deps: require vgi-rpc >=0.46.0, migrate to Identity.v1 and named protocols

0.46.0 carries wire-breaking changes, so a >=0.45.1 floor lets a deployment
resolve a 0.45.x client against a 0.46.0 peer and fail at runtime rather than
at install time. Raise the floor and relock.

Two things in this repo broke against the new release:

Identity moved from HTTP to the RPC layer. `vgi_rpc.http.server._introspect`
is gone; `TokenIdentity` now lives in `vgi_rpc.rpc._token_identity` and the
`TokenResolver` alias was dropped upstream. Introspection is no longer the
`POST {prefix}/__introspect_token__` JSON route but the `vgi_rpc.Identity.v1`
protocol hosted on the RpcServer, configured via `RpcServer(identity=...)`
rather than three `make_wsgi_app` kwargs. So:

  - vgi.auth re-exports TokenIdentity from the RPC layer and spells out
    TokenResolver locally. Neither is gated on the `[http]` extra any more,
    because identity now reaches every transport rather than only HTTP.
  - serve.create_app builds an IdentityImpl through a new `_build_identity`
    helper and hands it to RpcServer. Absent-unless-overridden is preserved:
    no hook means `identity=None` means the protocol is not hosted at all,
    rather than hosted-and-refusing.
  - The fail-closed allowlist and rate-limit startup checks are unchanged;
    they still run before IdentityImpl is constructed, so its own ValueError
    path stays unreachable and the actionable SystemExit message survives.

The protocol name is now the dispatch routing key. The bad_protocol fixture
subclasses VgiProtocol to vary the version, and the name defaults to the class
name — so subclassing alone renamed the protocol to `BadProtocol`, and the
client's request for `VgiProtocol` raised ProtocolNotSupportedError before
reaching the version gate the fixture exists to test. Pin `protocol_name` so
the version is once again the only thing that varies.

The three TestTokenIntrospection cases that drove the retired HTTP route are
rewritten against the surface that now exists. Two neighbours had become
vacuous — they asserted 404, which is what every path to a removed route
returns — so they now assert on hosted protocols instead. Guard behaviour
(allowlist, uniform rejection, JWS-shape refusal, rate limiting) is vgi-rpc's
and tested there; what is covered here is the wiring this repo owns.

Docs updated to describe the protocol rather than the route.

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

Author: rustyconover

CLAUDE.md

@@ -297,7 +297,7 @@ vgi-client --input data.parquet --function sum_all_columns --worker vgi-fixture-
 | `VGI_OAUTH_DEVICE_CODE_CLIENT_ID` | Client ID for device-code flow (optional, URL-safe chars only) |
 | `VGI_OAUTH_DEVICE_CODE_CLIENT_SECRET` | Client secret for device-code flow (optional, URL-safe chars only) |
 | `VGI_OAUTH_USE_ID_TOKEN` | When `1`/`true`/`yes`, clients use OIDC `id_token` as Bearer instead of `access_token` |
-| `VGI_INTROSPECT_PRINCIPALS` | Comma-separated principals permitted to call `__introspect_token__`. Required — no permissive default — whenever the worker implements `resolve_token()` (see below) |
+| `VGI_INTROSPECT_PRINCIPALS` | Comma-separated principals permitted to call `vgi_rpc.Identity.v1`'s `introspect_token`. Required — no permissive default — whenever the worker implements `resolve_token()` (see below) |
 | `VGI_INTROSPECT_RATE_LIMIT` | Introspection requests allowed per caller per second (default 20) |
 | `VGI_WORKER_ACCESS_LOG_SAMPLE` | Fraction of *successful* calls to keep in the access log, `0.0`–`1.0`. Errors are always kept; the decision is per call, so every record of one stream shares a fate |
 | `VGI_WORKER_ACCESS_LOG_ASYNC` | When `1`/`true`/`yes`, emit access-log records from a listener thread. Bounded queue; full means drop, and a crash loses whatever is queued |
@@ -420,10 +420,16 @@ Also available on `Worker.main --http` and the fixture server. Under
 
 ### Token Introspection (`resolve_token`)
 
-A worker may optionally expose `POST {prefix}/__introspect_token__`, which
-resolves an opaque bearer credential to a principal — for a reverse proxy that
-terminates the only public listener and must know the caller's identity before
-it can authorize anything.
+A worker may optionally host the `vgi_rpc.Identity.v1` protocol, whose
+`introspect_token` method resolves an opaque bearer credential to a principal —
+for a reverse proxy that terminates the only public listener and must know the
+caller's identity before it can authorize anything.
+
+Through vgi-rpc 0.45.x this was an HTTP JSON route, `POST
+{prefix}/__introspect_token__`, which meant it existed on exactly one
+transport. As of **vgi-rpc 0.46.0** identity lives at the RPC layer, so it
+reaches every transport, and a client discovers it through ordinary reflection
+(`list_protocols`) rather than by calling and reading an error.
 
 ```python
 from vgi.auth import AuthUnavailableError, TokenIdentity
@@ -444,9 +450,11 @@ class MyWorker(Worker):
         return TokenIdentity(principal=row.principal, token_name=row.label)
 ```
 
-**The route does not exist until `resolve_token` is overridden** — absent, not
-routed-and-refusing. That is what keeps a dependency upgrade from growing a
-credential-to-identity oracle on every existing worker.
+**The protocol is not hosted until `resolve_token` is overridden** — absent,
+not hosted-and-refusing. That is what keeps a dependency upgrade from growing a
+credential-to-identity oracle on every existing worker. Only the methods whose
+hooks exist are registered, so a worker that resolves credentials but does not
+mint grants hosts `introspect_token` and not `issue_grant`.
 
 Enabling it also requires an allowlist of principals permitted to ask, via
 `--introspect-principals` or `VGI_INTROSPECT_PRINCIPALS`. There is no permissive

docs/api/auth.md

@@ -18,6 +18,10 @@ require `pip install vgi-python[http]`; JWT authentication additionally requires
 `principal` plus an optional `token_name`. It lives in a private `vgi-rpc` module, so `vgi.auth`
 re-exports it — a worker that implements `resolve_token` never has to name a private import path.
 
+As of vgi-rpc 0.46.0 introspection is the `vgi_rpc.Identity.v1` protocol hosted on the RPC server,
+not an HTTP JSON route, so it reaches every transport rather than only HTTP. `TokenIdentity` and
+`TokenResolver` are correspondingly no longer gated on the `[http]` extra.
+
 ## Secret protocol
 
 ::: vgi.secret_protocol

pyproject.toml

@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.45.1",
+    "vgi-rpc>=0.46.0",
     "httpx2>=2.9.1",
 ]
 

tests/test_serve.py

@@ -501,97 +501,137 @@ def test_override_is_detected(self) -> None:
         assert resolver("nope") is None
 
 
+def _introspector_ctx(principal: str) -> object:
+    """Build a ``CallContext`` for an authenticated caller named *principal*.
+
+    The identity guards read the caller off ``ctx.auth``, so this is the whole
+    input they need: the allowlist check compares ``auth.principal`` against
+    the configured principals and refuses anything not authenticated.
+    """
+    from vgi_rpc.rpc import AuthContext, CallContext
+
+    return CallContext(
+        auth=AuthContext(domain="test", authenticated=True, principal=principal),
+        emit_client_log=lambda *a, **k: None,
+    )
+
+
+def _hosted_protocols(worker_cls: type[Worker]) -> frozenset[str]:
+    """Return the protocol names the server built for *worker_cls* hosts.
+
+    Built the way :func:`vgi.serve.create_app` builds it, so this observes the
+    real routing table rather than a re-derivation of it. The protocol name is
+    the dispatch routing key as of vgi-rpc 0.46.0, so "is identity hosted" is
+    exactly "is its name in here".
+    """
+    from vgi_rpc.rpc import RpcServer
+
+    from vgi.protocol import VgiProtocol
+    from vgi.serve import _build_identity
+    from vgi.worker import _get_vgi_version
+
+    server = RpcServer(
+        VgiProtocol,
+        worker_cls(quiet=True),
+        enable_describe=False,
+        server_version=_get_vgi_version(),
+        identity=_build_identity(worker_cls, None, None),
+    )
+    return frozenset(server.bindings)
+
+
 class TestTokenIntrospection:
-    """``POST /__introspect_token__`` — absent unless a worker implements it."""
+    """``vgi_rpc.Identity.v1`` — unhosted unless a worker implements the hook.
+
+    Identity was an HTTP JSON route (``POST {prefix}/__introspect_token__``)
+    through vgi-rpc 0.45.x. As of 0.46.0 it is an RPC-layer protocol hosted on
+    the ``RpcServer``, so it reaches every transport rather than only HTTP and
+    a client discovers it through reflection rather than by calling and reading
+    an error. What this repo owns — and what these tests cover — is the
+    *wiring*: a ``resolve_token`` override becomes an ``IdentityImpl`` carrying
+    the configured allowlist, and nothing at all when the hook is absent. The
+    guards themselves (allowlist enforcement, uniform rejection, JWS-shape
+    refusal, rate limiting) live in vgi-rpc and are tested there.
+    """
 
     @staticmethod
-    def _client(worker_cls: type[Worker], **env: str) -> object:
-        import falcon.testing
-
-        from vgi.serve import _resolve_authenticate
+    def _identity(worker_cls: type[Worker], **env: str) -> object | None:
+        from vgi.serve import _build_identity
 
         with pytest.MonkeyPatch.context() as mp:
-            for key in ("VGI_INTROSPECT_PRINCIPALS", "VGI_INTROSPECT_RATE_LIMIT", "VGI_BEARER_TOKENS"):
+            for key in ("VGI_INTROSPECT_PRINCIPALS", "VGI_INTROSPECT_RATE_LIMIT"):
                 mp.delenv(key, raising=False)
             for key, value in env.items():
                 mp.setenv(key, value)
-            app = create_app(
-                worker_cls,
-                prefix="/vgi",
-                describe=False,
-                authenticate=_resolve_authenticate(),
-            )
-        return falcon.testing.TestClient(app)
+            return _build_identity(worker_cls, None, None)
 
-    def test_route_absent_without_hook(self) -> None:
-        """Not "routed and refusing" — absent.
+    def test_identity_absent_without_hook(self) -> None:
+        """Not "hosted and refusing" — absent.
 
         This is the property that keeps a dependency upgrade from silently
         growing a credential-to-identity oracle on every existing worker.
         """
-        client = self._client(_SingleWorker)
-        resp = client.simulate_post("/vgi/__introspect_token__", json={"token": "x"})  # type: ignore[attr-defined]
-        assert resp.status_code == 404
+        assert self._identity(_SingleWorker) is None
 
-    def test_capability_not_advertised_without_hook(self) -> None:
-        """A proxy preflighting at boot learns this worker cannot answer."""
-        app = create_app(_SingleWorker, prefix="/vgi", describe=False)
-        assert "vgi-token-introspection" not in _capability_headers(app)
+    def test_protocol_not_hosted_without_hook(self) -> None:
+        """The server built for such a worker hosts no identity protocol."""
+        assert "vgi_rpc.Identity.v1" not in _hosted_protocols(_SingleWorker)
+
+    def test_identity_built_with_hook(self) -> None:
+        """Implementing the hook is what builds the implementation."""
+        identity = self._identity(_IntrospectingWorker, VGI_INTROSPECT_PRINCIPALS="proxy-a")
+        assert identity is not None
+
+    def test_only_offered_methods_are_hosted(self) -> None:
+        """A worker that resolves but does not mint offers exactly one method.
 
-    def test_capability_advertised_with_hook(self) -> None:
-        """A proxy can discover support at boot rather than at first login."""
+        The protocol a server hosts describes what it actually does, so a
+        client learns ``issue_grant`` is unavailable from reflection rather
+        than from an error.
+        """
+        identity = self._identity(_IntrospectingWorker, VGI_INTROSPECT_PRINCIPALS="proxy-a")
+        assert identity is not None
+        assert identity.offered_methods() == frozenset({"introspect_token"})  # type: ignore[attr-defined]
+
+    def test_protocol_hosted_with_hook(self) -> None:
+        """A client preflighting via reflection discovers the worker can answer."""
         with pytest.MonkeyPatch.context() as mp:
             mp.setenv("VGI_INTROSPECT_PRINCIPALS", "proxy-a")
-            app = create_app(_IntrospectingWorker, prefix="/vgi", describe=False)
-        assert _capability_headers(app)["vgi-token-introspection"] == "true"
-
-    def test_allowlisted_caller_resolves(self) -> None:
-        """The endpoint answers with a principal and never with claims."""
-        client = self._client(
-            _IntrospectingWorker,
-            VGI_INTROSPECT_PRINCIPALS="proxy-a",
-            VGI_BEARER_TOKENS="ptok=proxy-a",
-        )
-        resp = client.simulate_post(  # type: ignore[attr-defined]
-            "/vgi/__introspect_token__",
-            json={"token": "good-token"},
-            headers={"Authorization": "Bearer ptok"},
-        )
-        assert resp.status_code == 200
-        assert resp.json == {"principal": "alice", "token_name": "deploy-key-1", "ttl_seconds": 300}
-        assert "claims" not in resp.json
-
-    def test_unresolvable_token_is_404(self) -> None:
-        """Unknown credential and unknown route answer alike, on purpose."""
-        client = self._client(
-            _IntrospectingWorker,
-            VGI_INTROSPECT_PRINCIPALS="proxy-a",
-            VGI_BEARER_TOKENS="ptok=proxy-a",
-        )
-        resp = client.simulate_post(  # type: ignore[attr-defined]
-            "/vgi/__introspect_token__",
-            json={"token": "nope"},
-            headers={"Authorization": "Bearer ptok"},
-        )
-        assert resp.status_code == 404
+            hosted = _hosted_protocols(_IntrospectingWorker)
+        assert "vgi_rpc.Identity.v1" in hosted
+
+    def test_resolver_answers_through_the_implementation(self) -> None:
+        """The worker's own lookup is what the hosted protocol calls."""
+        identity = self._identity(_IntrospectingWorker, VGI_INTROSPECT_PRINCIPALS="proxy-a")
+        assert identity is not None
+        resolved = identity.introspect_token("good-token", _introspector_ctx("proxy-a"))  # type: ignore[attr-defined]
+        assert resolved.principal == "alice"
+        assert resolved.token_name == "deploy-key-1"
+        # Never claims: a pass-through claims field would let a worker choose
+        # its caller's tenant routing and policy branch.
+        assert not hasattr(resolved, "claims")
+
+    def test_unresolvable_token_is_refused(self) -> None:
+        """Unknown, expired and malformed are deliberately one answer."""
+        from vgi_rpc.rpc._token_identity import TokenUnresolvedError
+
+        identity = self._identity(_IntrospectingWorker, VGI_INTROSPECT_PRINCIPALS="proxy-a")
+        assert identity is not None
+        with pytest.raises(TokenUnresolvedError):
+            identity.introspect_token("nope", _introspector_ctx("proxy-a"))  # type: ignore[attr-defined]
 
     def test_non_allowlisted_caller_refused(self) -> None:
         """Authenticating is not the same capability as introspecting.
 
         Without this, any user holding a valid credential could resolve any
         other user's credential to its owner.
         """
-        client = self._client(
-            _IntrospectingWorker,
-            VGI_INTROSPECT_PRINCIPALS="proxy-a",
-            VGI_BEARER_TOKENS="ptok=proxy-a,utok=user-b",
-        )
-        resp = client.simulate_post(  # type: ignore[attr-defined]
-            "/vgi/__introspect_token__",
-            json={"token": "good-token"},
-            headers={"Authorization": "Bearer utok"},
-        )
-        assert resp.status_code == 403
+        from vgi_rpc.rpc._token_identity import IntrospectionRefusedError
+
+        identity = self._identity(_IntrospectingWorker, VGI_INTROSPECT_PRINCIPALS="proxy-a")
+        assert identity is not None
+        with pytest.raises(IntrospectionRefusedError):
+            identity.introspect_token("good-token", _introspector_ctx("user-b"))  # type: ignore[attr-defined]
 
     def test_hook_without_allowlist_refuses_to_start(self) -> None:
         """Fail closed and loud, rather than defaulting to an open oracle."""

uv.lock

@@ -44,6 +44,14 @@
 class BadProtocol(VgiProtocol):
     """VgiProtocol surface with a deliberately incompatible version."""
 
+    # The *only* thing this fixture varies is the version. As of vgi-rpc
+    # 0.46.0 the protocol name is the dispatch routing key, and it defaults to
+    # the class name -- so without this line subclassing alone renames the
+    # protocol to ``BadProtocol``, the client's request for ``VgiProtocol``
+    # finds no such protocol hosted, and the caller gets
+    # ``ProtocolNotSupportedError`` before the version gate it came to test
+    # ever runs.
+    protocol_name: ClassVar[str] = "VgiProtocol"
     protocol_version: ClassVar[str] = BAD_PROTOCOL_VERSION
 
 

vgi/_test_fixtures/bad_protocol.py

@@ -9,7 +9,7 @@
     bearer_authenticate, bearer_authenticate_static, chain_authenticate,
     OAuthResourceMetadata, AuthUnavailableError
 
-Token introspection (requires ``vgi[http]``):
+Token introspection (always available):
     TokenIdentity, TokenResolver
 
 JWT auth (requires ``vgi[oauth]``):
@@ -19,12 +19,28 @@
 from __future__ import annotations
 
 import contextlib
+from collections.abc import Callable
 
 from vgi_rpc.rpc import AuthContext, CallContext
 
+# ``vgi_rpc.Identity.v1`` lives at the RPC layer as of vgi-rpc 0.46.0 -- it was
+# an HTTP JSON route (``POST {prefix}/__introspect_token__``) through 0.45.x,
+# which meant it existed on exactly one transport.  So this is no longer gated
+# on the ``http`` extra.  Still not re-exported by ``vgi_rpc.rpc`` itself, so
+# the private module remains the only import path; re-exported here so a worker
+# that implements ``resolve_token`` never has to name one.
+from vgi_rpc.rpc._token_identity import TokenIdentity
+
+#: What :meth:`vgi.worker.Worker.resolve_token` is.  Upstream dropped its own
+#: alias when identity moved to the RPC layer; it is spelled out here so the
+#: name ``vgi.auth.TokenResolver`` keeps working.
+TokenResolver = Callable[[str], "TokenIdentity | None"]
+
 __all__ = [
     "AuthContext",
     "CallContext",
+    "TokenIdentity",
+    "TokenResolver",
 ]
 
 # HTTP auth helpers — available when vgi[http] is installed.
@@ -41,16 +57,9 @@
         parse_device_code_client_secret,
     )
 
-    # Not re-exported by ``vgi_rpc.http`` itself, so the private module is the
-    # only import path.  Re-exported here so a worker that implements
-    # ``resolve_token`` never has to name a private module.
-    from vgi_rpc.http.server._introspect import TokenIdentity, TokenResolver  # noqa: F401
-
     __all__ += [
         "AuthUnavailableError",
         "OAuthResourceMetadata",
-        "TokenIdentity",
-        "TokenResolver",
         "bearer_authenticate",
         "bearer_authenticate_static",
         "chain_authenticate",