Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

64.9 KB
Raw Blame
# Copyright 2026 The OpenSandbox Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

import asyncio
import gzip
import warnings
from types import SimpleNamespace
from typing import Any, cast

import httpx
import pytest
from fastapi import HTTPException
from fastapi.testclient import TestClient
from starlette.requests import ClientDisconnect
from starlette.types import Message
from websockets.exceptions import ConnectionClosedError, ConnectionClosedOK
from websockets.frames import Close, CloseCode
from websockets.typing import Origin

import opensandbox_server.api.proxy as proxy_api
from opensandbox_server.api import lifecycle
from opensandbox_server.api.schema import Endpoint
from opensandbox_server.middleware.auth import SANDBOX_API_KEY_HEADER
from opensandbox_server.services.constants import OPEN_SANDBOX_EGRESS_AUTH_HEADER, OPEN_SANDBOX_INGRESS_HEADER
from opensandbox_server.services.constants import OPEN_SANDBOX_SECURE_ACCESS_HEADER
from opensandbox_server.tenants.context import get_current_tenant
from opensandbox_server.tenants.models import TenantEntry


class _FakeStreamingResponse:
    def __init__(
        self,
        status_code: int = 200,
        headers: dict | list[tuple[str, str]] | None = None,
        chunks: list[bytes] | None = None,
        raw_chunks: list[bytes] | None = None,
    ):
        self.status_code = status_code
        self.headers = httpx.Headers(headers or {})
        self._chunks = chunks or []
        self._raw_chunks = raw_chunks if raw_chunks is not None else self._chunks
        self.aclose_called = False
        self.aiter_bytes_called = False
        self.aiter_raw_called = False

    async def aiter_bytes(self):
        self.aiter_bytes_called = True
        for chunk in self._chunks:
            yield chunk

    async def aiter_raw(self):
        self.aiter_raw_called = True
        for chunk in self._raw_chunks:
            yield chunk

    async def aclose(self):
        await asyncio.sleep(0)
        self.aclose_called = True


class _BlockingStreamingResponse(_FakeStreamingResponse):
    def __init__(self) -> None:
        super().__init__()
        self.body_started = asyncio.Event()

    async def aiter_raw(self):
        self.body_started.set()
        await asyncio.Future()
        yield b"unreachable"


class _FakeAsyncClient:
    def __init__(self):
        self.built = None
        self.response = _FakeStreamingResponse()
        self.connection_error: httpx.RequestError | None = None
        self.raise_generic_error = False

    def build_request(
        self,
        method: str,
        url: str,
        headers: dict,
        content,
        params: str | None = None,
    ):
        self.built = {
            "method": method,
            "url": url,
            "params": params,
            "headers": headers,
            "content": content,
        }
        return self.built

    async def send(self, req, stream: bool = True):
        if self.connection_error:
            raise self.connection_error
        if self.raise_generic_error:
            raise RuntimeError("unexpected proxy error")
        return self.response


def _set_http_client(client: TestClient, fake_client: _FakeAsyncClient) -> None:
    cast(Any, client.app).state.http_client = fake_client


class _FakeBackendWebSocket:
    def __init__(self, message: str = "backend-ready", subprotocol: str | None = "claw.v1"):
        self.message = message
        self.subprotocol = subprotocol
        self.sent: list[str | bytes] = []
        self.close_calls: list[tuple[int, str]] = []
        self._delivered = False

    async def send(self, payload: str | bytes) -> None:
        self.sent.append(payload)

    async def recv(self) -> str:
        if not self._delivered:
            self._delivered = True
            return self.message
        await asyncio.Future()
        raise AssertionError("unreachable")

    async def close(self, code: int = 1000, reason: str = "") -> None:
        self.close_calls.append((code, reason))


class _FakeWebSocketConnector:
    def __init__(self, backend: _FakeBackendWebSocket):
        self.backend = backend
        self.calls: list[dict] = []

    def __call__(self, uri: str, **kwargs):
        self.calls.append({"uri": uri, **kwargs})
        backend = self.backend

        class _ContextManager:
            async def __aenter__(self):
                return backend

            async def __aexit__(self, exc_type, exc, tb):
                return False

        return _ContextManager()


class _ClosingBackendWebSocket:
    def __init__(
        self,
        close_exception: ConnectionClosedError | ConnectionClosedOK,
    ) -> None:
        self._messages: list[str | bytes] = ["backend-text", b"\x00\x01"]
        self._close_exception = close_exception

    async def recv(self) -> str | bytes:
        if self._messages:
            return self._messages.pop(0)
        raise self._close_exception


class _DisconnectingClientWebSocket:
    """Client side that delivers one frame and then an ASGI ``websocket.disconnect``."""

    def __init__(self, disconnect_code: int | None, reason: str = "") -> None:
        message: dict[str, Any] = {"type": "websocket.disconnect", "reason": reason}
        if disconnect_code is not None:
            message["code"] = disconnect_code
        self._messages: list[dict[str, Any]] = [
            {"type": "websocket.receive", "text": "client-text"},
            message,
        ]

    async def receive(self) -> dict[str, Any]:
        return self._messages.pop(0)


class _RecordingBackendWebSocket:
    def __init__(self) -> None:
        self.sent: list[str | bytes] = []
        self.close_calls: list[tuple[int, str]] = []

    async def send(self, payload: str | bytes) -> None:
        self.sent.append(payload)

    async def close(self, code: int = 1000, reason: str = "") -> None:
        Close(code, reason).serialize()
        self.close_calls.append((code, reason))


class _RecordingClientWebSocket:
    def __init__(self) -> None:
        self.text_messages: list[str] = []
        self.binary_messages: list[bytes] = []
        self.close_calls: list[tuple[int, str]] = []

    async def send_text(self, payload: str) -> None:
        self.text_messages.append(payload)

    async def send_bytes(self, payload: bytes) -> None:
        self.binary_messages.append(payload)

    async def close(self, code: int, reason: str = "") -> None:
        Close(code, reason).serialize()
        self.close_calls.append((code, reason))


