vgi-python 0.36.2__tar.gz → 0.37.0__tar.gz

{vgi_python-0.36.2 → vgi_python-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.36.2
+Version: 0.37.0
 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

{vgi_python-0.36.2 → vgi_python-0.37.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.36.2"
+version = "0.37.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [

{vgi_python-0.36.2 → vgi_python-0.37.0}/tests/test_serve.py

@@ -24,7 +24,7 @@ from vgi_rpc import (
 from vgi_rpc.rpc import AuthContext, PeerResolutionContext, peer_identity_primary
 
 from vgi.arguments import Arguments, Auth, Param, Returns
-from vgi.auth import TokenIdentity
+from vgi.auth import IssuedGrant, TokenIdentity
 from vgi.client import Client
 from vgi.scalar_function import ScalarFunction
 from vgi.serve import (
@@ -486,6 +486,32 @@ class _IntrospectingWorker(Worker):
         return None
 
 
+class _MintingWorker(Worker):
+    """Worker that implements only the optional grant-minting hook."""
+
+    functions = [_DoubleFunc]
+
+    @classmethod
+    def mint_grant(cls, principal: str, purpose: str, scopes: list[str], ttl_seconds: int) -> IssuedGrant:
+        # A sealed self-contained credential: the worker owns the format and
+        # the framework never parses it. Capped TTL, to pin that a worker may
+        # issue SHORTER than asked.
+        ttl = min(ttl_seconds, 3600)
+        return IssuedGrant(
+            token=f"sealed:{principal}:{':'.join(scopes)}:{purpose}",
+            expires_at=1_000_000.0 + ttl,
+            grant_id="grant-1",
+        )
+
+
+class _BothWorker(_IntrospectingWorker):
+    """Worker that both resolves credentials and mints grants."""
+
+    @classmethod
+    def mint_grant(cls, principal: str, purpose: str, scopes: list[str], ttl_seconds: int) -> IssuedGrant:
+        return IssuedGrant(token=f"sealed:{principal}", expires_at=1_000_000.0, grant_id="g")
+
+
 class TestIntrospectResolverDetection:
     """``resolve_token`` presence is detected by override, not by a flag."""
 
@@ -516,6 +542,31 @@ def _introspector_ctx(principal: str) -> object:
     )
 
 
+def _minting_ctx(principal: str, *, auth_age_s: float = 0.0) -> object:
+    """Build a ``CallContext`` for a caller who authenticated *auth_age_s* ago.
+
+    Minting reads ``auth_time`` off the credential's claims, and a credential
+    without one cannot mint at all. That single rule is what stops a grant
+    minting another grant — a grant is not IdP-issued, so it carries no
+    ``auth_time`` — and what makes a static bearer token, which proves a
+    machine holds a secret rather than that a human just authenticated,
+    fail closed here.
+    """
+    import time
+
+    from vgi_rpc.rpc import AuthContext, CallContext
+
+    return CallContext(
+        auth=AuthContext(
+            domain="test",
+            authenticated=True,
+            principal=principal,
+            claims={"auth_time": time.time() - auth_age_s},
+        ),
+        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.
 
@@ -655,6 +706,111 @@ class TestTokenIntrospection:
             create_app(_IntrospectingWorker, prefix="/vgi", describe=False)
 
 
+class TestGrantMinting:
+    """``issue_grant`` — the other half of ``vgi_rpc.Identity.v1``.
+
+    Guarded very differently from ``introspect_token``, and deliberately so.
+    Introspection answers a question about *somebody else's* credential, so it
+    needs an allowlist. Minting produces a credential for the *caller* — there
+    is no subject on the wire, so cross-subject minting is closed by
+    construction and no allowlist applies. What this repo owns is the wiring:
+    a ``mint_grant`` override becomes an ``IdentityImpl`` that offers the
+    method, and a worker that never wrote one does not host it.
+    """
+
+    @staticmethod
+    def _identity(worker_cls: type[Worker], **env: str) -> object:
+        from vgi.serve import _build_identity
+
+        with pytest.MonkeyPatch.context() as mp:
+            mp.delenv("VGI_INTROSPECT_PRINCIPALS", raising=False)
+            for key, value in env.items():
+                mp.setenv(key, value)
+            return _build_identity(worker_cls, None)
+
+    def test_base_worker_has_no_minter(self) -> None:
+        """A worker that never wrote the minting gets no issuer."""
+        assert _SingleWorker._grant_minter() is None
+
+    def test_override_is_detected(self) -> None:
+        """Implementing the hook is what enables it."""
+        minter = _MintingWorker._grant_minter()
+        assert minter is not None
+
+    def test_minting_alone_hosts_the_protocol(self) -> None:
+        """A worker may mint without resolving — the two are independent."""
+        assert "vgi_rpc.Identity.v1" in _hosted_protocols(_MintingWorker)
+
+    def test_minting_alone_offers_only_issue_grant(self) -> None:
+        """The protocol describes what the worker does, not what it could do."""
+        identity = self._identity(_MintingWorker)
+        assert identity is not None
+        assert identity.offered_methods() == frozenset({"issue_grant"})  # type: ignore[attr-defined]
+
+    def test_minting_alone_needs_no_introspect_allowlist(self) -> None:
+        """No allowlist is required to mint: a grant is not an oracle.
+
+        Requiring one would be a startup error for a worker that never exposes
+        anybody else's identity — the exact opposite of the guard's purpose.
+        """
+        with pytest.MonkeyPatch.context() as mp:
+            mp.delenv("VGI_INTROSPECT_PRINCIPALS", raising=False)
+            create_app(_MintingWorker, prefix="/vgi", describe=False)
+
+    def test_both_hooks_offer_both_methods(self) -> None:
+        """Resolving and minting compose."""
+        identity = self._identity(_BothWorker, VGI_INTROSPECT_PRINCIPALS="proxy-a")
+        assert identity is not None
+        assert identity.offered_methods() == frozenset({"introspect_token", "issue_grant"})  # type: ignore[attr-defined]
+
+    def test_the_caller_is_the_subject(self) -> None:
+        """The framework supplies the principal; the wire method has no subject field.
+
+        This is the property that makes an allowlist unnecessary, so pin it
+        here rather than trusting the signature to stay that way.
+        """
+        identity = self._identity(_MintingWorker)
+        assert identity is not None
+        grant = identity.issue_grant(  # type: ignore[attr-defined]
+            "nightly-etl", ["read"], 600, _minting_ctx("alice")
+        )
+        assert grant.token.startswith("sealed:alice:")
+        assert grant.grant_id == "grant-1"
+
+    def test_a_worker_may_issue_a_shorter_ttl_than_asked(self) -> None:
+        """A worker may narrow the request; it must never widen it."""
+        identity = self._identity(_MintingWorker)
+        assert identity is not None
+        grant = identity.issue_grant(  # type: ignore[attr-defined]
+            "long", [], 86_400, _minting_ctx("alice")
+        )
+        assert grant.expires_at == 1_000_000.0 + 3600
+
+    def test_stale_authentication_cannot_mint(self) -> None:
+        """Minting while the user is present is enforced, not just documented."""
+        from vgi_rpc.rpc._token_identity import StaleAuthError
+
+        identity = self._identity(_MintingWorker)
+        assert identity is not None
+        with pytest.raises(StaleAuthError):
+            identity.issue_grant("x", [], 60, _minting_ctx("alice", auth_age_s=86_400))  # type: ignore[attr-defined]
+
+    def test_a_credential_with_no_auth_time_cannot_mint(self) -> None:
+        """A grant cannot mint another grant, and a static bearer cannot mint at all.
+
+        Neither carries ``auth_time`` — only an IdP-issued credential does — so
+        the lineage cannot escape the identity provider. This is the rule that
+        makes delegation accountable to a human login rather than to whoever
+        currently holds a machine secret.
+        """
+        from vgi_rpc.rpc._token_identity import StaleAuthError
+
+        identity = self._identity(_MintingWorker)
+        assert identity is not None
+        with pytest.raises(StaleAuthError):
+            identity.issue_grant("x", [], 60, _introspector_ctx("etl-service"))  # type: ignore[attr-defined]
+
+
 class TestAuthUnavailableReExport:
     """``AuthUnavailableError`` is reachable without naming a vgi_rpc module."""
 

{vgi_python-0.36.2 → vgi_python-0.37.0}/uv.lock

@@ -2580,7 +2580,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.36.2"
+version = "0.37.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.36.2 → vgi_python-0.37.0}/vgi/auth.py

@@ -9,8 +9,8 @@ HTTP auth factories (require ``vgi[http]``):
     bearer_authenticate, bearer_authenticate_static, chain_authenticate,
     OAuthResourceMetadata, AuthUnavailableError
 
-Token introspection (always available):
-    TokenIdentity, TokenResolver
+Token introspection and delegation (always available):
+    TokenIdentity, TokenResolver, IssuedGrant, GrantMinter
 
 JWT auth (requires ``vgi[oauth]``):
     jwt_authenticate
@@ -30,16 +30,25 @@ from vgi_rpc.rpc import AuthContext, CallContext
 # 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
+from vgi_rpc.rpc._token_identity import IssuedGrant, 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"]
 
+#: What :meth:`vgi.worker.Worker.mint_grant` is: ``(principal, purpose, scopes,
+#: ttl_seconds) -> IssuedGrant``.  The subject is a *parameter of the call the
+#: framework makes*, never of the wire method — ``issue_grant`` has no subject
+#: field, so a worker is handed the caller's own principal and cannot be asked
+#: to mint for anybody else.
+GrantMinter = Callable[[str, str, list[str], int], "IssuedGrant"]
+
 __all__ = [
     "AuthContext",
     "CallContext",
+    "GrantMinter",
+    "IssuedGrant",
     "TokenIdentity",
     "TokenResolver",
 ]

{vgi_python-0.36.2 → vgi_python-0.37.0}/vgi/serve.py

@@ -791,9 +791,12 @@ def _build_identity(
 ) -> IdentityImpl | None:
     """Build the ``vgi_rpc.Identity.v1`` implementation, or ``None``.
 
-    ``None`` unless the worker class actually implements the lookup, and that
-    is the point: ``RpcServer`` then does not host the protocol at all, rather
-    than hosting it and refusing every call. Absent beats routed-and-refusing —
+    ``None`` unless the worker class implements at least one of the two
+    methods, and that is the point: ``RpcServer`` then does not host the
+    protocol at all, rather than hosting it and refusing every call. The two
+    are independent — a worker may resolve credentials without minting them,
+    mint without resolving, or do both, and ``offered_methods()`` reports
+    exactly what it wrote. Absent beats routed-and-refusing —
     it is what keeps a dependency upgrade from growing a
     credential-to-identity oracle on every existing worker.
 
@@ -804,8 +807,8 @@ def _build_identity(
     calling and reading an error.
 
     Args:
-        worker_cls: The worker class, consulted for a ``resolve_token``
-            override.
+        worker_cls: The worker class, consulted for ``resolve_token`` and
+            ``mint_grant`` overrides.
         introspect_principals: Principals permitted to introspect, or ``None``
             to read the environment.
 
@@ -815,7 +818,8 @@ def _build_identity(
 
     """
     resolver = worker_cls._introspect_resolver()
-    if resolver is None:
+    minter = worker_cls._grant_minter()
+    if resolver is None and minter is None:
         return None
 
     # Not re-exported by ``vgi_rpc.rpc``, so the private module is the only
@@ -824,7 +828,11 @@ def _build_identity(
 
     return IdentityImpl(
         resolve_token=resolver,
-        introspect_principals=_resolve_introspect_principals(introspect_principals),
+        mint_grant=minter,
+        # Only meaningful for ``introspect_token``, and ``IdentityImpl``
+        # validates it only when a resolver is supplied — a worker that mints
+        # grants but resolves nothing is not an oracle and needs no allowlist.
+        introspect_principals=(_resolve_introspect_principals(introspect_principals) if resolver is not None else None),
     )
 
 

{vgi_python-0.36.2 → vgi_python-0.37.0}/vgi/worker.py

@@ -173,7 +173,7 @@ if TYPE_CHECKING:
     from ssl import SSLContext
 
     from vgi_rpc.rpc import PeerAuthenticationPolicy, PeerIdentityProvider
-    from vgi_rpc.rpc._token_identity import TokenIdentity
+    from vgi_rpc.rpc._token_identity import IssuedGrant, TokenIdentity
 
     from vgi.catalog.descriptors import Catalog
     from vgi.protocol import (
@@ -1478,6 +1478,80 @@ class Worker:
             return None
         return cls.resolve_token
 
+    @classmethod
+    def mint_grant(cls, principal: str, purpose: str, scopes: list[str], ttl_seconds: int) -> IssuedGrant:
+        """Mint a standing delegation credential for *principal*.
+
+        Override to host ``vgi_rpc.Identity.v1``'s ``issue_grant``. Like
+        ``resolve_token``, the method is absent until it is overridden rather
+        than hosted-and-refusing, so no worker grows a credential *issuer* by
+        upgrading a dependency.
+
+        OAuth cannot express durable delegation: it fuses the grant, the
+        credential and the session into one refresh token, so an IdP shortening
+        session lifetime shortens the grant. This mints the durable record —
+        created while the user is present, presented later by unattended
+        automation as an ordinary bearer.
+
+        **There is no subject on the wire.** ``issue_grant`` takes no subject
+        field; the framework passes the *caller's own* authenticated principal,
+        so cross-subject minting is closed by construction rather than by a
+        check that could be forgotten. That is also why this needs no allowlist
+        while ``introspect_token`` has one — it is not an oracle about anybody
+        else. The framework additionally refuses a caller whose authentication
+        is stale (``max_auth_age``, 15 minutes by default), because "minted
+        while the user is present" is the property that makes a grant
+        accountable to them.
+
+        ``IssuedGrant.token`` is **opaque to the framework** — a sealed
+        envelope, a database row, or a credential brokered from the IdP are all
+        equally valid and equally invisible here. It is never parsed and never
+        logged. Note that a self-contained sealed token cannot be revoked
+        individually: with no server-side record there is nothing to delete,
+        and rotating the sealing key invalidates every grant at once. If
+        per-grant revocation matters, the token has to name something the
+        worker can look up and remove.
+
+        Args:
+            principal: The caller's authenticated principal, in the form this
+                worker derives itself. Supplied by the framework, never by the
+                caller.
+            purpose: Free-text reason recorded with the grant, for the audit
+                trail.
+            scopes: Scopes the grant is limited to. A worker that ignores this
+                is issuing a credential broader than the caller asked for.
+            ttl_seconds: Lifetime the caller requested. A worker may issue a
+                shorter one — and should say so in ``expires_at`` — but must
+                never issue a longer one.
+
+        Returns:
+            The minted ``IssuedGrant``. ``expires_at`` is a declaration rather
+            than an enforcement: the real lifetime lives inside the opaque
+            token, so a worker that states one has thought about one.
+
+        Raises:
+            GrantRefusedError: When this caller may not mint this grant —
+                an unsupported scope, a ttl beyond policy, a principal the
+                worker declines to delegate for.
+
+        """
+        from vgi_rpc.rpc._token_identity import GrantRefusedError
+
+        raise GrantRefusedError("this worker does not mint grants")
+
+    @classmethod
+    def _grant_minter(cls) -> Callable[[str, str, list[str], int], IssuedGrant] | None:
+        """Return this worker's grant minter, or ``None`` when it has none.
+
+        Identity comparison against the base implementation, for the same
+        reason ``_introspect_resolver`` uses one: the method must be absent
+        unless a worker actually wrote the minting, and a "supports grants"
+        flag can be set without one.
+        """
+        if cls.mint_grant.__func__ is Worker.mint_grant.__func__:  # type: ignore[attr-defined]
+            return None
+        return cls.mint_grant
+
     @final
     @classmethod
     def main(cls) -> None: