Make the offline RAG chain observable without widening credential access

Expose the verified synthetic retrieval path through a typed React client and a non-root Nginx edge while keeping database credentials and data-network reachability out of the browser tier. A fixed-origin gateway preserves request boundaries and now closes upstream streams even when downstream disconnects before body iteration. The deployment ADR and runbooks record the four-network topology and its accepted Web edge-egress risk.

Constraint: The previously exposed Bailian key must be revoked and no live provider credential may enter Git, images, logs, or the browser.
Rejected: Connect Web directly to the data network | expands lateral reach to PostgreSQL.
Rejected: Publish the database-aware API on the edge network | gives a credential-bearing process a public default route.
Rejected: Buffer streaming responses in either proxy | prevents incremental chat delivery in the future.
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Do not mark Stage 1 or Stage 2 complete until the rotated-key live smoke and remaining stage gates pass.
Tested: make verify; 65 backend tests; 14 frontend tests; Docker image build; container health and isolation probes; real HTTP demo/status/search/docs/OpenAPI checks.
Not-tested: Live Bailian models, real document ingestion, business chat SSE generation, and final browser screenshot automation because the browser skill runtime was unavailable.

backend/app/gateway.py

@@ -5,7 +5,8 @@ from contextlib import asynccontextmanager
 
 import httpx
 from fastapi import FastAPI, Request, Response, status
-from fastapi.responses import JSONResponse
+from fastapi.responses import JSONResponse, StreamingResponse
+from starlette.types import Receive, Scope, Send
 
 UPSTREAM_ORIGIN = httpx.URL("http://api:8000")
 MAX_REQUEST_BODY_BYTES = 1024 * 1024
@@ -53,6 +54,27 @@ RESPONSE_HEADER_ALLOWLIST = frozenset(
 )
 
 
+class _UpstreamStreamingResponse(StreamingResponse):
+    """Close the upstream response even if downstream headers cannot be sent."""
+
+    def __init__(
+        self,
+        *,
+        upstream_response: httpx.Response,
+        content: AsyncIterator[bytes],
+        status_code: int,
+        headers: Mapping[str, str],
+    ) -> None:
+        self._upstream_response = upstream_response
+        super().__init__(content=content, status_code=status_code, headers=headers)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            await super().__call__(scope, receive, send)
+        finally:
+            await self._upstream_response.aclose()
+
+
 def _allowlisted_headers(headers: Mapping[str, str], allowlist: frozenset[str]) -> dict[str, str]:
     return {name: value for name, value in headers.items() if name.lower() in allowlist}
 
@@ -139,15 +161,23 @@ def create_gateway_app(transport: httpx.AsyncBaseTransport | None = None) -> Fas
             content=body,
         )
         try:
-            upstream_response = await upstream_client.send(upstream_request)
+            upstream_response = await upstream_client.send(upstream_request, stream=True)
         except httpx.RequestError:
             return JSONResponse(
                 status_code=status.HTTP_502_BAD_GATEWAY,
                 content={"detail": "upstream unavailable"},
             )
 
-        return Response(
-            content=upstream_response.content,
+        async def response_body() -> AsyncIterator[bytes]:
+            if upstream_response.is_stream_consumed:
+                yield upstream_response.content
+            else:
+                async for chunk in upstream_response.aiter_raw():
+                    yield chunk
+
+        return _UpstreamStreamingResponse(
+            upstream_response=upstream_response,
+            content=response_body(),
             status_code=upstream_response.status_code,
             headers=_allowlisted_headers(
                 upstream_response.headers,

backend/tests/integration/test_schema_contract.py

@@ -18,6 +18,8 @@ from app.persistence.job_queue_sql import (  # noqa: E402
 
 COMPOSE = (ROOT / "compose.yaml").read_text(encoding="utf-8")
 DOCKERFILE = (BACKEND / "Dockerfile").read_text(encoding="utf-8")
+FRONTEND_DOCKERFILE = (ROOT / "frontend/Dockerfile").read_text(encoding="utf-8")
+NGINX = (ROOT / "frontend/nginx.conf").read_text(encoding="utf-8")
 DEMO_API = (BACKEND / "app/api/v1/demo.py").read_text(encoding="utf-8")
 BOOTSTRAP = (ROOT / "ops/postgres/init/10-bootstrap-rag.sh").read_text(encoding="utf-8")
 MIGRATION = (BACKEND / "migrations/versions/0001_initial_schema.py").read_text(encoding="utf-8")
@@ -35,6 +37,7 @@ def test_compose_isolates_database_credentials_and_networks() -> None:
     migrate = _service_block("migrate")
     api = _service_block("api")
     gateway = _service_block("gateway")
+    web = _service_block("web")
     provider_smoke = _service_block("provider-smoke")
     seed_demo = _service_block("seed-demo")
     seed_demo_offline = _service_block("seed-demo-offline")
@@ -59,15 +62,29 @@ def test_compose_isolates_database_credentials_and_networks() -> None:
     assert "no-new-privileges:true" in api
     assert "cap_drop:" in api and "      - ALL" in api
 
-    assert '"127.0.0.1:8000:8000"' in gateway
-    assert "      - edge" in gateway
+    assert '"127.0.0.1:8000:8000"' not in gateway
+    assert "      - ingress" in gateway
     assert "      - data" in gateway
+    assert "      - edge" not in gateway
+    assert "      - egress" not in gateway
     assert "secrets:" not in gateway
     assert "POSTGRES_" not in gateway
     assert "BAILIAN_" not in gateway
     assert "read_only: true" in gateway
     assert "no-new-privileges:true" in gateway
 
+    assert '"127.0.0.1:8000:8080"' in web
+    assert "      - edge" in web
+    assert "      - ingress" in web
+    assert "      - data" not in web
+    assert "      - egress" not in web
+    assert "secrets:" not in web
+    assert "POSTGRES_" not in web
+    assert "BAILIAN_" not in web
+    assert "read_only: true" in web
+    assert "no-new-privileges:true" in web
+    assert len(re.findall(r"(?m)^    ports:$", COMPOSE)) == 1
+
     assert "bailian_api_key" in provider_smoke
     assert "postgres_" not in provider_smoke
 
@@ -83,11 +100,15 @@ def test_compose_isolates_database_credentials_and_networks() -> None:
     assert "./data/samples/public:/demo:ro" in seed_demo_offline
 
     assert re.search(r"(?ms)^  data:\n.*?^    internal: true$", COMPOSE)
+    assert re.search(r"(?ms)^  ingress:\n.*?^    internal: true$", COMPOSE)
     assert re.search(r"(?m)^  edge:$", COMPOSE)
     assert re.search(r"(?m)^  egress:$", COMPOSE)
 
     assert "USER 10001:10001" in DOCKERFILE
     assert 'CMD ["uvicorn", "app.main:app"' in DOCKERFILE
+    assert "USER 101:101" in FRONTEND_DOCKERFILE
+    assert "proxy_buffering off" in NGINX
+    assert "server gateway:8000" in NGINX
 
 
 def test_demo_queries_pin_governed_offline_identity() -> None:

backend/tests/unit/test_gateway.py

@@ -1,16 +1,38 @@
 import json
 from collections.abc import AsyncIterator, Callable
 from contextlib import asynccontextmanager
+from typing import cast
 
 import httpx
 import pytest
 from fastapi import FastAPI
+from starlette.requests import ClientDisconnect
+from starlette.types import Message, Scope
 
 from app.gateway import MAX_REQUEST_BODY_BYTES, create_gateway_app
 
 type Handler = Callable[[httpx.Request], httpx.Response]
 
 
+class _TwoEventStream(httpx.AsyncByteStream):
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        yield b"data: first\n\n"
+        yield b"data: second\n\n"
+
+
+class _TrackedStream(httpx.AsyncByteStream):
+    def __init__(self) -> None:
+        self.closed = False
+        self.started = False
+
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        self.started = True
+        yield b"data: never-delivered\n\n"
+
+    async def aclose(self) -> None:
+        self.closed = True
+
+
 @asynccontextmanager
 async def _gateway_client(handler: Handler) -> AsyncIterator[httpx.AsyncClient]:
     gateway = create_gateway_app(httpx.MockTransport(handler))
@@ -161,3 +183,105 @@ async def test_sensitive_upstream_response_headers_are_not_forwarded() -> None:
     assert "set-cookie" not in response.headers
     assert "server" not in response.headers
     assert "x-internal-token" not in response.headers
+
+
+@pytest.mark.asyncio
+async def test_sse_events_are_forwarded_as_separate_asgi_body_chunks() -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            headers={"content-type": "text/event-stream"},
+            stream=_TwoEventStream(),
+        )
+
+    gateway = create_gateway_app(httpx.MockTransport(handler))
+    sent: list[Message] = []
+    request_delivered = False
+
+    async def receive() -> Message:
+        nonlocal request_delivered
+        if not request_delivered:
+            request_delivered = True
+            return {"type": "http.request", "body": b"", "more_body": False}
+        return {"type": "http.disconnect"}
+
+    async def send(message: Message) -> None:
+        sent.append(message)
+
+    scope = cast(
+        Scope,
+        {
+            "type": "http",
+            "asgi": {"version": "3.0", "spec_version": "2.4"},
+            "http_version": "1.1",
+            "method": "GET",
+            "scheme": "http",
+            "path": "/api/v1/chat/stream",
+            "raw_path": b"/api/v1/chat/stream",
+            "query_string": b"",
+            "headers": [(b"accept", b"text/event-stream")],
+            "client": ("127.0.0.1", 12345),
+            "server": ("gateway", 80),
+        },
+    )
+
+    async with gateway.router.lifespan_context(gateway):
+        await gateway(scope, receive, send)
+
+    body_messages = [message for message in sent if message["type"] == "http.response.body"]
+    assert [message["body"] for message in body_messages] == [
+        b"data: first\n\n",
+        b"data: second\n\n",
+        b"",
+    ]
+    assert [message["more_body"] for message in body_messages] == [True, True, False]
+
+
+@pytest.mark.asyncio
+async def test_upstream_stream_closes_when_downstream_disconnects_before_body_iteration() -> None:
+    upstream_stream = _TrackedStream()
+
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            headers={"content-type": "text/event-stream"},
+            stream=upstream_stream,
+        )
+
+    gateway = create_gateway_app(httpx.MockTransport(handler))
+    request_delivered = False
+
+    async def receive() -> Message:
+        nonlocal request_delivered
+        if not request_delivered:
+            request_delivered = True
+            return {"type": "http.request", "body": b"", "more_body": False}
+        return {"type": "http.disconnect"}
+
+    async def disconnect_on_response_start(message: Message) -> None:
+        if message["type"] == "http.response.start":
+            raise OSError("downstream disconnected")
+
+    scope = cast(
+        Scope,
+        {
+            "type": "http",
+            "asgi": {"version": "3.0", "spec_version": "2.4"},
+            "http_version": "1.1",
+            "method": "GET",
+            "scheme": "http",
+            "path": "/api/v1/chat/stream",
+            "raw_path": b"/api/v1/chat/stream",
+            "query_string": b"",
+            "headers": [(b"accept", b"text/event-stream")],
+            "client": ("127.0.0.1", 12345),
+            "server": ("gateway", 80),
+        },
+    )
+
+    async with gateway.router.lifespan_context(gateway):
+        with pytest.raises(ClientDisconnect):
+            await gateway(scope, receive, disconnect_on_response_start)
+
+    assert upstream_stream.closed is True
+    assert upstream_stream.started is False