@pytest.mark.asyncio
@pytest.mark.parametrize(
    ("backend_close", "expected_code", "expected_reason"),
    [
        (ConnectionClosedError(None, None), 1011, ""),
        (
            ConnectionClosedError(Close(CloseCode.NO_STATUS_RCVD, ""), None),
            1011,
            "",
        ),
        (ConnectionClosedOK(Close(1000, "normal"), None), 1000, "normal"),
        (ConnectionClosedError(Close(4001, "application close"), None), 4001, "application close"),
    ],
)
async def test_relay_backend_messages_maps_non_transmittable_close_code(
    backend_close: ConnectionClosedError | ConnectionClosedOK,
    expected_code: int,
    expected_reason: str,
) -> None:
    websocket = _RecordingClientWebSocket()
    backend = _ClosingBackendWebSocket(backend_close)
    cancelled: list[bool] = []
    cancel_scope = SimpleNamespace(cancel=lambda: cancelled.append(True))

    await asyncio.wait_for(
        proxy_api._relay_backend_messages(
            cast(Any, websocket),
            cast(Any, backend),
            cast(Any, cancel_scope),
        ),
        timeout=0.5,
    )

    assert websocket.text_messages == ["backend-text"]
    assert websocket.binary_messages == [b"\x00\x01"]
    assert websocket.close_calls == [(expected_code, expected_reason)]
    assert cancelled == [True]


@pytest.mark.parametrize(
    ("backend_code", "expected_code"),
    [
        (None, 1000),
        (999, 1011),
        (1000, 1000),
        (1004, 1011),
        (1005, 1011),
        (1006, 1011),
        (1011, 1011),
        (1015, 1011),
        (2999, 1011),
        (3000, 3000),
        (4001, 4001),
        (4999, 4999),
        (5000, 1011),
    ],
)
def test_client_websocket_close_code_maps_only_transmittable_codes(
    backend_code: int | None,
    expected_code: int,
) -> None:
    assert proxy_api._client_websocket_close_code(backend_code) == expected_code


@pytest.mark.asyncio
@pytest.mark.parametrize(
    ("disconnect_code", "expected_code"),
    [
        (1000, 1000),
        (1001, 1001),
        (4001, 4001),
        (None, 1000),
        (1005, 1000),
        (1006, 1001),
    ],
)
async def test_relay_client_messages_maps_non_transmittable_disconnect_code(
    disconnect_code: int | None,
    expected_code: int,
) -> None:
    websocket = _DisconnectingClientWebSocket(disconnect_code)
    backend = _RecordingBackendWebSocket()
    cancelled: list[bool] = []
    cancel_scope = SimpleNamespace(cancel=lambda: cancelled.append(True))

    await asyncio.wait_for(
        proxy_api._relay_client_messages(
            cast(Any, websocket),
            cast(Any, backend),
            cast(Any, cancel_scope),
        ),
        timeout=0.5,
    )

    assert backend.sent == ["client-text"]
    assert backend.close_calls == [(expected_code, "")]
    assert cancelled == [True]


@pytest.mark.parametrize(
    ("client_code", "expected_code"),
    [
        (None, 1000),
        (999, 1001),
        (1000, 1000),
        (1004, 1001),
        (1005, 1000),
        (1006, 1001),
        (1011, 1011),
        (1015, 1001),
        (2999, 1001),
        (3000, 3000),
        (4001, 4001),
        (4999, 4999),
        (5000, 1001),
    ],
)
def test_backend_websocket_close_code_maps_only_transmittable_codes(
    client_code: int | None,
    expected_code: int,
) -> None:
    assert proxy_api._backend_websocket_close_code(client_code) == expected_code


def test_proxy_openapi_operation_ids_are_unique(client: TestClient) -> None:
    app = cast(Any, client.app)
    app.openapi_schema = None
    with warnings.catch_warnings(record=True) as caught:
        warnings.simplefilter("always")
        schema = app.openapi()

    proxy_paths = {
        "/sandboxes/{sandbox_id}/proxy/{port}",
        "/sandboxes/{sandbox_id}/proxy/{port}/{full_path}",
        "/v1/sandboxes/{sandbox_id}/proxy/{port}",
        "/v1/sandboxes/{sandbox_id}/proxy/{port}/{full_path}",
    }
    proxy_methods = {"get", "post", "put", "delete", "patch"}
    operation_ids = [
        schema["paths"][path][method]["operationId"]
        for path in proxy_paths
        for method in proxy_methods
    ]
    duplicate_warnings = [
        str(item.message)
        for item in caught
        if "Duplicate Operation ID" in str(item.message)
        and "proxy_sandbox_endpoint" in str(item.message)
    ]

    assert len(operation_ids) == 20
    assert len(set(operation_ids)) == len(operation_ids)
    assert duplicate_warnings == []


@pytest.mark.parametrize("prefix", ["", "/v1"])
@pytest.mark.parametrize("suffix", ["", "/{full_path}"])
@pytest.mark.parametrize("method", ["get", "post", "put", "delete", "patch"])
def test_proxy_openapi_describes_transparent_responses(
    client: TestClient,
    prefix: str,
    suffix: str,
    method: str,
) -> None:
    app = cast(Any, client.app)
    app.openapi_schema = None
    schema = app.openapi()
    path = f"{prefix}/sandboxes/{{sandbox_id}}/proxy/{{port}}{suffix}"
    responses = schema["paths"][path][method]["responses"]

    for status_code in ("default", "200"):
        assert responses[status_code]["description"]
        assert responses[status_code]["content"] == {"*/*": {}}
    assert responses["422"]["content"] == {
        "application/json": {"schema": {"$ref": "#/components/schemas/HTTPValidationError"}}
    }


@pytest.mark.parametrize(
    "request_path",
    [
        "/sandboxes/sbx-123/proxy/44772",
        "/sandboxes/sbx-123/proxy/44772/nested/path",
        "/v1/sandboxes/sbx-123/proxy/44772",
        "/v1/sandboxes/sbx-123/proxy/44772/nested/path",
    ],
)
@pytest.mark.parametrize(
    ("status_code", "content_type", "body"),
    [
        (200, "text/html; charset=utf-8", b"<h1>backend</h1>"),
        (200, "text/event-stream", b"data: backend\n\n"),
        (302, "text/plain; charset=utf-8", b"redirect"),
        (405, "application/json", b'{"error":"backend method"}'),
        (503, "application/octet-stream", b"\x00\xffbackend"),
    ],
)
def test_proxy_preserves_backend_status_body_and_media_type(
    client: TestClient,
    auth_headers: dict,
    monkeypatch: pytest.MonkeyPatch,
    request_path: str,
    status_code: int,
    content_type: str,
    body: bytes,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(
            sandbox_id: str,
            port: int,
            resolve_internal: bool = False,
            use_proxy_host: bool = False,
        ) -> Endpoint:
            return Endpoint(endpoint="127.0.0.1:44772")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=status_code,
        headers={"content-type": content_type},
        chunks=[body],
    )
    _set_http_client(client, fake_client)

    response = client.get(request_path, headers=auth_headers, follow_redirects=False)

    assert response.status_code == status_code
    assert response.content == body
    assert response.headers["content-type"] == content_type
    assert fake_client.response.aclose_called is True


@pytest.mark.parametrize("prefix", ["", "/v1"])
@pytest.mark.parametrize("suffix", ["", "/nested/path"])
def test_proxy_invalid_port_preserves_validation_error(
    client: TestClient,
    auth_headers: dict,
    prefix: str,
    suffix: str,
) -> None:
    response = client.get(
        f"{prefix}/sandboxes/sbx-123/proxy/not-a-port{suffix}", headers=auth_headers
    )

    assert response.status_code == 422
    assert response.headers["content-type"] == "application/json"


@pytest.mark.parametrize(
    "request_path",
    [
        "/sandboxes/sbx-123/proxy/44772",
        "/sandboxes/sbx-123/proxy/44772/nested/path",
        "/v1/sandboxes/sbx-123/proxy/44772",
        "/v1/sandboxes/sbx-123/proxy/44772/nested/path",
    ],
)
def test_proxy_method_not_allowed_lists_all_supported_methods(
    client: TestClient,
    auth_headers: dict,
    request_path: str,
) -> None:
    response = client.options(
        request_path,
        headers=auth_headers,
    )

    assert response.status_code == 405
    assert set(response.headers["allow"].split(", ")) == {
        "GET",
        "POST",
        "PUT",
        "DELETE",
        "PATCH",
    }


def test_proxy_forwards_filtered_headers_and_query(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=201,
        headers={"x-backend": "yes"},
        chunks=[b"proxy-ok"],
    )
    _set_http_client(client, fake_client)

    headers = {
        **auth_headers,
        "Authorization": "Bearer top-secret",
        "Cookie": "sid=secret",
        "Connection": "keep-alive, X-Hop-Temp",
        "Upgrade": "h2c",
        "Trailer": "X-Checksum",
        "X-Hop-Temp": "drop-me",
        "X-Trace": "trace-1",
        "Forwarded": "for=attacker;proto=https",
        "X-Forwarded-For": "203.0.113.99",
        "X-Forwarded-Host": "attacker.example",
        "X-Forwarded-Proto": "https",
        "X-Real-Ip": "203.0.113.99",
    }

    response = client.post(
        "/v1/sandboxes/sbx-123/proxy/44772/api/run",
        params={"q": "search"},
        headers=headers,
        content=b'{"hello":"world"}',
    )

    assert response.status_code == 201
    assert response.content == b"proxy-ok"
    assert response.headers.get("x-backend") == "yes"

    assert fake_client.built is not None
    assert fake_client.built["method"] == "POST"
    assert fake_client.built["url"] == "http://10.57.1.91:40109/api/run?q=search"
    assert fake_client.built["params"] is None
    forwarded_headers = fake_client.built["headers"]
    lowered_headers = {k.lower(): v for k, v in forwarded_headers.items()}
    assert "host" not in lowered_headers
    assert "connection" not in lowered_headers
    assert "upgrade" not in lowered_headers
    assert "trailer" not in lowered_headers
    assert "authorization" not in lowered_headers
    assert "cookie" not in lowered_headers
    assert SANDBOX_API_KEY_HEADER.lower() not in lowered_headers
    assert "x-hop-temp" not in lowered_headers
    assert lowered_headers.get("x-trace") == "trace-1"
    assert "forwarded" not in lowered_headers
    assert "x-real-ip" not in lowered_headers
    assert lowered_headers.get("x-forwarded-proto") == "http"
    assert lowered_headers.get("x-forwarded-host") != "attacker.example"
    assert lowered_headers.get("x-forwarded-for") != "203.0.113.99"
    assert fake_client.response.aclose_called is True


def test_proxy_honors_configured_resolve_internal_false(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
):
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is False
            assert use_proxy_host is True
            return Endpoint(endpoint="127.0.0.1:51999")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    monkeypatch.setattr(
        proxy_api,
        "get_config",
        lambda: SimpleNamespace(proxy=SimpleNamespace(resolve_internal=False)),
    )

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={},
        chunks=[b"ok"],
    )
    _set_http_client(client, fake_client)

    response = client.get("/v1/sandboxes/sbx-123/proxy/44772/status", headers=auth_headers)
    assert response.status_code == 200
    assert fake_client.built is not None
    assert fake_client.built["url"] == "http://127.0.0.1:51999/status"


