vgi-python 0.40.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/catalog_contents.py

@@ -42,7 +42,9 @@ at least once (tables, a view, scalar / aggregate / table functions, scalar and
 table macros), split over two schemas (``main`` and ``extra``), so RPC
 accounting in ``vgi/test/sql/integration/catalog/catalog_contents*.test`` is
 deterministic. Served by ``vgi-fixture-worker`` and ``vgi-fixture-http``
-(MetaWorker), so the same tests run over every transport. Their functions
+(MetaWorker), so the same tests run over every transport. Every other SDK's
+fixture worker serves these six catalogs too, and the same ``.test`` files run
+against each of them, so the semantics here are the cross-SDK contract. Their functions
 re-use the example catalog's classes (``main.double`` ...), so every worker
 here sets ``route_unattached_calls = False``: they are reachable only through
 their own attach, and an unattached ``main.double`` still routes to the

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/client/__init__.py

@@ -45,7 +45,7 @@ from vgi.client.aggregate import (
     AggregateSession,
     AggregateStreamingSession,
 )
-from vgi.client.catalog_mixin import CatalogClientMixin, CatalogContents
+from vgi.client.catalog_mixin import CatalogClientMixin, CatalogContents, CatalogSnapshot
 from vgi.client.client import Client, ClientError, ResumableTableScan, ResumeUnsupported
 
 if TYPE_CHECKING:
