release: 0.22.1 — advertise VGI-Proxy-Proof-Required from create_app

A `require`-mode worker now tells proxies it actually enforces the proof
they mint. Without the header, `allow` → `require` has no confirmation
step: a proxy minting proofs at a worker that silently ignores them looks
identical to one that checks every hop.

`proxy_proof_required` defaults to `None`, deriving from
VGI_PROXY_PROOF_MODE — the same env var `_resolve_proxy_proof_gate` reads,
so the advertisement cannot drift from the posture it describes. Pass a
bool explicitly only when supplying a hand-built gate via `authenticate`.

Requires vgi-rpc 0.28.3, which adds the `make_wsgi_app` kwarg and two
shared conformance cases pinning both postures across all five ports.

Verified against a real waitress-served worker: off and allow silent,
require emits "true".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: rustyconover

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.22.0"
+version = "0.22.1"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.28.2",
+    "vgi-rpc>=0.28.3",
     "httpx>=0.24",
 ]
 

tests/test_serve.py

@@ -206,6 +206,57 @@ def test_describe_disabled(self) -> None:
 
         assert isinstance(app, falcon.App)
 
+    @staticmethod
+    def _health_proof_header(**env: str) -> str | None:
+        """Serve an app under ``env`` and read the proof capability header.
+
+        Args:
+            **env: ``VGI_PROXY_PROOF_*`` values to set for the duration.
+
+        Returns:
+            The ``VGI-Proxy-Proof-Required`` value, or ``None`` when absent.
+
+        """
+        import falcon.testing
+
+        with pytest.MonkeyPatch.context() as mp:
+            for key in ("VGI_PROXY_PROOF_MODE", "VGI_PROXY_PROOF_ORIGIN_ID", "VGI_PROXY_PROOF_SECRETS"):
+                mp.delenv(key, raising=False)
+            for key, value in env.items():
+                mp.setenv(key, value)
+            app = create_app(_SingleWorker, prefix="/vgi", describe=False)
+            resp = falcon.testing.TestClient(app).simulate_get("/vgi/health")
+        assert resp.status_code == 200
+        return {k.lower(): v for k, v in resp.headers.items()}.get("vgi-proxy-proof-required")
+
+    def test_advertises_proof_required_in_require_mode(self) -> None:
+        """A ``require``-mode worker tells proxies it actually enforces.
+
+        Derived from ``VGI_PROXY_PROOF_MODE`` rather than passed separately,
+        because that env var is also where the gate itself comes from — so the
+        advertisement cannot drift from the posture it describes.
+        """
+        value = self._health_proof_header(
+            VGI_PROXY_PROOF_MODE="require",
+            VGI_PROXY_PROOF_ORIGIN_ID="worker-a",
+            VGI_PROXY_PROOF_SECRETS="k:" + "11" * 32,
+        )
+        assert value == "true"
+
+    @pytest.mark.parametrize("mode", ["off", "allow"])
+    def test_does_not_advertise_below_require(self, mode: str) -> None:
+        """Only ``require`` advertises — ``allow`` never denies, so it must not.
+
+        A proxy reads this to confirm a rollout landed; an ``allow``-mode worker
+        that claimed to require would report the rollout complete while every
+        unproofed direct caller still sailed through.
+        """
+        env = {"VGI_PROXY_PROOF_MODE": mode}
+        if mode != "off":
+            env["VGI_PROXY_PROOF_ORIGIN_ID"] = "worker-a"
+            env["VGI_PROXY_PROOF_SECRETS"] = "k:" + "11" * 32
+        assert self._health_proof_header(**env) is None
+
     def test_signing_key_passed(self) -> None:
         """Explicit signing_key is accepted without warning."""
         import warnings

vgi/serve.py

@@ -202,6 +202,7 @@ def create_app(
     signing_key: bytes | None = None,
     log_level: int = logging.INFO,
     authenticate: Callable[[falcon.Request], AuthContext] | None = None,
+    proxy_proof_required: bool | None = None,
     oauth_resource_metadata: Any = None,
     otel_config: OtelConfig | None = None,
     max_stream_response_bytes: int | None = None,
@@ -224,6 +225,12 @@ def create_app(
         authenticate: Optional callback that validates each HTTP request
             and returns an `AuthContext`. When ``None``, all requests are
             anonymous.
+        proxy_proof_required: Whether to advertise ``VGI-Proxy-Proof-Required``
+            so a proxy can confirm this worker actually enforces the proof it
+            mints. ``None`` (the default) derives it from
+            ``VGI_PROXY_PROOF_MODE``, which is also where the gate itself comes
+            from — so the advertisement cannot drift from the posture. Pass a
+            bool only when supplying a hand-built gate via ``authenticate``.
         oauth_resource_metadata: Optional `OAuthResourceMetadata` for
             RFC 9728 discovery endpoint.
         otel_config: Optional OpenTelemetry configuration.  When provided,
@@ -259,6 +266,9 @@ def create_app(
     if signing_key is None:
         signing_key = os.urandom(32)
 
+    if proxy_proof_required is None:
+        proxy_proof_required = (os.environ.get("VGI_PROXY_PROOF_MODE") or "").strip().lower() == "require"
+
     worker = worker_cls(quiet=True, log_level=log_level)
     worker._vgi_tracer = VgiTracer.create(otel_config)
     worker._signing_key = signing_key
@@ -271,6 +281,7 @@ def create_app(
         cors_origins=cors_origins,
         token_key=signing_key,
         authenticate=authenticate,
+        proxy_proof_required=proxy_proof_required,
         oauth_resource_metadata=oauth_resource_metadata,
         otel_config=otel_config,
         max_stream_response_bytes=max_stream_response_bytes,