def test_proxy_preserves_origin_date_and_filters_server_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(endpoint="backend.example:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    origin_date = "Wed, 21 Oct 2015 07:28:00 GMT"
    fake_client.response = _FakeStreamingResponse(
        headers={
            "Date": origin_date,
            "Server": "backend-server",
            "X-Backend": "yes",
        },
        chunks=[b"proxy-ok"],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772",
        headers=auth_headers,
    )

    assert response.status_code == 200
    assert response.headers.get("x-backend") == "yes"
    assert response.headers.get("date") == origin_date
    assert "server" not in response.headers


@pytest.mark.parametrize(
    ("request_path", "location", "expected_location"),
    [
        (
            "/v1/sandboxes/sbx-123/proxy/44772/",
            "/login?next=%2F",
            "/v1/sandboxes/sbx-123/proxy/44772/login?next=%2F",
        ),
        (
            "/sandboxes/sbx-123/proxy/44772/",
            "/login?next=%2F",
            "/sandboxes/sbx-123/proxy/44772/login?next=%2F",
        ),
        (
            "/v1/sandboxes/sbx-123/proxy/44772/nested/page",
            "/login?next=%2F",
            "/v1/sandboxes/sbx-123/proxy/44772/login?next=%2F",
        ),
        ("/v1/sandboxes/sbx-123/proxy/44772/", "login?next=%2F", "login?next=%2F"),
        (
            "/v1/sandboxes/sbx-123/proxy/44772/",
            "https://example.com/login",
            "https://example.com/login",
        ),
        (
            "/v1/sandboxes/sbx-123/proxy/44772/",
            "//example.com/login",
            "//example.com/login",
        ),
        ("/v1/sandboxes/sbx-123/proxy/44772/", "?next=%2F", "?next=%2F"),
    ],
)
def test_proxy_rewrites_only_root_relative_redirects(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    request_path: str,
    location: str,
    expected_location: str,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(endpoint="backend.example:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=302,
        headers={"Location": location},
    )
    _set_http_client(client, fake_client)

    response = client.get(
        request_path,
        headers=auth_headers,
        follow_redirects=False,
    )

    assert response.status_code == 302
    assert response.headers["location"] == expected_location


def test_proxy_rewrites_root_relative_redirect_with_server_eip_path(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(endpoint="backend.example:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    monkeypatch.setattr(
        lifecycle,
        "get_config",
        lambda: SimpleNamespace(
            server=SimpleNamespace(eip="sandbox.example.com/opensandbox/")
        ),
    )

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=302,
        headers={"Location": "/login?next=%2F"},
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/",
        headers=auth_headers,
        follow_redirects=False,
    )

    assert response.status_code == 302
    assert (
        response.headers["location"]
        == "/opensandbox/sandboxes/sbx-123/proxy/44772/login?next=%2F"
    )


def test_proxy_root_path_forwards_endpoint_headers_and_query(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(
                endpoint="10.57.1.91:40109/base",
                headers={OPEN_SANDBOX_INGRESS_HEADER: "sbx-123-44772"},
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(chunks=[b"root-ok"])
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772",
        params={"q": "search"},
        headers={**auth_headers, "X-Trace": "trace-root"},
    )

    assert response.status_code == 200
    assert response.content == b"root-ok"
    assert fake_client.built is not None
    assert fake_client.built["url"] == "http://10.57.1.91:40109/base?q=search"
    assert fake_client.built["params"] is None
    lowered_headers = {
        key.lower(): value for key, value in fake_client.built["headers"].items()
    }
    assert lowered_headers["opensandbox-ingress-to"] == "sbx-123-44772"
    assert lowered_headers["x-trace"] == "trace-root"


def test_proxy_rejects_missing_secure_access_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(
                endpoint="10.57.1.91:40109/base",
                headers={
                    OPEN_SANDBOX_INGRESS_HEADER: "sbx-123-44772",
                    OPEN_SANDBOX_SECURE_ACCESS_HEADER: "secure-token",
                },
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(chunks=[b"root-ok"])
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772",
        params={"q": "search"},
        headers={**auth_headers, "X-Trace": "trace-root"},
    )

    assert response.status_code == 401
    assert fake_client.built is None  # request was never forwarded


def test_proxy_rejects_mismatched_secure_access_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(
                endpoint="10.57.1.91:40109/base",
                headers={
                    OPEN_SANDBOX_INGRESS_HEADER: "sbx-123-44772",
                    OPEN_SANDBOX_SECURE_ACCESS_HEADER: "server-side-token",
                },
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(chunks=[b"root-ok"])
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772",
        headers={
            **auth_headers,
            OPEN_SANDBOX_SECURE_ACCESS_HEADER: "wrong-token",
        },
    )

    assert response.status_code == 401
    assert fake_client.built is None  # request was never forwarded


def test_proxy_allows_valid_secure_access_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    """Valid secure-access token passes; header is stripped from forwarded request."""
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(
                endpoint="10.57.1.91:40109/base",
                headers={
                    OPEN_SANDBOX_INGRESS_HEADER: "sbx-123-44772",
                    OPEN_SANDBOX_SECURE_ACCESS_HEADER: "server-side-token",
                },
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(chunks=[b"root-ok"])
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772",
        headers={
            **auth_headers,
            OPEN_SANDBOX_SECURE_ACCESS_HEADER: "server-side-token",
        },
    )

    assert response.status_code == 200
    assert fake_client.built is not None
    lowered_headers = {
        key.lower(): value for key, value in fake_client.built["headers"].items()
    }
    # Token is stripped from forwarded headers — sandbox app should not receive it
    assert OPEN_SANDBOX_SECURE_ACCESS_HEADER.lower() not in lowered_headers
    # Other endpoint headers are still forwarded
    assert lowered_headers["opensandbox-ingress-to"] == "sbx-123-44772"


def test_proxy_forwards_get_request_with_query_params(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    """
    This test verifies the fix for issue #484 where GET requests with query
    parameters were failing with 400 MISSING_QUERY when using use_server_proxy.
    The query string must reach the backend URL.
    """
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is True
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={"content-type": "application/json"},
        chunks=[b'[{"name":"file.txt","size":100}]'],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/files/search",
        params={"path": "/workspace"},
        headers=auth_headers,
    )

    assert response.status_code == 200
    assert fake_client.built is not None
    assert fake_client.built["method"] == "GET"
    assert fake_client.built["url"] == "http://10.57.1.91:40109/files/search?path=%2Fworkspace"
    assert fake_client.built["params"] is None
    assert fake_client.built["content"] is None


def _record_backend_raw_paths(client: TestClient, monkeypatch) -> list[bytes]:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    seen: list[bytes] = []

    class _Body(httpx.AsyncByteStream):
        async def __aiter__(self):
            yield b"ok"

    def handler(request: httpx.Request) -> httpx.Response:
        seen.append(request.url.raw_path)
        return httpx.Response(200, stream=_Body())

    _set_http_client(client, cast(Any, httpx.AsyncClient(transport=httpx.MockTransport(handler))))
    return seen


def test_proxy_forwards_raw_query_string_unchanged(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    seen = _record_backend_raw_paths(client, monkeypatch)

    # Repeated keys out of order, a valueless flag, a non-UTF-8 escape, a
    # literal ';' and a %20 space must all reach the backend byte for byte.
    raw_query = "b=2&a=1&b=3&uploads&sig=%E9%FF&s=1;2&q=hello%20world"
    response = client.get(
        f"/v1/sandboxes/sbx-123/proxy/44772/files/search?{raw_query}",
        headers=auth_headers,
    )

    assert response.status_code == 200
    assert seen == [f"/files/search?{raw_query}".encode("ascii")]


@pytest.mark.parametrize("prefix", ["/v1", ""])
@pytest.mark.parametrize(
    "suffix",
    [
        "api/contents/plain.txt?type=file",
        "api/contents/a%2Fb",
        "api/contents/a%3Fb.txt",
        "api/contents/a%23b.txt?type=file",
        "api/contents/100%25.txt",
        "api/contents/caf%E9.txt",
        "api/contents/a/%2E%2E/b",
    ],
)
def test_proxy_forwards_encoded_path_unchanged(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    prefix: str,
    suffix: str,
) -> None:
    seen = _record_backend_raw_paths(client, monkeypatch)

    response = client.get(f"{prefix}/sandboxes/sbx-123/proxy/8888/{suffix}", headers=auth_headers)

    assert response.status_code == 200
    assert seen == [f"/{suffix}".encode("ascii")]


def test_proxy_reencodes_decoded_path_when_raw_suffix_does_not_match(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    seen = _record_backend_raw_paths(client, monkeypatch)

    # The encoded '/' in the sandbox id shifts the decoded match to port 8888,
    # so the raw tail after the same number of '/' is not the matched suffix.
    response = client.get(
        "/v1/sandboxes/sbx%2Fproxy%2F8888/proxy/9999/x%3Fy",
        headers=auth_headers,
    )

    assert response.status_code == 200
    assert seen == [b"/proxy/9999/x%3Fy"]


@pytest.mark.parametrize(
    ("path", "query", "expected"),
    [
        ("a#frag", "x=1", "http://10.57.1.91:40109/a"),
        ("a", "x=1#frag", "http://10.57.1.91:40109/a?x=1"),
        ("a%23b", "x=1", "http://10.57.1.91:40109/a%23b?x=1"),
    ],
)
def test_build_proxy_target_url_drops_raw_fragment(path: str, query: str, expected: str) -> None:
    endpoint = Endpoint(endpoint="10.57.1.91:40109")

    assert proxy_api._build_proxy_target_url(endpoint, path, query) == expected


def test_proxy_forwards_delete_request_with_body(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={"content-type": "application/json"},
        chunks=[b'{"deleted":true}'],
    )
    _set_http_client(client, fake_client)

    response = client.request(
        "DELETE",
        "/v1/sandboxes/sbx-123/proxy/44772/resources",
        headers=auth_headers,
        content=b'{"id": "resource-123"}',
    )

    assert response.status_code == 200
    assert fake_client.built is not None
    assert fake_client.built["method"] == "DELETE"
    assert fake_client.built["content"] is not None


def test_proxy_filters_response_hop_by_hop_headers(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert resolve_internal is True
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={
            "x-backend": "yes",
            "Connection": "keep-alive, X-Hop-Temp",
            "Keep-Alive": "timeout=5",
            "Trailer": "X-Checksum",
            "X-Hop-Temp": "drop-me",
        },
        chunks=[b"proxy-ok"],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/healthz",
        headers=auth_headers,
    )

    assert response.status_code == 200
    assert response.content == b"proxy-ok"
    assert response.headers.get("x-backend") == "yes"
    assert response.headers.get("connection") is None
    assert response.headers.get("keep-alive") is None
    assert response.headers.get("trailer") is None
    assert response.headers.get("x-hop-temp") is None


@pytest.mark.parametrize("status_code", [200, 302, 400])
def test_proxy_preserves_repeated_response_headers(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    status_code: int,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(*args, **kwargs) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    cookies = [
        "session=abc; Path=/; HttpOnly; Expires=Wed, 09 Jun 2027 10:18:14 GMT",
        "theme=dark; Path=/; SameSite=Lax",
    ]
    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=status_code,
        headers=[
            ("Set-Cookie", cookies[0]),
            ("set-cookie", cookies[1]),
            ("X-Backend", "first"),
            ("x-backend", "second"),
            ("Connection", "X-Hop-One"),
            ("connection", "X-Hop-Two"),
            ("X-Hop-One", "drop-first"),
            ("x-hop-one", "drop-second"),
            ("X-Hop-Two", "drop-third"),
            ("Server", "backend-one"),
            ("server", "backend-two"),
            ("Location", "/login"),
        ],
        chunks=[b"proxy-ok"],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/healthz",
        headers=auth_headers,
        follow_redirects=False,
    )

    assert response.status_code == status_code
    assert response.content == b"proxy-ok"
    assert response.headers.get_list("set-cookie") == cookies
    assert response.headers.get_list("x-backend") == ["first", "second"]
    assert response.headers["location"] == "/v1/sandboxes/sbx-123/proxy/44772/login"
    for name in ("connection", "x-hop-one", "x-hop-two", "server"):
        assert name not in response.headers
    assert fake_client.response.aclose_called is True


def test_proxy_streams_raw_body_for_content_encoded_response(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert resolve_internal is True
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService)

    decoded_body = b"<html>vnc</html>"
    encoded_body = gzip.compress(decoded_body)
    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={
            "content-type": "text/html",
            "content-encoding": "gzip",
        },
        chunks=[decoded_body],
        raw_chunks=[encoded_body],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/8080/vnc/index.html",
        headers={**auth_headers, "Accept-Encoding": "gzip"},
    )

    assert response.status_code == 200
    assert response.headers.get("content-encoding") == "gzip"
    assert response.content == decoded_body
    assert fake_client.response.aiter_raw_called is True
    assert fake_client.response.aiter_bytes_called is False
    assert fake_client.response.aclose_called is True


def test_proxy_closes_backend_response_when_downstream_rejects_headers() -> None:
    """A disconnect before body iteration must not retain the backend connection."""

    async def run() -> None:
        backend_response = _FakeStreamingResponse()
        response = proxy_api._ProxyStreamingResponse(
            cast(httpx.Response, backend_response),
            status_code=200,
            raw_headers=[],
        )

        async def receive() -> Message:
            return {"type": "http.disconnect"}

        async def reject_response_start(message: Message) -> None:
            assert message["type"] == "http.response.start"
            raise ConnectionError("downstream disconnected")

        try:
            await response(
                {"type": "http", "asgi": {"spec_version": "2.4"}},
                receive,
                reject_response_start,
            )
        except ClientDisconnect:
            pass
        else:
            raise AssertionError("expected the downstream send to fail")

        assert backend_response.aclose_called is True

    asyncio.run(run())


def test_proxy_closes_backend_response_when_stream_is_cancelled() -> None:
    """Task cancellation must not interrupt returning the backend connection."""

    async def run() -> None:
        backend_response = _BlockingStreamingResponse()
        response = proxy_api._ProxyStreamingResponse(
            cast(httpx.Response, backend_response),
            status_code=200,
            raw_headers=[],
        )

        async def send(message: Message) -> None:
            return None

        async def receive() -> Message:
            return {"type": "http.disconnect"}

        task = asyncio.create_task(
            response(
                {"type": "http", "asgi": {"spec_version": "2.4"}},
                receive,
                send,
            )
        )
        await backend_response.body_started.wait()
        task.cancel()

        try:
            await task
        except asyncio.CancelledError:
            pass
        else:
            raise AssertionError("expected stream task cancellation")

        assert backend_response.aclose_called is True

    asyncio.run(run())


def test_proxy_rejects_websocket_upgrade(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    _set_http_client(client, _FakeAsyncClient())

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/ws",
        headers={**auth_headers, "Upgrade": "websocket"},
    )

    assert response.status_code == 400
    assert response.json()["message"] == "Websocket upgrade is not supported yet"


def test_proxy_rejects_websocket_upgrade_for_post_and_mixed_case_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    _set_http_client(client, _FakeAsyncClient())

    response = client.post(
        "/v1/sandboxes/sbx-123/proxy/44772/ws",
        headers={**auth_headers, "Upgrade": "WebSocket"},
        content=b"{}",
    )

    assert response.status_code == 400
    assert response.json()["message"] == "Websocket upgrade is not supported yet"


def _on_event_loop() -> bool:
    try:
        asyncio.get_running_loop()
    except RuntimeError:
        return False
    return True


def test_proxy_resolves_endpoint_off_the_event_loop(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    # get_endpoint does blocking Docker/Kubernetes I/O; running it on the event
    # loop would stall every other request while it waits.
    on_loop: list[bool] = []

    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            on_loop.append(_on_event_loop())
            raise HTTPException(status_code=404, detail={"code": "NOT_FOUND", "message": "gone"})

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    response = client.get("/v1/sandboxes/sbx-123/proxy/44772/healthz", headers=auth_headers)

    assert response.status_code == 404
    assert on_loop == [False]


def test_proxy_websocket_resolves_endpoint_off_the_event_loop(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    on_loop: list[bool] = []

    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            on_loop.append(_on_event_loop())
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    monkeypatch.setattr(proxy_api.websockets, "connect", _FakeWebSocketConnector(_FakeBackendWebSocket()))

    with client.websocket_connect(
        "/v1/sandboxes/sbx-123/proxy/44772/ws", headers=auth_headers
    ) as websocket:
        assert websocket.receive_text() == "backend-ready"

    assert on_loop == [False]


def test_proxy_websocket_endpoint_lookup_sees_the_tenant(
    client: TestClient,
    monkeypatch,
) -> None:
    # The lookup runs in a worker thread; it must still see the tenant that
    # authentication set, or it would resolve in the wrong namespace.
    tenant = TenantEntry(name="team-a", namespace="ns-a", api_keys=("key-a",))

    class Provider:
        @staticmethod
        def lookup(api_key: str) -> TenantEntry | None:
            return tenant if api_key == "key-a" else None

    seen: list[TenantEntry | None] = []

    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            seen.append(get_current_tenant())
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(client.app.state, "tenant_provider", Provider(), raising=False)
    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    monkeypatch.setattr(proxy_api.websockets, "connect", _FakeWebSocketConnector(_FakeBackendWebSocket()))

    with client.websocket_connect(
        "/v1/sandboxes/sbx-123/proxy/44772/ws", headers={SANDBOX_API_KEY_HEADER: "key-a"}
    ) as websocket:
        assert websocket.receive_text() == "backend-ready"

    assert seen == [tenant]


@pytest.mark.parametrize("configured_resolve_internal", [True, False])
def test_proxy_websocket_relays_messages_and_forwards_safe_headers(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    configured_resolve_internal: bool,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert sandbox_id == "sbx-123"
            assert port == 44772
            assert resolve_internal is configured_resolve_internal
            assert use_proxy_host is (not configured_resolve_internal)
            return Endpoint(
                endpoint="10.57.1.91:40109/proxy/44772",
                headers={
                    OPEN_SANDBOX_INGRESS_HEADER: "sbx-123-44772",
                    "X-Forwarded-Proto": "https",
                    "X-Forwarded-For": "198.51.100.20",
                },
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    monkeypatch.setattr(
        proxy_api,
        "get_config",
        lambda: SimpleNamespace(
            proxy=SimpleNamespace(resolve_internal=configured_resolve_internal)
        ),
    )
    backend = _FakeBackendWebSocket()
    connector = _FakeWebSocketConnector(backend)
    monkeypatch.setattr(proxy_api.websockets, "connect", connector)

    with client.websocket_connect(
        "/v1/sandboxes/sbx-123/proxy/44772/ws?token=abc",
        headers={
            **auth_headers,
            "Authorization": "Bearer top-secret",
            "Cookie": "sid=secret",
            "Origin": "https://ui.example.com",
            "X-Trace": "trace-ws",
            "Forwarded": "for=attacker;proto=https",
            "X-Forwarded-For": "203.0.113.99",
            "X-Forwarded-Host": "attacker.example",
            "X-Forwarded-Proto": "https",
            "X-Real-Ip": "203.0.113.99",
        },
        subprotocols=["claw.v1"],
    ) as websocket:
        assert websocket.receive_text() == "backend-ready"
        websocket.send_text("client-ready")

    assert backend.sent == ["client-ready"]
    assert backend.close_calls[0][0] == 1000

    call = connector.calls[0]
    assert call["uri"] == "ws://10.57.1.91:40109/proxy/44772/ws?token=abc"
    assert call["origin"] == Origin("https://ui.example.com")
    assert call["subprotocols"] == ["claw.v1"]
    lowered_headers = {
        key.lower(): value for key, value in (call["additional_headers"] or {}).items()
    }
    assert "authorization" not in lowered_headers
    assert "cookie" not in lowered_headers
    assert "origin" not in lowered_headers
    assert "forwarded" not in lowered_headers
    assert "x-real-ip" not in lowered_headers
    assert lowered_headers["x-forwarded-proto"] == "http"
    assert lowered_headers["x-forwarded-host"] == "testserver"
    assert lowered_headers["x-forwarded-for"] == "testclient"
    assert lowered_headers["opensandbox-ingress-to"] == "sbx-123-44772"
    assert lowered_headers["x-trace"] == "trace-ws"


@pytest.mark.parametrize("suffix", ["ws/a%2Fb?token=abc", "ws/a%23b?token=abc"])
def test_proxy_websocket_forwards_encoded_path_unchanged(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    suffix: str,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    connector = _FakeWebSocketConnector(_FakeBackendWebSocket())
    monkeypatch.setattr(proxy_api.websockets, "connect", connector)

    with client.websocket_connect(
        f"/v1/sandboxes/sbx-123/proxy/8888/{suffix}", headers=auth_headers
    ) as websocket:
        assert websocket.receive_text() == "backend-ready"

    assert connector.calls[0]["uri"] == f"ws://10.57.1.91:40109/{suffix}"


@pytest.mark.parametrize(
    "connection_error",
    [httpx.ConnectError("connection refused"), httpx.ConnectTimeout("connection timed out")],
)
def test_proxy_maps_connect_failure_to_502(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    connection_error: httpx.RequestError,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109", headers={"X-Endpoint-Token": "endpoint-secret"})

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    fake_client = _FakeAsyncClient()
    fake_client.connection_error = connection_error
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/healthz",
        headers=auth_headers,
    )

    assert response.status_code == 502
    payload = response.json()
    assert payload["code"] == "BACKEND_CONNECTION_FAILED"
    assert "Could not connect to the backend sandbox 10.57.1.91:40109" in payload["message"]
    assert "endpoint-secret" not in payload["message"]


@pytest.mark.parametrize(
    ("backend_error", "expected_status", "expected_code"),
    [
        (httpx.ReadTimeout("read timed out"), 504, "BACKEND_TIMEOUT"),
        (httpx.WriteTimeout("write timed out"), 504, "BACKEND_TIMEOUT"),
        (httpx.RemoteProtocolError("server disconnected"), 502, "BACKEND_RESPONSE_FAILED"),
        (httpx.ReadError("connection reset"), 502, "BACKEND_RESPONSE_FAILED"),
        (httpx.WriteError("broken pipe"), 502, "BACKEND_RESPONSE_FAILED"),
    ],
)
def test_proxy_maps_backend_failure_after_connect_to_gateway_error(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
    backend_error: httpx.RequestError,
    expected_status: int,
    expected_code: str,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109", headers={"X-Endpoint-Token": "endpoint-secret"})

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    fake_client = _FakeAsyncClient()
    fake_client.connection_error = backend_error
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/healthz",
        headers=auth_headers,
    )

    assert response.status_code == expected_status
    payload = response.json()
    assert payload["code"] == expected_code
    assert "10.57.1.91:40109" in payload["message"]
    assert "endpoint-secret" not in payload["message"]


def test_proxy_maps_unexpected_error_to_500(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            return Endpoint(endpoint="10.57.1.91:40109")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    fake_client = _FakeAsyncClient()
    fake_client.raise_generic_error = True
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/44772/healthz",
        headers=auth_headers,
    )

    assert response.status_code == 500
    assert "An internal error occurred in the proxy" in response.json()["message"]


def test_proxy_forwards_18080_without_server_side_egress_auth_check(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert port == 18080
            assert resolve_internal is True
            return Endpoint(
                endpoint="10.57.1.91:18080",
                headers={OPEN_SANDBOX_EGRESS_AUTH_HEADER: "endpoint-token"},
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())
    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=401,
        headers={"content-type": "application/json"},
        chunks=[b'{"code":"UNAUTHORIZED"}'],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/18080/policy",
        headers=auth_headers,
    )

    assert response.status_code == 401
    assert response.json()["code"] == "UNAUTHORIZED"
    assert fake_client.built is not None
    assert fake_client.built["url"] == "http://10.57.1.91:18080/policy"
    lowered_headers = {k.lower(): v for k, v in fake_client.built["headers"].items()}
    assert OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower() not in lowered_headers


def test_proxy_forwards_egress_auth_header_for_18080(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert port == 18080
            assert resolve_internal is True
            return Endpoint(endpoint="10.57.1.91:18080")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={"content-type": "application/json"},
        chunks=[b'{"status":"ok"}'],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/18080/policy",
        headers={**auth_headers, OPEN_SANDBOX_EGRESS_AUTH_HEADER: "egress-token"},
    )

    assert response.status_code == 200
    assert fake_client.built is not None
    lowered_headers = {k.lower(): v for k, v in fake_client.built["headers"].items()}
    assert lowered_headers[OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower()] == "egress-token"


def test_proxy_active_credential_vault_returns_sidecar_forbidden(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert port == 18080
            assert resolve_internal is True
            return Endpoint(endpoint="10.57.1.91:18080")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=403,
        headers={"content-type": "text/plain"},
        chunks=[b"forbidden\n"],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/proxy/18080/credential-vault/_active",
        headers={**auth_headers, OPEN_SANDBOX_EGRESS_AUTH_HEADER: "egress-token"},
    )

    assert response.status_code == 403
    assert response.content == b"forbidden\n"
    assert fake_client.built is not None
    assert fake_client.built["url"] == "http://10.57.1.91:18080/credential-vault/_active"


def test_networkpolicy_route_forwards_egress_auth_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert port == 18080
            return Endpoint(
                endpoint="10.57.1.91:18080",
                headers={OPEN_SANDBOX_EGRESS_AUTH_HEADER: "injected-egress-token"},
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={"content-type": "application/json"},
        chunks=[b'{"status":"ok"}'],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/networkpolicy",
        headers={
            **auth_headers,
            OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower(): "caller-fake-token",
        },
    )

    assert response.status_code == 200
    assert fake_client.built is not None
    assert fake_client.built["url"] == "http://10.57.1.91:18080/policy"
    # Ensure caller-supplied header was completely replaced and does not duplicate
    egress_headers = [
        (k, v)
        for k, v in fake_client.built["headers"].items()
        if k.lower() == OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower()
    ]
    assert len(egress_headers) == 1
    assert egress_headers[0][1] == "injected-egress-token"


def test_credential_vault_route_forwards_egress_auth_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    """The server-routed credential vault proxies the sidecar surface with the
    endpoint-resolved egress-auth token (internal=True), replacing any
    caller-supplied value."""

    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert port == 18080
            return Endpoint(
                endpoint="10.57.1.91:18080",
                headers={OPEN_SANDBOX_EGRESS_AUTH_HEADER: "injected-egress-token"},
            )

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=200,
        headers={"content-type": "application/json"},
        chunks=[b'{"revision":1}'],
    )
    _set_http_client(client, fake_client)

    response = client.get(
        "/v1/sandboxes/sbx-123/credential-vault",
        headers={
            **auth_headers,
            OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower(): "caller-fake-token",
        },
    )

    assert response.status_code == 200
    assert fake_client.built is not None
    assert fake_client.built["url"] == "http://10.57.1.91:18080/credential-vault"
    egress_headers = [
        (k, v)
        for k, v in fake_client.built["headers"].items()
        if k.lower() == OPEN_SANDBOX_EGRESS_AUTH_HEADER.lower()
    ]
    assert len(egress_headers) == 1
    assert egress_headers[0][1] == "injected-egress-token"


def test_credential_vault_route_forwards_exchange_payload_verbatim(
    client: TestClient,
    auth_headers: dict,
    monkeypatch,
) -> None:
    """OSEP-0025: the server shape gate accepts exchange sources and typeless
    auth (previously 422) and the sidecar proxy forwards the body verbatim —
    semantic validation stays with the egress."""

    class StubService:
        @staticmethod
        def get_endpoint(sandbox_id: str, port: int, resolve_internal: bool = False, use_proxy_host: bool = False) -> Endpoint:
            assert port == 18080
            return Endpoint(endpoint="10.57.1.91:18080")

    monkeypatch.setattr(lifecycle, "sandbox_service", StubService())

    fake_client = _FakeAsyncClient()
    fake_client.response = _FakeStreamingResponse(
        status_code=201,
        headers={"content-type": "application/json"},
        chunks=[b'{"revision":1,"credentials":[],"bindings":[]}'],
    )
    _set_http_client(client, fake_client)

    payload = {
        "credentials": [
            {
                "name": "spi-signer",
                "source": {"type": "exchange", "endpoint": "unix:///run/spi/spi.sock"},
            }
        ],
        "bindings": [
            {
                "name": "internal-api",
                "match": {"hosts": ["*.internal.example.com"]},
                "auth": {"credential": "spi-signer"},
            }
        ],
    }
    response = client.post(
        "/v1/sandboxes/sbx-123/credential-vault",
        headers=auth_headers,
        json=payload,
    )

    assert response.status_code == 201
    assert fake_client.built is not None
    assert fake_client.built["method"] == "POST"
    assert fake_client.built["url"] == "http://10.57.1.91:18080/credential-vault"
    # The body rides the raw request stream (verbatim passthrough like every
    # other proxied body); reaching the sidecar at all proves the shape gate
    # accepted the exchange payload.
    assert fake_client.built["content"] is not None

class _StubRenewCoordinator:
    def __init__(self) -> None:
        self.scheduled: list[str] = []

    def schedule(self, sandbox_id: str) -> None:
        self.scheduled.append(sandbox_id)


def _install_renew_coordinator(client: TestClient) -> _StubRenewCoordinator:
    coordinator = _StubRenewCoordinator()
    cast(Any, client.app).state.proxy_renew_coordinator = coordinator
    return coordinator


def _proxy_ok_fake() -> _FakeAsyncClient:
    fake = _FakeAsyncClient()
    fake.response = _FakeStreamingResponse(
        status_code=200, headers={"content-type": "text/plain"}, chunks=[b"ok"]
    )
    return fake


class _RenewStubService:
    @staticmethod
    def get_endpoint(
        sandbox_id: str,
        port: int,
        resolve_internal: bool = False,
        use_proxy_host: bool = False,
    ) -> Endpoint:
        return Endpoint(endpoint="127.0.0.1:44772")


@pytest.mark.parametrize("prefix", ["", "/v1"])
def test_proxy_renew_intent_scheduled_by_default(
    client: TestClient,
    auth_headers: dict,
    monkeypatch: pytest.MonkeyPatch,
    prefix: str,
) -> None:
    monkeypatch.setattr(lifecycle, "sandbox_service", _RenewStubService())
    fake_client = _proxy_ok_fake()
    _set_http_client(client, fake_client)
    coordinator = _install_renew_coordinator(client)

    response = client.get(
        f"{prefix}/sandboxes/sbx-renew/proxy/3000/status",
        headers=auth_headers,
        follow_redirects=False,
    )

    assert response.status_code == 200
    assert coordinator.scheduled == ["sbx-renew"]


@pytest.mark.parametrize("prefix", ["", "/v1"])
def test_proxy_renew_skip_header_suppresses_intent_and_strips_header(
    client: TestClient,
    auth_headers: dict,
    monkeypatch: pytest.MonkeyPatch,
    prefix: str,
) -> None:
    monkeypatch.setattr(lifecycle, "sandbox_service", _RenewStubService())
    fake_client = _proxy_ok_fake()
    _set_http_client(client, fake_client)
    coordinator = _install_renew_coordinator(client)

    response = client.get(
        f"{prefix}/sandboxes/sbx-renew/proxy/3000/status",
        headers={**auth_headers, "OpenSandbox-Access-Renew": "skip"},
        follow_redirects=False,
    )

    assert response.status_code == 200
    assert coordinator.scheduled == []
    forwarded = fake_client.built["headers"]
    assert all(k.lower() != "opensandbox-access-renew" for k in forwarded)


@pytest.mark.parametrize("prefix", ["", "/v1"])
def test_proxy_renew_skip_header_unknown_value_still_renews_but_strips(
    client: TestClient,
    auth_headers: dict,
    monkeypatch: pytest.MonkeyPatch,
    prefix: str,
) -> None:
    monkeypatch.setattr(lifecycle, "sandbox_service", _RenewStubService())
    fake_client = _proxy_ok_fake()
    _set_http_client(client, fake_client)
    coordinator = _install_renew_coordinator(client)

    response = client.get(
        f"{prefix}/sandboxes/sbx-renew/proxy/3000/status",
        headers={**auth_headers, "OpenSandbox-Access-Renew": "later"},
        follow_redirects=False,
    )

    assert response.status_code == 200
    assert coordinator.scheduled == ["sbx-renew"]
    forwarded = fake_client.built["headers"]
    assert all(k.lower() != "opensandbox-access-renew" for k in forwarded)