@@ -57,6 +57,7 @@ __all__ = [
     "AggregateStreamingSession",
     "CatalogClientMixin",
     "CatalogContents",
+    "CatalogSnapshot",
     "Client",
     "ClientError",
     "OutputWriter",

vgi/client/catalog_mixin.py

@@ -42,7 +42,7 @@ import shlex
 import sys
 from collections.abc import Iterator, Sequence
 from contextlib import contextmanager
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Any, Literal, overload
 
 import pyarrow as pa
@@ -129,6 +129,55 @@ class CatalogContents:
     schemas: list[SchemaContentsInfo]
 
 
+@dataclass(frozen=True)
+class CatalogSnapshot:
+    """A whole catalog — every schema and everything in it — from [`CatalogClientMixin.load_catalog`][].
+
+    Hold on to it and pass it back as ``previous`` to revalidate: when it came
+    from ``catalog_contents`` with an etag, the next load sends
+    ``if_none_match`` and a ``not_modified`` answer returns this same content
+    without re-downloading it.
+
+    Attributes:
+        schemas: One [`SchemaContentsInfo`][] per schema, parents first.
+        catalog_version: The version the snapshot was taken at, or ``None``
+            when it was assembled from the per-schema RPCs (which carry none).
+        etag: The ``catalog_contents`` validator, or ``None`` when the worker
+            does not revalidate or the snapshot did not come from
+            ``catalog_contents``.
+        source: ``"catalog_contents"`` (one RPC) or ``"per_schema"``
+            (``catalog_schemas`` plus the per-schema ``catalog_schema_contents_*``
+            RPCs — the worker did not advertise ``catalog_contents``, the load
+            ran inside a transaction, or ``catalog_contents`` failed).
+        not_modified: ``True`` when this is ``previous`` confirmed current by a
+            ``not_modified`` answer.
+        fallback_reason: Why ``catalog_contents`` was advertised but not used
+            (its error message, or a protocol violation), else ``None``.
+    """
+
+    schemas: list[SchemaContentsInfo]
+    catalog_version: int | None
+    etag: str | None
+    source: Literal["catalog_contents", "per_schema"]
+    not_modified: bool = False
+    fallback_reason: str | None = None
+
+
+# ``SchemaInfo.estimated_object_count`` key for each per-schema kind; a count of
+# exactly 0 is a hard "none of this kind" guarantee, so the RPC is skipped (the
+# same rule the DuckDB extension and ``CatalogInterface.catalog_contents`` apply).
+_PER_SCHEMA_KINDS: tuple[tuple[str, SchemaObjectType, str], ...] = (
+    ("tables", SchemaObjectType.TABLE, "table"),
+    ("views", SchemaObjectType.VIEW, "view"),
+    ("scalar_functions", SchemaObjectType.SCALAR_FUNCTION, "scalar_function"),
+    ("aggregate_functions", SchemaObjectType.AGGREGATE_FUNCTION, "aggregate_function"),
+    ("table_functions", SchemaObjectType.TABLE_FUNCTION, "table_function"),
+    ("scalar_macros", SchemaObjectType.SCALAR_MACRO, "macro"),
+    ("table_macros", SchemaObjectType.TABLE_MACRO, "macro"),
+    ("indexes", SchemaObjectType.INDEX, "index"),
+)
+
+
 class CatalogClientError(Exception):
     """Error raised by catalog operations."""
 
@@ -492,13 +541,123 @@ class CatalogClientMixin:
             one [`SchemaContentsInfo`][] per schema, parents first.
 
         """
+        # Decode inside the connection block so a malformed item surfaces as
+        # CatalogClientError (which load_catalog falls back on), not a bare
+        # decode error.
         with self._catalog_connect() as proxy:
             response = proxy.catalog_contents(attach_opaque_data=attach_opaque_data, if_none_match=if_none_match)
-        return CatalogContents(
-            catalog_version=response.catalog_version,
-            etag=response.etag,
-            not_modified=response.not_modified,
-            schemas=[_decode_schema_contents(entry) for entry in response.schemas],
+            return CatalogContents(
+                catalog_version=response.catalog_version,
+                etag=response.etag,
+                not_modified=response.not_modified,
+                schemas=[_decode_schema_contents(entry) for entry in response.schemas],
+            )
+
+    def load_catalog(
+        self,
+        *,
+        attach: CatalogAttachResult,
+        previous: CatalogSnapshot | None = None,
+        transaction_opaque_data: TransactionOpaqueData | None = None,
+    ) -> CatalogSnapshot:
+        """Load every schema and all of its contents, in as few RPCs as the worker allows.
+
+        This is the client's whole-catalog enumeration. When the attach result
+        advertises ``supports_catalog_contents`` it is one ``catalog_contents``
+        call; otherwise — or inside a transaction, or when that call fails — it
+        is ``catalog_schemas`` plus the per-schema ``catalog_schema_contents_*``
+        RPCs (skipping a kind whose ``estimated_object_count`` is exactly 0).
+        ``catalog_contents`` is never sent to a worker that did not advertise it.
+
+        Revalidation: pass the snapshot from a previous load as ``previous``.
+        If it came from ``catalog_contents`` with an etag, the call sends
+        ``if_none_match``; a ``not_modified`` answer returns ``previous``'s
+        content (with ``not_modified=True`` and the current version), and a full
+        answer replaces it. A snapshot older than ``previous`` (a lagging
+        replica) is retried once, then the per-schema RPCs are used.
+
+        Args:
+            attach: The result of [`catalog_attach`][vgi.client.CatalogClientMixin.catalog_attach]
+                for this catalog.
+            previous: A snapshot already held, to revalidate instead of reload.
+            transaction_opaque_data: Load inside this transaction. ``catalog_contents``
+                returns only the committed catalog, so a transactional load always
+                uses the (transaction-aware) per-schema RPCs.
+
+        Returns:
+            A [`CatalogSnapshot`][]. ``source`` says which path served it and
+            ``fallback_reason`` why an advertised ``catalog_contents`` was not used.
+        """
+        attach_opaque_data = attach.attach_opaque_data
+        if not attach.supports_catalog_contents or transaction_opaque_data is not None:
+            return self._load_catalog_per_schema(attach_opaque_data, transaction_opaque_data, None)
+
+        if_none_match = previous.etag if previous is not None and previous.source == "catalog_contents" else None
+        known_version = previous.catalog_version if previous is not None else None
+        reason: str
+        for _attempt in range(2):
+            try:
+                contents = self.contents(attach_opaque_data=attach_opaque_data, if_none_match=if_none_match)
+            except CatalogClientError as e:
+                reason = str(e)
+                break
+            if contents.not_modified:
+                if previous is None or if_none_match is None or contents.schemas:
+                    reason = "catalog_contents answered not_modified to a request it could not match"
+                    break
+                return replace(
+                    previous,
+                    catalog_version=contents.catalog_version,
+                    etag=contents.etag if contents.etag is not None else previous.etag,
+                    not_modified=True,
+                )
+            # Versions are monotonic within a session; 0 means "unknown".
+            if known_version and contents.catalog_version and contents.catalog_version < known_version:
+                reason = (
+                    f"catalog_contents returned version {contents.catalog_version}, "
+                    f"older than the known version {known_version}"
+                )
+                continue
+            return CatalogSnapshot(
+                schemas=contents.schemas,
+                catalog_version=contents.catalog_version,
+                etag=contents.etag,
+                source="catalog_contents",
+            )
+        return self._load_catalog_per_schema(attach_opaque_data, None, reason)
+
+    def _load_catalog_per_schema(
+        self,
+        attach_opaque_data: AttachOpaqueData,
+        transaction_opaque_data: TransactionOpaqueData | None,
+        fallback_reason: str | None,
+    ) -> CatalogSnapshot:
+        """Assemble a snapshot from ``catalog_schemas`` and the per-schema RPCs."""
+        result: list[SchemaContentsInfo] = []
+        for schema in self.schemas(
+            attach_opaque_data=attach_opaque_data, transaction_opaque_data=transaction_opaque_data
+        ):
+            counts = schema.estimated_object_count or {}
+            kinds: dict[str, list[Any]] = {}
+            for attr, object_type, count_key in _PER_SCHEMA_KINDS:
+                if counts.get(count_key, 1) == 0:
+                    kinds[attr] = []
+                    continue
+                kinds[attr] = list(
+                    self.schema_contents(
+                        attach_opaque_data=attach_opaque_data,
+                        transaction_opaque_data=transaction_opaque_data,
+                        path=list(schema.path),
+                        type=object_type,
+                    )
+                )
+            result.append(SchemaContentsInfo(schema=schema, **kinds))
+        return CatalogSnapshot(
+            schemas=result,
+            catalog_version=None,
+            etag=None,
+            source="per_schema",
+            fallback_reason=fallback_reason,
         )
 
     def schema_get(

vgi/client/cli_catalog.py

@@ -11,6 +11,7 @@ catalog
 ├── create <name>           # Create a new catalog
 ├── drop <name>             # Drop a catalog
 ├── version                 # Get catalog version (--attach-opaque-data or --catalog)
+├── contents                # Every schema and its contents (catalog_contents when advertised)
 ├── schema                  # Schema operations
 │   ├── list/get/create/drop/contents
 ├── table                   # Table operations
@@ -163,6 +164,52 @@ def catalog_version(
     output_json({"version": version, "attach_opaque_data": bytes_to_hex(resolved_attach_opaque_data)})
 
 
+@catalog.command("contents")
+@click.option("--catalog", "catalog_name", required=True, help="Catalog name to attach")
+@click.option("--attach-options", default="{}", help="Attach options as JSON")
+@click.option("--worker", "-w", required=True, help="VGI worker command")
+def catalog_contents(catalog_name: str, attach_options: str, worker: str) -> None:
+    """List every schema and the names of everything in it.
+
+    Uses one ``catalog_contents`` call when the catalog advertises it, else
+    ``catalog_schemas`` plus the per-schema RPCs (see ``Client.load_catalog``).
+    """
+    client = Client(worker)
+    attach = client.catalog_attach(
+        name=catalog_name,
+        options=parse_json_option(attach_options, "--attach-options"),
+        data_version_spec=None,
+        implementation_version=None,
+    )
+    snapshot = client.load_catalog(attach=attach)
+    kinds = (
+        "tables",
+        "views",
+        "scalar_functions",
+        "aggregate_functions",
+        "table_functions",
+        "scalar_macros",
+        "table_macros",
+        "indexes",
+    )
+    output_json(
+        {
+            "source": snapshot.source,
+            "catalog_version": snapshot.catalog_version,
+            "etag": snapshot.etag,
+            "fallback_reason": snapshot.fallback_reason,
+            "schemas": [
+                {
+                    "path": list(entry.schema.path),
+                    "comment": entry.schema.comment,
+                    **{kind: [item.name for item in getattr(entry, kind)] for kind in kinds},
+                }
+                for entry in snapshot.schemas
+            ],
+        }
+    )
+
+
 # Add nested subcommand groups
 catalog.add_command(schema)
 catalog.add_command(table)

vgi/client/cli_utils.py

@@ -389,6 +389,7 @@ def catalog_attach_result_to_dict(result: CatalogAttachResult) -> dict[str, Any]
         "catalog_version": result.catalog_version,
         "attach_opaque_data_required": result.attach_opaque_data_required,
         "default_schema": result.default_schema,
+        "supports_catalog_contents": result.supports_catalog_contents,
         "settings": [bytes_to_hex(s) for s in result.settings],
         "resolved_data_version": result.resolved_data_version,
         "resolved_implementation_version": result.resolved_implementation_version,

vgi/client/client.py

@@ -54,6 +54,7 @@ Key methods
     client.catalog_attach(...)    — open a catalog
     client.schemas(...)           — list schemas
     client.schema_contents(...)   — list tables/views/functions/macros
+    client.load_catalog(...)      — whole catalog (catalog_contents when advertised)
     client.scalar_function(...)   — invoke a scalar
     client.table_function(...)    — invoke a table function
     client.table_function_plan(...) — plan a table function into named, redeemable splits

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.40.0.dist-info → vgi_python-0.42.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.40.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.40.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
@@ -45,13 +45,13 @@ vgi/_test_fixtures/bad_enum.py,sha256=b8l-afmXgGR6iqgIUiVeqHu0C0F8Of8ahEmdQGtqd1
 vgi/_test_fixtures/bad_protocol.py,sha256=fPU7rpXEgBxRtPHfuCa0O2AHNRRbZDllLfydHsAKPEg,2992
 vgi/_test_fixtures/cancellable.py,sha256=hetTRLyT4kkazPNcxAdfzj0pYzEmegMksamJbR0w3Ho,12151
 vgi/_test_fixtures/catalog.py,sha256=zjBKBgg4TKoDQ9SYIFj7sx6bOL3_aXHMJHSzTgk1fdA,28526
-vgi/_test_fixtures/catalog_contents.py,sha256=Hvt98vLMhdWwk9FvdtPx5GoZJ1ZLgiCFBA2NLEJohVY,11765
+vgi/_test_fixtures/catalog_contents.py,sha256=C9vxHil2kmsqoELiTq2jZINBOwONJ2KIIYrreNMEN6c,11934
 vgi/_test_fixtures/companion.py,sha256=Ya_rg2J4tXOYC7zBFOjTTh-4AYuRhJN5BT4tVZULQ-Q,6037
 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
@@ -133,17 +133,17 @@ vgi/catalog/duckdb_statistics.py,sha256=Bzw4UGO-zdKrontaCcRV2palO8G3XLCWh-AhZozv
 vgi/catalog/secret_type.py,sha256=1DoEMyQun9K5z53817rUuhG1YpHSEAsazEmubkRLVL0,3745
 vgi/catalog/setting.py,sha256=06QfgaAR-0BKflIJ0du6PGqA5BPMdrkwr6u7f4nddII,1846
 vgi/catalog/storage.py,sha256=DhngzywbhQUfLF7NjFyiPp4Sw2ovOhcUXAuW3rkBQD8,11935
-vgi/client/__init__.py,sha256=SXS_95QN2c68ssxEWwSvS7yfyq_2ORtDpf5YqSEwC0w,2507
+vgi/client/__init__.py,sha256=QOZGVkJWOfB8r4jjiwfU2q8Q97eWkLTnT6BK1jPZ2RE,2547
 vgi/client/aggregate.py,sha256=EAaI-4d1mnNjGORZvLf3wfVuu8RXBTFGVbMek0DeGDg,38482
-vgi/client/catalog_mixin.py,sha256=ft6S0vfhvG77qvXixF-7g5jjfDE9ClwL0TM2h0mvv_w,61691
+vgi/client/catalog_mixin.py,sha256=CMUl4AUDCFDerRLc6mieZau1JCx9CIAbG_hIRHsZRJs,69620
 vgi/client/cli.py,sha256=nahuRCjday0z74Gk9zxOxIOJX9n6fHrP7-CGwJoyTzU,22754
-vgi/client/cli_catalog.py,sha256=twjlhHGl7n2mNN4jc7DnDRQr-Zj9KLAF2eATIQnITHQ,5577
+vgi/client/cli_catalog.py,sha256=RVhSJLFKSBfVwLfEb_GLT8vnuliOwU6FzlsVUF7Rpsw,7308
 vgi/client/cli_schema.py,sha256=9G2vZiaAyqINItcDCoARdM04qNlDyJ3IXw3SuA6jgU8,7818
 vgi/client/cli_table.py,sha256=H1xrKZF5yYmSe55YSrLWXGIXPmuGuzQcncEBvqL43zs,26498
 vgi/client/cli_transaction.py,sha256=TDW0ZrBy8XM_eYSkYk5ewEsnozfzDJOlopd66Fm7OOE,3142
-vgi/client/cli_utils.py,sha256=_JoNiVu12NV4Pg2b1wtWFt0L0uIWJ9p9mBIfIu-QIuM,17387
+vgi/client/cli_utils.py,sha256=ykh7XK-yzcW6WGED2_DhPLIVPSyVG3KUdllV5ztBicw,17458
 vgi/client/cli_view.py,sha256=0qhxoS91-zFMjq8V_Fb0PNW-YDxERu8-zPpxSFEE-G8,8490
-vgi/client/client.py,sha256=cvBQHzM2Z2lamC-fkBAvZD4HuRxB03aUkEKFVo_E9GU,167312
+vgi/client/client.py,sha256=GSkcVXQzI0VCmeUf7WY4kR0ZqFtYmeb6EkenarBvX5c,167399
 vgi/client/errors.py,sha256=cSN65cyQMk3crwZCz1IdPErK3mtlEkTNpu-nuQUDOQE,1633
 vgi/http/__init__.py,sha256=hlOwOVcoZqmEKVGk7ganOdr5ryRSpEhLBF9sRD7BkYc,608
 vgi/http/demo_storage.py,sha256=830s-H61thozC3eEuqdnwCpYFfvoJRq9vjyuXa5OURo,8769
@@ -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.40.0.dist-info/METADATA,sha256=lw7UWSpVsGOISgdZ3GYe4Y0cQoL59BlTUsqiXlstBng,25953
-vgi_python-0.40.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-vgi_python-0.40.0.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.40.0.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.40.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,,