fix(compose): rebuild loopback publishing on current main

CHANGELOG.md

@@ -35,6 +35,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Restricted the bundled standalone Compose PostgreSQL and component-health
+  published ports to IPv4 loopback so the default developer profile no longer
+  listens on every host interface when operators have not made an explicit
+  ingress decision.
 - Removed plaintext secret values from `config set-secret` process arguments;
   interactive entry now uses a no-echo prompt and fails closed if terminal echo
   suppression is unavailable. Automation accepts one bounded logical line over

docker-compose.yml

@@ -14,7 +14,9 @@ services:
       POSTGRES_PASSWORD: pgllm
       POSTGRES_DB: pgllm
     ports:
-      - "5432:5432"
+      # Standalone host access is local-only by default. Remote deployments must
+      # opt into an explicit ingress/network policy instead of inheriting 0.0.0.0.
+      - "127.0.0.1:5432:5432"
     healthcheck:
       # Readiness = DB up AND pg_tiktoken present (mirrors /healthz gate).
       test:
@@ -39,11 +41,13 @@ services:
       postgres:
         condition: service_healthy
     environment:
-      # Bootstrap transport only.
+      # Bootstrap transport only. The component image owns its default health
+      # port; alternate ports require an explicit command/healthcheck override.
       PG_LLM_BATCH_DSN: "postgresql://pgllm:pgllm@postgres:5432/pgllm"
-      PG_LLM_BATCH_HEALTH_PORT: "8080"
     ports:
-      - "8080:8080"
+      # The bundled standalone profile is deliberately host-local. Operators
+      # expose production health/API surfaces only through reviewed ingress.
+      - "127.0.0.1:8080:8080"
 
 volumes:
   pgdata:

docs/doctoring/compose-loopback-publishing.md

@@ -0,0 +1,31 @@
+# Standalone Compose loopback publishing
+
+## Decision
+
+The bundled `docker-compose.yml` is a standalone/developer profile. Its published PostgreSQL (`5432`) and component health (`8080`) ports bind to IPv4 loopback (`127.0.0.1`) by default.
+
+Remote access is not silently inherited from this profile. A production deployment that needs external ingress must define an explicit deployment-specific network and authorization boundary rather than broadening the bundled standalone mappings.
+
+## Security rationale
+
+Docker's Compose service reference defines the short port syntax as `[HOST:]CONTAINER[/PROTOCOL]` and warns that omitting the host IP binds the published port to all host interfaces (`0.0.0.0`). Docker's port-publishing documentation likewise states that a mapping that includes `127.0.0.1` is accessible only from the Docker host. The previous `"5432:5432"` and `"8080:8080"` mappings therefore created a broader default host-network surface than the standalone workflow requires.
+
+The loopback binding preserves the documented local commands:
+
+- host-side PostgreSQL access through `localhost:5432`;
+- host-side readiness checks through `localhost:8080`;
+- Compose-internal service-to-service traffic over the project network.
+
+It intentionally does not claim that loopback binding replaces authentication, tenant isolation, firewalling, ingress policy, or production deployment hardening.
+
+## Verification contract
+
+`tests/test_compose_network_boundary.py` requires the exact loopback mappings, rejects unexpected host-published services, and verifies that the obsolete shell-era `PG_LLM_BATCH_HEALTH_PORT` environment override is absent. CI also renders the Compose model with `docker compose config` and builds both component and PostgreSQL images.
+
+Release evidence must be taken from the exact source head under review. Organization-provided security/SAST workflows may independently exercise integration refs; those results remain distinct from exact-source proof.
+
+## References
+
+Docker, Inc. (n.d.). *Define services in Docker Compose*. Docker Documentation. Retrieved August 12, 2026, from https://docs.docker.com/reference/compose-file/services/
+
+Docker, Inc. (n.d.). *Port publishing and mapping*. Docker Documentation. Retrieved August 12, 2026, from https://docs.docker.com/engine/network/port-publishing/

tests/test_compose_network_boundary.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Security contracts for standalone Docker Compose host publishing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import shutil
+import subprocess
+from typing import Any
+
+import pytest
+
+
+_ROOT = Path(__file__).resolve().parents[1]
+_COMPOSE_PATH = _ROOT / "docker-compose.yml"
+_EXPECTED_PUBLISHED_PORTS = {"postgres": 5432, "component": 8080}
+
+
+def _compose_model() -> dict[str, Any]:
+    """Return Docker Compose's normalized JSON model for the standalone stack."""
+    docker = shutil.which("docker")
+    assert docker is not None, "Docker CLI is required to validate Compose security"
+    result = subprocess.run(
+        [
+            docker,
+            "compose",
+            "-f",
+            str(_COMPOSE_PATH),
+            "config",
+            "--format",
+            "json",
+        ],
+        cwd=_ROOT,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    model = json.loads(result.stdout)
+    assert isinstance(model, dict)
+    return model
+
+
+def _assert_only_loopback_port(
+    model: dict[str, Any], service_name: str, port_number: int
+) -> None:
+    """Require one exact IPv4-loopback TCP publication for a service port."""
+    services = model.get("services")
+    assert isinstance(services, dict)
+    service = services.get(service_name)
+    assert isinstance(service, dict)
+    ports = service.get("ports")
+    assert isinstance(ports, list)
+    assert len(ports) == 1
+
+    published = ports[0]
+    assert isinstance(published, dict)
+    assert published.get("host_ip") == "127.0.0.1"
+    assert int(published.get("published")) == port_number
+    assert published.get("target") == port_number
+    assert published.get("protocol", "tcp") == "tcp"
+
+
+def _assert_standalone_port_contract(model: dict[str, Any]) -> None:
+    """Require exactly the reviewed database and health host publications."""
+    services = model.get("services")
+    assert isinstance(services, dict)
+
+    published_services: set[str] = set()
+    for service_name, service in services.items():
+        assert isinstance(service_name, str)
+        assert isinstance(service, dict)
+        ports = service.get("ports")
+        if ports is None:
+            continue
+        assert isinstance(ports, list)
+        if ports:
+            published_services.add(service_name)
+
+    assert published_services == set(_EXPECTED_PUBLISHED_PORTS)
+    for service_name, port_number in _EXPECTED_PUBLISHED_PORTS.items():
+        _assert_only_loopback_port(model, service_name, port_number)
+
+
+def test_standalone_compose_publishes_database_and_health_only_on_loopback() -> None:
+    """Canonical Compose ports must expose only the two intended loopback sockets."""
+    _assert_standalone_port_contract(_compose_model())
+
+
+def test_standalone_compose_does_not_override_legacy_health_port_environment() -> None:
+    """The standalone profile must not advertise an inert shell-era health-port knob."""
+    model = _compose_model()
+    services = model.get("services")
+    assert isinstance(services, dict)
+    component = services.get("component")
+    assert isinstance(component, dict)
+    environment = component.get("environment")
+    assert isinstance(environment, dict)
+
+    assert "PG_LLM_BATCH_HEALTH_PORT" not in environment
+
+
+def test_standalone_port_contract_rejects_an_unexpected_published_service() -> None:
+    """Adding another host-published service must fail the standalone boundary."""
+    model: dict[str, Any] = {
+        "services": {
+            "postgres": {
+                "ports": [
+                    {
+                        "host_ip": "127.0.0.1",
+                        "published": "5432",
+                        "target": 5432,
+                        "protocol": "tcp",
+                    }
+                ]
+            },
+            "component": {
+                "ports": [
+                    {
+                        "host_ip": "127.0.0.1",
+                        "published": "8080",
+                        "target": 8080,
+                        "protocol": "tcp",
+                    }
+                ]
+            },
+            "rogue": {
+                "ports": [
+                    {
+                        "host_ip": "0.0.0.0",
+                        "published": "9090",
+                        "target": 9090,
+                        "protocol": "tcp",
+                    }
+                ]
+            },
+        }
+    }
+
+    with pytest.raises(AssertionError):
+        _assert_standalone_port_contract(model)