vgi-python 0.41.0__py3-none-any.whl → 0.42.0__py3-none-any.whl

vgi/_duckdb.py

@@ -7,8 +7,8 @@ engine (expression-filter evaluation, the transactor, the statistics
 fixtures) resolves it through this module, which prefers Query Farm's
 ``haybarn`` distribution when installed and falls back to stock ``duckdb``.
 
-Install one via the extras: ``pip install vgi[haybarn]`` (preferred) or
-``pip install vgi[duckdb]``.
+Install one via the extras: ``pip install 'vgi-python[haybarn]'`` (preferred) or
+``pip install 'vgi-python[duckdb]'``.
 """
 
 from __future__ import annotations
@@ -50,7 +50,7 @@ def engine_module() -> ModuleType:
         else:
             raise ImportError(
                 "No DuckDB-compatible engine is installed. Install 'haybarn' (preferred) "
-                "or 'duckdb', e.g. `pip install vgi[haybarn]` or `pip install vgi[duckdb]`."
+                "or 'duckdb', e.g. `pip install 'vgi-python[haybarn]'` or `pip install 'vgi-python[duckdb]'`."
             )
     return _engine
 

vgi/_test_fixtures/http_server.py

@@ -372,7 +372,7 @@ def main() -> None:
         from vgi._test_fixtures.catalog_contents import CONTENTS_WORKERS
         from vgi._test_fixtures.narrow_bind.worker import NarrowBindWorker
         from vgi._test_fixtures.twin_catalogs import TwinAWorker, TwinBWorker
-        from vgi.rpc_server import build_rpc_server
+        from vgi.rpc_server import build_rpc_server, resolve_grant_keys
 
         worker_classes: list[type] = [
             ExampleWorker,
@@ -408,6 +408,7 @@ def main() -> None:
             describe=describe,
             external_location=external_location,
             introspect_principals=introspect_principals,
+            grant_keys=resolve_grant_keys(),
         )
         wsgi_app = make_wsgi_app(
             server,

vgi/_test_fixtures/identity_fixture.py

@@ -61,12 +61,18 @@ class IdentityExampleWorker(ExampleWorker):
 def conformance_authenticate(req: Any) -> AuthContext:
     """Derive the caller from ``X-Conformance-Principal`` / ``X-Conformance-Auth-Time``.
 
-    An absent principal header means *unauthenticated*. The auth-time header is
+    An absent principal header means *unauthenticated*, unless an
+    ``Authorization`` header is present: that request falls through to the
+    sealed-grant and ``resolve_token`` bearers. The auth-time header is
     placed in the claims verbatim and unparsed, because the guard does the
     parsing and the fixture only carries the value.
     """
     principal = req.get_header(PRINCIPAL_HEADER)
     if not principal:
+        if req.get_header("Authorization"):
+            # A bearer is not ours: fall through to the identity bearer
+            # authenticators vgi-rpc appends (sealed grants, resolve_token).
+            raise ValueError("no conformance principal header")
         return AuthContext(domain=None, authenticated=False, principal=None)
     claims: dict[str, object] = {}
     auth_time = req.get_header(AUTH_TIME_HEADER)

vgi/rpc_server.py

@@ -34,13 +34,14 @@ from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
     from vgi_rpc.external import ExternalLocationConfig
+    from vgi_rpc.grants import GrantKeys
     from vgi_rpc.rpc import RpcServer
     from vgi_rpc.rpc._token_identity import IdentityImpl
 
     from vgi.meta_worker import MetaWorker
     from vgi.worker import Worker
 
-__all__ = ["Transport", "build_rpc_server"]
+__all__ = ["Transport", "build_rpc_server", "resolve_grant_keys"]
 
 Transport = Literal["pipe", "unix", "tcp", "iroh", "http"]
 """The transport a server is being built for.
@@ -65,6 +66,7 @@ def build_rpc_server(
     transport: Transport,
     describe: bool = True,
     introspect_principals: Iterable[str] | None = None,
+    grant_keys: GrantKeys | None = None,
     external_location: ExternalLocationConfig | None = None,
     otel_config: Any = None,
 ) -> RpcServer:
@@ -83,6 +85,11 @@ def build_rpc_server(
         introspect_principals: HTTP only. Principals permitted to call
             ``introspect_token``; ``None`` reads ``VGI_INTROSPECT_PRINCIPALS``.
             Only consulted when the worker overrides ``resolve_token``.
+        grant_keys: HTTP only. Sealed-grant configuration (see
+            [`resolve_grant_keys`][vgi.rpc_server.resolve_grant_keys]). When
+            given, Identity is hosted even without hooks: the framework mints
+            sealed grants unless the worker overrides ``mint_grant``, and the
+            HTTP server accepts them back as bearer credentials.
         external_location: Optional external-storage configuration for large
             batches (HTTP).
         otel_config: Optional ``OtelConfig``. When given, the server is
@@ -116,13 +123,18 @@ def build_rpc_server(
     if transport in _IDENTITY_TRANSPORTS:
         # A Worker's hooks are classmethods; a MetaWorker answers for the one
         # child that implements each hook.
-        identity = _build_identity(type(worker) if isinstance(worker, Worker) else worker, introspect_principals)
+        identity = _build_identity(
+            type(worker) if isinstance(worker, Worker) else worker, introspect_principals, grant_keys
+        )
 
     server = RpcServer(
         primary,
         worker,
         extra_protocols=extra,
         identity=identity,
+        # Explicit, never vgi-rpc's "env" default: grants are an HTTP-only
+        # identity feature here, and the caller resolved them already.
+        grant_keys=grant_keys if transport in _IDENTITY_TRANSPORTS else None,
         external_location=external_location,
         enable_describe=describe,
         server_version=_get_vgi_version(),
@@ -191,6 +203,7 @@ def _validated_hosted_protocols(worker: Worker | MetaWorker, primary: type) -> t
 def _build_identity(
     worker_cls: type[Worker] | MetaWorker,
     introspect_principals: Iterable[str] | None,
+    grant_keys: GrantKeys | None = None,
 ) -> IdentityImpl | None:
     """Build the ``vgi_rpc.Identity.v1`` implementation, or ``None``.
 
@@ -217,6 +230,9 @@ def _build_identity(
             the one child class that overrides each.
         introspect_principals: Principals permitted to introspect, or ``None``
             to read the environment.
+        grant_keys: Sealed-grant configuration. When given, Identity is built
+            even with no hook, and mints sealed grants unless the worker
+            overrides ``mint_grant``.
 
     Returns:
         The implementation, or ``None`` when this worker does not resolve
@@ -225,7 +241,7 @@ def _build_identity(
     """
     resolver = worker_cls._introspect_resolver()
     minter = worker_cls._grant_minter()
-    if resolver is None and minter is None:
+    if resolver is None and minter is None and grant_keys is None:
         return None
 
     # Not re-exported by ``vgi_rpc.rpc``, so the private module is the only
@@ -239,6 +255,9 @@ def _build_identity(
         # 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),
+        # With keys and no mint_grant override, IdentityImpl mints sealed
+        # grants itself; the HTTP server then accepts them as bearers.
+        grant_keys=grant_keys,
     )
 
 
@@ -285,3 +304,37 @@ def _resolve_introspect_principals(explicit: Iterable[str] | None) -> list[str]:
         )
         sys.exit(1)
     return principals
+
+
+def resolve_grant_keys(explicit: Sequence[str] | None = None) -> GrantKeys | None:
+    """Resolve the sealed-grant configuration, or exit with an actionable message.
+
+    Grants are opt-in: with no key configured this returns ``None`` and
+    nothing changes. Keys come from *explicit* (``--grant-key``, repeatable)
+    or else ``VGI_RPC_GRANT_KEYS`` (comma-separated). Either way
+    ``VGI_RPC_GRANT_AUDIENCE`` and ``VGI_RPC_GRANT_MAX_TTL_SECONDS`` (default
+    7 days) apply. Each key is standard base64 of exactly 32 bytes; the first
+    mints and every key verifies, which is how keys rotate.
+
+    Args:
+        explicit: Keys given on the command line, or ``None`` to read the
+            environment.
+
+    Returns:
+        The configuration, or ``None`` when no key is configured.
+
+    Raises:
+        SystemExit: A key or lifetime is malformed. A worker refuses to start
+            rather than run with a key it misread.
+
+    """
+    from vgi_rpc.grants import GRANT_KEYS_ENV, GrantKeys
+
+    env: dict[str, str] = dict(os.environ)
+    if explicit:
+        env[GRANT_KEYS_ENV] = ",".join(explicit)
+    try:
+        return GrantKeys.from_env(env)
+    except ValueError as exc:
+        sys.stderr.write(f"Error: invalid sealed-grant configuration ({GRANT_KEYS_ENV} / --grant-key): {exc}\n")
+        sys.exit(1)

vgi/serve.py

@@ -41,6 +41,7 @@ from vgi.profiling import maybe_start_profile
 
 if TYPE_CHECKING:
     import falcon
+    from vgi_rpc.grants import GrantKeys
     from vgi_rpc.otel import OtelConfig
     from vgi_rpc.rpc import AuthContext, PeerAuthenticationPolicy, PeerIdentityProvider
 
@@ -216,6 +217,7 @@ def create_app(
     max_stream_response_bytes: int | None = None,
     max_externalized_response_bytes: int | None = None,
     introspect_principals: Iterable[str] | None = None,
+    grant_keys: GrantKeys | None = None,
     iroh_bridge_issuer: str | None = None,
     iroh_trusted_proxy_addresses: Iterable[str] = (),
     iroh_authenticate: bool = True,
@@ -277,6 +279,16 @@ def create_app(
             ``vgi_rpc.Identity.v1``'s ``introspect_token``.  Only consulted
             when the worker class overrides ``resolve_token``.  ``None`` reads
             ``VGI_INTROSPECT_PRINCIPALS``.
+        grant_keys: Sealed-grant configuration. ``None`` reads
+            ``VGI_RPC_GRANT_KEYS`` (see
+            [`resolve_grant_keys`][vgi.rpc_server.resolve_grant_keys]); no key
+            configured means grants are off. With keys, ``issue_grant`` mints
+            sealed grants (unless the worker overrides ``mint_grant``) and
+            requests may present them as ``Authorization: Bearer <grant>``.
+            Independently, a worker that overrides ``resolve_token`` has it
+            consulted for bearer credentials. Both come after *authenticate*
+            in the chain, so the deployment's own authenticator answers first
+            and must raise ``ValueError`` for a credential it does not know.
         iroh_bridge_issuer: Operator-controlled identity namespace for an
             ``iroh-http/2`` bridge. ``None`` disables Iroh header trust.
         iroh_trusted_proxy_addresses: Exact immediate bridge addresses.
@@ -297,7 +309,7 @@ def create_app(
         sys.exit(1)
 
     from vgi.otel import VgiTracer
-    from vgi.rpc_server import build_rpc_server
+    from vgi.rpc_server import build_rpc_server, resolve_grant_keys
 
     # Resolve the signing key once, here, so the worker (which seals catalog
     # opaque-data envelopes) and the HTTP state-token machinery share the same
@@ -319,7 +331,9 @@ def create_app(
         transport="http",
         describe=describe,
         introspect_principals=introspect_principals,
+        grant_keys=grant_keys if grant_keys is not None else resolve_grant_keys(),
     )
+    authenticate, identity_bearer = _compose_identity_bearer(server, authenticate)
 
     effective_peer_identity_providers = tuple(peer_identity_providers)
     effective_peer_authentication_policy = peer_authentication_policy
@@ -356,6 +370,7 @@ def create_app(
         max_stream_response_bytes=max_stream_response_bytes,
         max_externalized_response_bytes=max_externalized_response_bytes,
         enable_landing_page=False,
+        identity_bearer=identity_bearer,
     )
 
     # Frontend: either redirect to external CDN or serve pre-rendered worker page
@@ -490,6 +505,16 @@ def main() -> None:
                 "that case, with no permissive default. Env: VGI_INTROSPECT_PRINCIPALS."
             ),
         ),
+        grant_key: list[str] | None = typer.Option(  # noqa: B008
+            None,
+            "--grant-key",
+            help=(
+                "Sealed-grant key: standard base64 of 32 bytes; repeat to rotate (the first "
+                "mints, all verify). Enables issue_grant without a mint_grant override and "
+                "accepts the grants as HTTP bearer credentials. Env: VGI_RPC_GRANT_KEYS "
+                "(comma-separated), VGI_RPC_GRANT_AUDIENCE, VGI_RPC_GRANT_MAX_TTL_SECONDS."
+            ),
+        ),
         access_log_sample: float | None = typer.Option(  # noqa: B008
             None,
             "--access-log-sample",
@@ -573,6 +598,7 @@ def main() -> None:
                 max_stream_response_bytes=max_stream_response_bytes,
                 max_externalized_response_bytes=max_externalized_response_bytes,
                 introspect_principals=introspect_principals,
+                grant_keys=grant_key,
                 server=server,
                 worker_ref=worker_ref,
                 http_workers=http_workers,
@@ -770,7 +796,44 @@ def _resolve_authenticate() -> Callable[..., Any] | None:
     # this worker", with user identity handled upstream.
     from vgi_rpc.http import require_all
 
-    return require_all(gate, inner)
+    gated = require_all(gate, inner)
+    # Kept so create_app can put the identity bearers (sealed grants,
+    # resolve_token) inside the gate rather than beside it.
+    setattr(gated, _PROXY_GATE_PARTS_ATTR, (gate, inner))
+    return gated
+
+
+#: Attribute on a proxy-gated authenticator holding its ``(gate, inner)``.
+_PROXY_GATE_PARTS_ATTR = "_vgi_proxy_gate_parts"
+
+
+def _compose_identity_bearer(
+    server: Any,
+    authenticate: Callable[..., Any] | None,
+) -> tuple[Callable[..., Any] | None, bool]:
+    """Return ``(authenticate, identity_bearer)`` for ``make_wsgi_app``.
+
+    vgi-rpc appends the identity bearers (sealed grants, then the worker's
+    ``resolve_token``) after *authenticate* itself. It refuses when
+    *authenticate* depends on proxy-injected evidence, because an OR beside a
+    proxy-proof gate would let a grant bypass it. VGI's own gate
+    (``VGI_PROXY_PROOF_MODE``) is built by :func:`_resolve_authenticate`, so
+    here the bearers go *inside* it: ``require_all(gate, inner, then grants,
+    then resolve_token)``. Any other authenticator is left to vgi-rpc.
+    """
+    identity = getattr(server, "identity", None)
+    parts = getattr(authenticate, _PROXY_GATE_PARTS_ATTR, None)
+    if identity is None or parts is None:
+        return authenticate, True
+    if identity.grant_keys is None and identity.resolve_token_hook is None:
+        return authenticate, True
+    from vgi_rpc.http import compose_identity_authenticate, require_all
+
+    gate, inner = parts
+    composed = compose_identity_authenticate(
+        inner, grant_keys=identity.grant_keys, resolve_token=identity.resolve_token_hook
+    )
+    return require_all(gate, composed), False
 
 
 def _resolve_proxy_proof_gate() -> Any | None:
@@ -1352,6 +1415,7 @@ def _serve_http(
     max_stream_response_bytes: int | None = None,
     max_externalized_response_bytes: int | None = None,
     introspect_principals: str | None = None,
+    grant_keys: Sequence[str] | None = None,
     server: str = "waitress",
     worker_ref: str | None = None,
     http_workers: int | None = None,
@@ -1369,6 +1433,13 @@ def _serve_http(
     # export_serve_config for why the environment is the channel.
     if introspect_principals is not None:
         os.environ["VGI_INTROSPECT_PRINCIPALS"] = introspect_principals
+    if grant_keys:
+        from vgi_rpc.grants import GRANT_KEYS_ENV
+
+        from vgi.rpc_server import resolve_grant_keys
+
+        resolve_grant_keys(grant_keys)  # a malformed key stops startup here
+        os.environ[GRANT_KEYS_ENV] = ",".join(grant_keys)
 
     if server == "granian":
         _serve_http_granian(

{vgi_python-0.41.0.dist-info → vgi_python-0.42.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.41.0
+Version: 0.42.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
@@ -162,7 +162,7 @@ Requires-Dist: httpx2>=2.12.0
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.48.0
+Requires-Dist: vgi-rpc>=0.49.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.41.0.dist-info → vgi_python-0.42.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 vgi/__init__.py,sha256=8uLMNQcNzWjp8VzYtj2u98_Wp8WpB8c_dKlMv67TH0g,5384
-vgi/_duckdb.py,sha256=YB5D7N3Bwg_xP6X8a5QlumtlAovSej1A1Go5XlNGVko,2162
+vgi/_duckdb.py,sha256=Tu8Yb4vABRv4yOMo7qul8LxG_wH5ZqZuOCSSjyiMgbY,2198
 vgi/_storage_profile.py,sha256=VkTsXojuE0tHEzurmteQSAiL1vI3CZSgYkL6D_h8GvE,5061
 vgi/aggregate_function.py,sha256=NYxudbvQ9ZLkP2w5hRdd4YgsGUZ_0cVfqqXnlmJPfls,27389
 vgi/argument_spec.py,sha256=SADH97VlFu3asI8CWZ_I7XTuSxwqFciFgdupdAf-tkY,34231
@@ -25,13 +25,13 @@ vgi/profiling.py,sha256=rK7vij3oHhXC3JHI2BsMySsXh7_hrXi0aXpCW8iFSIc,3671
 vgi/protocol.py,sha256=J9vaxstGvxe4Vmlf_Aij9HkabGbdFx_nEsQI_m-V7ak,175438
 vgi/protocol_version.txt,sha256=yJuHwmLp1f_SDnOqx0oXcq3Mn1ohaCzDOtz1CG5f71w,6
 vgi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vgi/rpc_server.py,sha256=KLFgOxnpFWRMkj9nR7HnrMBkqn1ahFuIOqgwd6RJ27o,12444
+vgi/rpc_server.py,sha256=Qdqi6rHkX78SYXUZqG5D-a9NR0ZtGoxW22he0J9xS-0,14914
 vgi/scalar_function.py,sha256=YBy5s4eEBYTMjACGPE-8-82BObyJoM9qt9cnm24b_RQ,53485
 vgi/schema_path.py,sha256=GVlkZlCUj7GbVhgiocSMC6Ff5iTJhKqiYE62hMIEKiI,2403
 vgi/schema_utils.py,sha256=zQCliUgIpO2u77Mhtgg3OFvOEDNgJopu6kj2fw8YP1I,7945
 vgi/secret_protocol.py,sha256=iCDl7nF7Nb4cJV4vpfbldunTDqDJWzCzS7uCmOACf7U,7151
 vgi/secret_service.py,sha256=r7qCzfnOMirf9wSCUe-mgFe3z6v9_cDRzixuSAZG_bs,8973
-vgi/serve.py,sha256=UATWrggJe0TrcjEguC0P-vNN4UOMceEOqJl_3B2qV2Q,59899
+vgi/serve.py,sha256=V56NcO9VzWaMlkUCXumLBsfMEZ8oZeckT_EJ9sumsQc,63442
 vgi/split_token.py,sha256=tutcksj-hgWrLY7UW3sSqkyoaD-cMqNTOeff40MGl_g,10850
 vgi/table_buffering_function.py,sha256=SI6yLAcs8WBHqS6TeaZ92s-Q6GXn0ReROyQWDujw2iA,19554
 vgi/table_filter_pushdown.py,sha256=4Qo4OAOLjTYQ5pinNTOjLCDnb96OHqpcxJlbSJo3cJU,67144
@@ -50,8 +50,8 @@ vgi/_test_fixtures/companion.py,sha256=Ya_rg2J4tXOYC7zBFOjTTh-4AYuRhJN5BT4tVZULQ
 vgi/_test_fixtures/copy_from.py,sha256=YAWametIhrKE_K_kRwx37QpKMY0yBWAordE5-cNVn4M,6134
 vgi/_test_fixtures/copy_to.py,sha256=fFHxPYVd0wfAfMEvpeBRijqUasBeoAGREY3kHmm_oK8,9667
 vgi/_test_fixtures/global_functions.py,sha256=G1h0w5o6bHMULDFLZuNjrZVrBbO6Cre6kTqTnQwTFmE,11251
-vgi/_test_fixtures/http_server.py,sha256=M0drWRwy-apDmQcXfTTAnkAoLRpL9gG5O8l0UwhVe1Q,20487
-vgi/_test_fixtures/identity_fixture.py,sha256=9JvCzLEm6MNU_V9IJ_HREAbaR_wKy2oFaqfRj3n_QQ8,2928
+vgi/_test_fixtures/http_server.py,sha256=hS6yKEE6I0UzwfIk_q7ORKee4jn4vD2xSCYItj8VkWE,20552
+vgi/_test_fixtures/identity_fixture.py,sha256=wNTON3wpOGwH7HS9oCPb4Iav7GMYW0NlhtlZF1TL7aY,3318
 vgi/_test_fixtures/nest_tensor.py,sha256=UjjW9UwipYG3ehQpZOm4hdzsafMyvVc0ZKJCrqiZTPU,24471
 vgi/_test_fixtures/orchard_catalog.py,sha256=8Uv-mKTIgl-OYU9JLgG23owlHGmgniyF2chPoKXGtuI,1643
 vgi/_test_fixtures/secret_cache.py,sha256=su4a90I-YHTfsmVPoJGyycTkEzT7GItreYZEfbXMp2o,9552
@@ -156,8 +156,8 @@ vgi/transactor/_duckdb_compat.py,sha256=sXVZ9JLKAQyGR1BjWczSwdQEavtr-TcZPoVZZnTr
 vgi/transactor/client.py,sha256=7DTeMksogsw6ANjQjGOPpKYrV76rg4_kGjktMJf54jg,4486
 vgi/transactor/protocol.py,sha256=v59IvrKnuvwOXvn_HEcBAbCzDVcx0akgKN0R1mChXg0,5034
 vgi/transactor/server.py,sha256=nzsZQxJZdgappdYX8okrFIrjFtUbdM_Hhskl1fZ2nDY,32553
-vgi_python-0.41.0.dist-info/METADATA,sha256=cYzmCmk6poHPPaMQ9OiIidOEntlJdzlD_Nr-RLbjoP4,25953
-vgi_python-0.41.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-vgi_python-0.41.0.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.41.0.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.41.0.dist-info/RECORD,,
+vgi_python-0.42.0.dist-info/METADATA,sha256=1c3-T4txCgcbPeUyxS-fOuMogZtSRPvbjNDOeau4pSg,25953
+vgi_python-0.42.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vgi_python-0.42.0.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.42.0.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.42.0.dist-info/RECORD,,