vgi-python 0.21.0__tar.gz → 0.22.1__tar.gz

{vgi_python-0.21.0 → vgi_python-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vgi-python
-Version: 0.21.0
+Version: 0.22.1
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python
@@ -162,7 +162,7 @@ Requires-Dist: httpx>=0.24
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.26.0
+Requires-Dist: vgi-rpc>=0.28.3
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.21.0 → vgi_python-0.22.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.21.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.26.0",
+    "vgi-rpc>=0.28.3",
     "httpx>=0.24",
 ]
 
@@ -142,6 +142,12 @@ convention = "google"
 
 [tool.ruff.format]
 quote-style = "double"
+# ruff >=0.16 formats Python code blocks embedded in Markdown. Our docs use
+# mkdocs `pymdownx.snippets` includes (`--8<-- "examples/foo.py"`) inside
+# ```python fences; ruff parses those as Python and rewrites them to
+# `--8 < --"..."`, breaking both the docs build and the doc-example tests.
+# Keep Markdown out.
+exclude = ["*.md"]
 
 [tool.pydoclint]
 # Docstring consistency gate (complements ruff's `D` rules, which only check

{vgi_python-0.21.0 → vgi_python-0.22.1}/tests/test_serve.py

@@ -206,6 +206,57 @@ class TestCreateApp:
 
         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_python-0.21.0 → vgi_python-0.22.1}/uv.lock

@@ -2061,27 +2061,27 @@ wheels = [
 
 [[package]]
 name = "ruff"
-version = "0.15.20"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/43/dc/35b341fc554ba02f217fc10da57d1a75168cfbcf75b0ef2202176d4c4f2d/ruff-0.15.20.tar.gz", hash = "sha256:1416eb04349192646b54de98f146c4f59afe37d0decfc02c3cbbf396f3a28566", size = 4755489, upload-time = "2026-06-25T17:20:37.578Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/94/d9/2d5014f0253ba541d2061d9fa7193f48e941c8b21bb88a7ff9bbe0bd0596/ruff-0.15.20-py3-none-linux_armv6l.whl", hash = "sha256:00e188c53e499c3c1637f73c91dcf2fb56d576cab76ce1be50a27c4e80e37078", size = 10839665, upload-time = "2026-06-25T17:19:44.702Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/d3/ac1798ba64f670698867fcfc591d50e7e421bef137db564858f619a30fcf/ruff-0.15.20-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:9ebd1fd9b9c95fc0bd7b2761aebec1f030013d2e193a2901b224af68fe47251b", size = 11208649, upload-time = "2026-06-25T17:19:48.787Z" },
-    { url = "https://files.pythonhosted.org/packages/47/47/d3ac899991202095dfcf3d5176be4272642be3cf981a2f1a30f72a2afb95/ruff-0.15.20-py3-none-macosx_11_0_arm64.whl", hash = "sha256:c5b16cdd67ca108185cd36dce98c576350c03b1660a751de725fb049193a0632", size = 10622638, upload-time = "2026-06-25T17:19:51.354Z" },
-    { url = "https://files.pythonhosted.org/packages/33/13/4e043fe30aa94d4ff5213a9881fc296d12960f5971b234a5263fdc225312/ruff-0.15.20-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3413bb3c3d2ca6a8208f1f4809cd2dca3c6de6d0b491c0e70847672bde6e6efd", size = 10984227, upload-time = "2026-06-25T17:19:54.044Z" },
-    { url = "https://files.pythonhosted.org/packages/76/e6/92e7bf40388bc5800073b96564f56264f7e48bfd1a498f5ced6ae6d5a769/ruff-0.15.20-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:bd7ec42b3bb3da066488db093308a69c4ac5ee6d2af333a86ba6e2eb2e7dd44b", size = 10622882, upload-time = "2026-06-25T17:19:57.037Z" },
-    { url = "https://files.pythonhosted.org/packages/13/7a/43460be3f24495a3aa46d4b16873e2c4941b3b5f0b00cf88c03b7b94b339/ruff-0.15.20-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e1a36ad0eb77fba9aabfb69ede54de6f376d04ac18ebea022847046d340a8267", size = 11474808, upload-time = "2026-06-25T17:20:00.357Z" },
-    { url = "https://files.pythonhosted.org/packages/27/a0/f37077884873221c6b33b4ab49eb18f9f88e54a16a25a5bca59bef46dd66/ruff-0.15.20-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b6df3b1e4610432f0386dba04d853b5f08cbbc903410c6fcc02f620f05aff53c", size = 12293094, upload-time = "2026-06-25T17:20:03.446Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/74/165545b60256a9704c21ac0ec4a0d07933b320812f9584836c9f4aca4292/ruff-0.15.20-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e89f198a1ea6ef0d727c1cf16088bc91a6cb0ab947dedc966715691647186eae", size = 11526176, upload-time = "2026-06-25T17:20:06.301Z" },
-    { url = "https://files.pythonhosted.org/packages/86/b1/a976a136d40ade83ce743578399865f57001003a409acadc0ecbb3051082/ruff-0.15.20-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:309809086c2acb67624950a3c8133e80f32d0d3e27106c0cd60ff26657c9f24b", size = 11520767, upload-time = "2026-06-25T17:20:09.191Z" },
-    { url = "https://files.pythonhosted.org/packages/19/0f/f032696cb01c9b54c0263fa393474d7758f1cdc021a01b04e3cbc2500999/ruff-0.15.20-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:2d2374caa2f2c2f9e2b7da0a50802cfb8b79f55a9b5e49379f564544fbf56487", size = 11500132, upload-time = "2026-06-25T17:20:13.602Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/f4/51b1a14bc69e8c224b15dab9cce8e99b425e0455d462caa2b3c9be2b6a8e/ruff-0.15.20-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a1ed17b65293e0c2f22fc387bc13198a5de94bf4429589b0ff6946b0feaf21a3", size = 10943828, upload-time = "2026-06-25T17:20:16.635Z" },
-    { url = "https://files.pythonhosted.org/packages/71/4b/fe267640783cd02bf6c5cc290b1df1051be2ec294c678b5c15fe19e52343/ruff-0.15.20-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:f701305e66b38ea6c91882490eb73459796808e4c6362a1b765255e0cdcd4053", size = 10645418, upload-time = "2026-06-25T17:20:19.4Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/c0/a65aa4ec2f5e87a1df32dc3ec1fede434fe3dfd5cbcf3b503cafc676ab54/ruff-0.15.20-py3-none-musllinux_1_2_i686.whl", hash = "sha256:5b9c0c367ad8e5d0d5b5b8537864c469a0a0e55417aadfbeca41fa61333be9f4", size = 11211770, upload-time = "2026-06-25T17:20:22.033Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/a4/0caa331d954ae2723d729d351c989cb4ca8b6077d5c6c2cb6de75e98c041/ruff-0.15.20-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:01cc00dd58f0df339d0e902219dd53990ea99996a0344e5d9cc8d45d5307e460", size = 11618698, upload-time = "2026-06-25T17:20:25.259Z" },
-    { url = "https://files.pythonhosted.org/packages/10/9b/5f14927848d2fd4aa891fd88d883788c5a7baba561c7874732364045708c/ruff-0.15.20-py3-none-win32.whl", hash = "sha256:ed65ef510e43a137207e0f01cfcf998aeddb1aeeda5c9d35023e910284d7cf21", size = 10857322, upload-time = "2026-06-25T17:20:28.612Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/f0/fe47c501f9dea92a26d788ff98bb5d92ed4cb4c88792c5c88af6b697dc8e/ruff-0.15.20-py3-none-win_amd64.whl", hash = "sha256:a525c81c70fb0380344dd1d8745d8cc1c890b7fc94a58d5a07bd8eb9557b8415", size = 11993274, upload-time = "2026-06-25T17:20:31.871Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/2b/9555445e1201d92b3195f45cdb153a0b68f24e0a4273f6e3d5ab46e212bb/ruff-0.15.20-py3-none-win_arm64.whl", hash = "sha256:2f5b2a6d614e8700388806a14996c40fab2c47b819ef57d790a34878858ed9ca", size = 11343498, upload-time = "2026-06-25T17:20:35.03Z" },
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4d/94/1e5e4967626faf12fa56999cd6222dff6992ceb086ad7945756baf70c7a7/ruff-0.16.0.tar.gz", hash = "sha256:e460aafd5495ec89efaa6ced2e4a9a581116451e1c88b9d37ef497e0f8e93982", size = 4790557, upload-time = "2026-07-23T19:11:30.981Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4b/81/1c8818fee7ce1a04cd7d1b3172e0a8f8e4f1dc4feb7fc390e16daa8af323/ruff-0.16.0-py3-none-linux_armv6l.whl", hash = "sha256:e5115729eb08c585e5121978ba5d5b60caeae394ce21b9fb5e6cd33a1c6c9b1e", size = 10754633, upload-time = "2026-07-23T19:10:46.415Z" },
+    { url = "https://files.pythonhosted.org/packages/23/df/beaf59c09d68db84304d555f188b276a77132a5d5b0b67a5c762aa143628/ruff-0.16.0-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:3c954b1d580bfa035b41654f7858cc7e71d5fc3ac5b723dd62bd9133830ed522", size = 10969164, upload-time = "2026-07-23T19:10:50.271Z" },
+    { url = "https://files.pythonhosted.org/packages/42/ce/741cd197496a1abbf51352710fd15ed995d2a2be87189c1da26a450d6e83/ruff-0.16.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:e01c21d10eb1b29f47b7454e1f4056db9a3f0260c646aa88457c610291db9f81", size = 10488846, upload-time = "2026-07-23T19:10:52.639Z" },
+    { url = "https://files.pythonhosted.org/packages/52/2a/a2db8e88cade358f5cdcb05674a917751074109315d014eb6352d9a893f7/ruff-0.16.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6e364e5ed22ed8dc05082fd78e35308618260907ac2d3c1d637b2e682415b6c9", size = 10889729, upload-time = "2026-07-23T19:10:54.89Z" },
+    { url = "https://files.pythonhosted.org/packages/42/65/62a771694ebd63029dc953e27dbad40e1588bd4860ff9fe881018fddaa49/ruff-0.16.0-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d327b8fc113a1d4421a04f3839d3752057c8dd1ee320223a6f3f52d04ada462a", size = 10568275, upload-time = "2026-07-23T19:10:56.993Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/e2/ced249fe8af5f086c5c58cc21cc3356d50f32f7401c5df87050c999620a7/ruff-0.16.0-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a9b50c55e263103586b3dcf5f73d479eb8cb5fdb6098fec59a62891dab653717", size = 11385112, upload-time = "2026-07-23T19:10:59.615Z" },
+    { url = "https://files.pythonhosted.org/packages/87/0b/05154977a8fd69eeb6c103271f55403bfd8711f5c0f8ed07489d95a504e7/ruff-0.16.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:0ff4a79ce3ec0172f3241943835de1c4cb4e2dcd07f0f8c2d02603dbbbee4b17", size = 12207008, upload-time = "2026-07-23T19:11:02.154Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/29/98225831a3a1eab0e02f4acc6ca6559a98611dcc68b6965ff4b7234627c1/ruff-0.16.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e95c448fca1fb2a18372a9440926c5a6ee789639bb975c72e7ae6d0b04218ab4", size = 11650842, upload-time = "2026-07-23T19:11:04.557Z" },
+    { url = "https://files.pythonhosted.org/packages/91/66/6bd3cf90500653d55dc0ffc8507aa8300bd49d0214b2e8cb4d3fef2943ba/ruff-0.16.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:4f11a8d11010301d0a398a2fdef67691feca7294da6aef55e2150e8fa2cd520b", size = 11400718, upload-time = "2026-07-23T19:11:09.233Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/a2/a54eb4eae05d66364050a5d3b8a9c5ef88196531b3cbe7109d873f87f819/ruff-0.16.0-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:48044c678e9cb8698246c99b14aaccfa6601dea7379eb48a6f8f73f7a6d86cd0", size = 11426177, upload-time = "2026-07-23T19:11:11.994Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/be/16e3eea4b2a478a496919f5e36f17c4559e54620bd3bbac5d6affa068006/ruff-0.16.0-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:7aa0959bad8eb8bef50340154fc9b58678dae31fa4293afa38b44b6e552c0213", size = 10856126, upload-time = "2026-07-23T19:11:14.221Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/84/252eb8b868a16eec7257c14f504f77537e734b2d69c762e639e588e304a3/ruff-0.16.0-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:28ea2b7df8ebf7f9da6b7d47b230ab48f387c0a29be3b474c4d0740e197bb9af", size = 10571208, upload-time = "2026-07-23T19:11:16.378Z" },
+    { url = "https://files.pythonhosted.org/packages/21/09/817a482f542f7570cbb4554b26e896610c7114f539b1d9e2d2145bf6bef6/ruff-0.16.0-py3-none-musllinux_1_2_i686.whl", hash = "sha256:33a3dfac8c35f81498dea9181bccc2f4c4bc8f1521a1dd9406e77643e0f0fb09", size = 11063329, upload-time = "2026-07-23T19:11:19.173Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/23/9403c180ca1cb9b1f7335f5c3e5305c09d49ea5b345196682a36028bde4a/ruff-0.16.0-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:a5237a0bda500d30d81b8e07a6973a5cbc772864cbf746ae2f4e8a2e01c9f4ed", size = 11489751, upload-time = "2026-07-23T19:11:21.74Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/1d/1b2ef7bcde851c78d7f17f1cca13fd6dc695fc4b3d6197941e72cae5b132/ruff-0.16.0-py3-none-win32.whl", hash = "sha256:7fab76fa065c873f41ff744347c6e77bcc3dfec4bcc754dc26b63d23c0f7f5fb", size = 10785885, upload-time = "2026-07-23T19:11:23.947Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/a3/d5e4ef7a56be3f928ffb90b94c25ba7d3cb9c7fe0736aeaaedf361770712/ruff-0.16.0-py3-none-win_amd64.whl", hash = "sha256:429c117f022bf481fabd9d551e7a3952b24c65e6ef44337ea09d90bebef14472", size = 11923141, upload-time = "2026-07-23T19:11:26.409Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/9a/8415f2657cbe200f41a4531ccededf135505a92d4a012229121f885b26f9/ruff-0.16.0-py3-none-win_arm64.whl", hash = "sha256:14296fedcd2705c77ab8235439278bbb38f285cf7da5528b00b3e330c3d4872d", size = 11273407, upload-time = "2026-07-23T19:11:28.705Z" },
 ]
 
 [[package]]
@@ -2228,7 +2228,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.21.0"
+version = "0.22.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2338,7 +2338,7 @@ requires-dist = [
     { name = "vgi-python", extras = ["test-fixtures"], marker = "extra == 'test-fixtures-writable'" },
     { name = "vgi-python", extras = ["test-fixtures", "test-fixtures-writable", "http", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.26.0" },
+    { name = "vgi-rpc", specifier = ">=0.28.3" },
     { name = "vgi-rpc", extras = ["conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'http'" },
     { name = "vgi-rpc", extras = ["oauth"], marker = "extra == 'oauth'" },
@@ -2367,7 +2367,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.26.0"
+version = "0.28.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2375,9 +2375,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/b5/51/86d4c4466cf5311e80db28f535c02b92961f3d5160a0aae348112a03f7d5/vgi_rpc-0.26.0.tar.gz", hash = "sha256:c0966c99e087f923b228b2211877a8695bf42052d9cde05ce9a4bf077047cb78", size = 869625, upload-time = "2026-07-21T17:39:12.871Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a0/5a/1996a64ca9ecb0a030cee5a4b9944301f20d6269369b39a5d30f07bf71a9/vgi_rpc-0.28.3.tar.gz", hash = "sha256:772f535912926ce47c17c3eba33769ad226171277159c591f441169f642e14d6", size = 908548, upload-time = "2026-07-27T16:45:47.344Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/57/51/d86efc32aef03d69d197916f9d18d0f3719ebd843424cfb9a782ced041c9/vgi_rpc-0.26.0-py3-none-any.whl", hash = "sha256:2c455edb517831867342ce2f105386b73b1fa23137477916c5e5d7a14b66e0fc", size = 386786, upload-time = "2026-07-21T17:39:11.142Z" },
+    { url = "https://files.pythonhosted.org/packages/70/d1/db1b3aa48d1d0526bc30ad72e51ad8fd7f67f693310de8c143e707a87d0a/vgi_rpc-0.28.3-py3-none-any.whl", hash = "sha256:bf913b9b95ac4abde4e4ddad5b228c1d81bd748268773f9a2e5fa9626cc68bf7", size = 406388, upload-time = "2026-07-27T16:45:45.905Z" },
 ]
 
 [package.optional-dependencies]

{vgi_python-0.21.0 → vgi_python-0.22.1}/vgi/serve.py

@@ -32,7 +32,7 @@ import os
 import sys
 from collections.abc import Callable
 from types import ModuleType
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 from vgi.logging_config import LogFormat, LogLevel
 
@@ -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,
@@ -429,6 +440,10 @@ def _resolve_authenticate() -> Callable[..., Any] | None:
     - ``VGI_JWT_ISSUER`` + ``VGI_JWT_AUDIENCE``: JWT/JWKS auth
       (requires ``vgi[oauth]`` extra). Optional ``VGI_JWT_JWKS_URI``.
     - When both bearer and JWT are set, they are chained (JWT first).
+    - ``VGI_PROXY_PROOF_MODE``: ``allow`` or ``require`` gates every request
+      on proof that it arrived through a trusted proxy. This is a
+      precondition ANDed with whichever credential above is configured, not
+      an alternative to one.
 
     Returns:
         An authenticate callback, or None if no auth env vars are set.
@@ -438,14 +453,84 @@ def _resolve_authenticate() -> Callable[..., Any] | None:
             JWT issuer without audience).
 
     """
-    bearer_auth = _resolve_bearer_authenticate()
-    jwt_auth = _resolve_jwt_authenticate()
+    # Ordered by cost: JWT resolves a signature, bearer does a constant-time
+    # scan over the token set, so the cheaper one goes last.
+    candidates = [fn for fn in (_resolve_jwt_authenticate(), _resolve_bearer_authenticate()) if fn is not None]
 
-    if bearer_auth is not None and jwt_auth is not None:
+    inner: Callable[..., Any] | None
+    if len(candidates) > 1:
         from vgi_rpc.http import chain_authenticate
 
-        return chain_authenticate(jwt_auth, bearer_auth)
-    return jwt_auth or bearer_auth
+        inner = chain_authenticate(*candidates)
+    else:
+        inner = candidates[0] if candidates else None
+
+    gate = _resolve_proxy_proof_gate()
+    if gate is None:
+        return inner
+
+    # AND, not OR: chaining the gate would let any later credential satisfy
+    # the request on its own, which is exactly the bypass the gate exists to
+    # close. `inner` may be None — proof alone means "only my proxy may call
+    # this worker", with user identity handled upstream.
+    from vgi_rpc.http import require_all
+
+    return require_all(gate, inner)
+
+
+def _resolve_proxy_proof_gate() -> Any | None:
+    """Build a proxy-proof gate from ``VGI_PROXY_PROOF_*`` environment variables.
+
+    Env vars:
+
+    - ``VGI_PROXY_PROOF_MODE``: ``off`` (default), ``allow`` or ``require``.
+    - ``VGI_PROXY_PROOF_ORIGIN_ID``: this worker's identifier. Folded into
+      every MAC but never transmitted, so it must match what the proxy is
+      configured to prove to.
+    - ``VGI_PROXY_PROOF_SECRETS``: ``kid:hex`` pairs, comma-separated. The
+      ``kid`` doubles as the proxy's label in the audit trail.
+    - ``VGI_PROXY_PROOF_SKEW``: acceptance half-window in seconds (default 30).
+
+    Returns:
+        A gate for ``require_all``, or None when the feature is off.
+
+    Raises:
+        SystemExit: On any malformed value. Deliberately fail-closed: the
+            secret is shared with an independently-deployed proxy, so a typo
+            would otherwise silently reject every request with no diagnostic.
+
+    """
+    raw_mode = (os.environ.get("VGI_PROXY_PROOF_MODE") or "off").strip().lower()
+    if raw_mode == "off":
+        return None
+    if raw_mode not in ("allow", "require"):
+        sys.stderr.write(
+            f"Error: VGI_PROXY_PROOF_MODE must be 'off', 'allow' or 'require', got {raw_mode!r}\n",
+        )
+        sys.exit(1)
+    mode: Literal["allow", "require"] = "allow" if raw_mode == "allow" else "require"
+
+    from vgi_rpc.http import ProxyProofConfig, parse_secrets, proxy_proof_gate
+
+    raw_secrets = os.environ.get("VGI_PROXY_PROOF_SECRETS") or ""
+    skew_raw = os.environ.get("VGI_PROXY_PROOF_SKEW") or "30"
+    try:
+        secrets = parse_secrets(raw_secrets)
+        config = ProxyProofConfig(
+            mode=mode,
+            origin_id=os.environ.get("VGI_PROXY_PROOF_ORIGIN_ID") or "",
+            secrets=secrets,
+            skew_seconds=int(skew_raw),
+        )
+    except ValueError as exc:
+        sys.stderr.write(
+            f"Error: invalid proxy-proof configuration: {exc}\n"
+            "Set VGI_PROXY_PROOF_MODE=off to disable, or fix "
+            "VGI_PROXY_PROOF_ORIGIN_ID / VGI_PROXY_PROOF_SECRETS "
+            "(kid:hex pairs, 64 hex chars each; generate with 'openssl rand -hex 32').\n",
+        )
+        sys.exit(1)
+    return proxy_proof_gate(config)
 
 
 def _resolve_bearer_authenticate() -> Callable[..., Any] | None: