vgi-python 0.41.0__tar.gz → 0.42.0__tar.gz

{vgi_python-0.41.0 → vgi_python-0.42.0}/CLAUDE.md

@@ -297,6 +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_RPC_GRANT_KEYS` | Comma-separated base64 32-byte sealed-grant keys (first mints, all verify); enables grants as HTTP bearers. Also `VGI_RPC_GRANT_AUDIENCE`, `VGI_RPC_GRANT_MAX_TTL_SECONDS` |
 | `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_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 |
@@ -484,6 +485,24 @@ sidecar outage raised as one is read as "not my credential, try the next" and
 ends up a 401 from the end of the chain, restarting every session in the fleet
 over a thirty-second blip.
 
+### Grants and `resolve_token` as HTTP Bearers
+
+With `VGI_RPC_GRANT_KEYS` (or `vgi-serve --grant-key`) set, the HTTP worker
+hosts Identity even without hooks. It mints sealed `vgig1.` grants through
+`issue_grant`, unless the worker overrides `mint_grant`, and accepts them back
+as `Authorization: Bearer` credentials, authenticated as the grant's owner. A
+worker that overrides `resolve_token` also has it consulted for bearers. The
+order is the deployment's authenticator, then grants, then `resolve_token`. A
+bad `vgig1.` token is a 401 and never reaches `resolve_token`. vgi-rpc composes
+this in `make_wsgi_app`. vgi-python resolves the keys in
+`vgi.rpc_server.resolve_grant_keys` and passes them explicitly to `RpcServer`
+(`None` off HTTP, never vgi-rpc's `"env"` default), so grants stay HTTP-only. It
+also puts the bearers *inside* VGI's proxy-proof gate
+(`serve._compose_identity_bearer`), because vgi-rpc refuses to OR them beside
+one. Allowlist rules are unchanged. See `docs/authentication.md` and
+`tests/test_grant_auth.py`, which also runs the shared
+`grant_token_vectors.json` through `create_app`.
+
 ### Hosting Additional Protocols (`hosted_protocols`)
 
 Every transport (stdio, unix/named pipe, TCP, Iroh, HTTP) builds its `RpcServer`

{vgi_python-0.41.0 → vgi_python-0.42.0}/PKG-INFO

@@ -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 → vgi_python-0.42.0}/docs/api/index.md

@@ -32,7 +32,7 @@ added incrementally.
 | [Auth & Secrets](auth.md) | `AuthContext`, `CallContext`, bearer/JWT authenticators, secret protocol | HTTP: `[http]`; JWT: `[oauth]` |
 | [Observability](observability.md) | OpenTelemetry tracing, worker logging configuration | `[otel]` for tracing |
 | [HTTP](http.md) | Worker page, blob storage, request-size middleware | `pip install vgi-python[http]` |
-| [Transactor](transactor.md) | `TransactorClient`, `TransactorProtocol` | `pip install vgi-python[transactor]` |
+| [Transactor](transactor.md) | `TransactorClient`, `TransactorProtocol` | `[transactor]` extra and a [compatible engine build](transactor.md#runtime-requirements) |
 | [Exceptions](exceptions.md) | VGI exception types | — |
 
 ## Import Convention

vgi_python-0.42.0/docs/api/transactor.md

@@ -0,0 +1,32 @@
+# Transactor
+
+!!! note "Advanced — reference only"
+    The transactor is an advanced feature without a dedicated how-to guide yet. This page is the
+    API reference; start from the [tutorial](../tutorial/index.md) and
+    [function patterns](../how-to/function-patterns.md) if you're new to VGI.
+
+The transactor is a long-lived subprocess that gives worker functions transactional access to a
+database, mediated by `TransactorClient` over the `TransactorProtocol`.
+
+## Runtime requirements
+
+The bundled transactor requires both:
+
+- `pip install 'vgi-python[transactor]'` for its Python dependencies.
+- A VGI fork build of `duckdb-python` providing `DuckDBPyConnection.subcursor()`,
+  which lets reads share an open write transaction. This extension has not yet
+  been merged into Haybarn or upstream DuckDB; installing the extra alone is
+  insufficient.
+
+Engine resolution prefers `haybarn` when installed, then falls back to `duckdb`.
+Use an environment where the selected engine provides `subcursor()`; installing
+a compatible `duckdb` build alongside an incompatible `haybarn` installation
+does not override that preference.
+
+These requirements apply to the bundled transactor. Workers can implement
+[table writes](../catalog-interface.md#table-writes-and-indexes) against their own
+backing data sources without using it.
+
+## API
+
+::: vgi.transactor

{vgi_python-0.41.0 → vgi_python-0.42.0}/docs/authentication.md

@@ -24,7 +24,7 @@ the principal in the `AuthContext` available to functions.
 | Variable | Description |
 |----------|-------------|
 | `VGI_BEARER_TOKENS` | Comma-separated `token=principal` pairs for static bearer auth |
-| `VGI_JWT_ISSUER` | JWT issuer URL (requires `vgi[oauth]` extra) |
+| `VGI_JWT_ISSUER` | JWT issuer URL (requires `vgi-python[oauth]` extra) |
 | `VGI_JWT_AUDIENCE` | JWT audience string, comma-separated for multiple audiences (required when `VGI_JWT_ISSUER` is set) |
 | `VGI_JWT_JWKS_URI` | JWKS endpoint URL (auto-discovered from issuer if omitted) |
 | `VGI_OAUTH_RESOURCE` | OAuth resource URL for RFC 9728 metadata |
@@ -39,6 +39,48 @@ When both `VGI_BEARER_TOKENS` and `VGI_JWT_ISSUER` are set, they are
 chained — JWT validation is attempted first, falling back to bearer token
 lookup.
 
+## Grants and resolved tokens as bearer credentials
+
+`vgi_rpc.Identity.v1`'s `issue_grant` mints a standing credential that
+unattended automation later presents as an ordinary bearer. Over HTTP the
+worker accepts two kinds of identity credential after the deployment's own
+authenticator:
+
+1. **Sealed grants** (opt-in). Set `VGI_RPC_GRANT_KEYS` (or
+   `vgi-serve --http --grant-key KEY`, repeatable). `issue_grant` then mints a
+   `vgig1.` grant sealed with the first key, unless the worker overrides
+   `mint_grant`. Every key verifies, so to rotate you add the new key first and
+   drop the old one once its grants have expired. A request carrying
+   `Authorization: Bearer vgig1.…` is authenticated as the grant's owner, with
+   `domain="grant"` and claims `grant_id`, `scopes` and `purpose`. The claims
+   carry no `auth_time`, so a grant cannot mint another grant.
+2. **`resolve_token`**. A worker that overrides
+   [`Worker.resolve_token`][vgi.worker.Worker.resolve_token] has it consulted
+   for any other bearer, with `domain="token"`. `None` means the credential is
+   unknown, which is a 401 unless something else accepts it.
+   `AuthUnavailableError` is a 503 with the hook's `Retry-After`.
+
+The order is the deployment's authenticator (JWT, static bearer), then sealed
+grants, then `resolve_token`. A `vgig1.` token that does not verify is a 401
+that stops the chain: it never reaches `resolve_token`. A JWS-shaped token or
+one over 4096 bytes never reaches the hook either. Your own `authenticate`
+callback must raise `ValueError` for a credential it does not recognise, so the
+chain moves on. One that answers anonymous for every request ends the chain
+before grants are checked. With no authenticator configured, a request with no
+`Authorization` header stays anonymous as before.
+
+| Variable | Description |
+|----------|-------------|
+| `VGI_RPC_GRANT_KEYS` | Comma-separated standard-base64 keys, 32 bytes each. The first mints and all verify. Unset means grants are off. A malformed key stops startup |
+| `VGI_RPC_GRANT_AUDIENCE` | Bound into every grant, so two deployments that share a key still reject each other's grants |
+| `VGI_RPC_GRANT_MAX_TTL_SECONDS` | Ceiling on a grant's lifetime (default 7 days) |
+
+The startup rules are unchanged. Overriding `resolve_token` still requires
+`VGI_INTROSPECT_PRINCIPALS`. Grant keys alone need no allowlist, because
+minting answers only for the caller. Grants and `resolve_token` bearers are
+HTTP-only, like the rest of Identity. When `VGI_PROXY_PROOF_MODE` is on, both
+are accepted only *inside* the proxy-proof gate, never as an alternative to it.
+
 ## Programmatic API
 
 ```python test="skip"

{vgi_python-0.41.0 → vgi_python-0.42.0}/docs/catalog-interface.md

@@ -944,7 +944,7 @@ if __name__ == "__main__":
 
 ---
 
-## API Limitations
+## Catalog capabilities and limitations { #api-limitations }
 
 The current CatalogInterface has the following limitations:
 
@@ -952,8 +952,33 @@ The current CatalogInterface has the following limitations:
 - **Tags**: Cannot be updated after object creation
 - **Schema metadata**: Comments and tags cannot be updated on schemas
 - **Constraints**: Only NOT NULL can be added/dropped (no ALTER for UNIQUE/CHECK)
-- **Indexes**: Not supported
-- **INSERT/UPDATE/DELETE**: Not yet implemented (metadata only)
+
+### Table writes and indexes
+
+`INSERT`, `UPDATE`, and `DELETE` are supported when the catalog supplies a write
+function for the operation. For declarative catalogs, configure the
+[`Table`][vgi.catalog.descriptors.Table] descriptor:
+
+| Operation | Descriptor field | Requirement |
+|-----------|------------------|-------------|
+| `INSERT` | `insert_function` | A `TableInOutGenerator` that accepts rows to insert |
+| `UPDATE` | `update_function` | A write function and a scan `function` that provides row IDs |
+| `DELETE` | `delete_function` | A write function and a scan `function` that provides row IDs |
+
+Each field defaults to `None`, which leaves that operation unsupported. Custom
+catalogs implement `table_insert_function_get()`, `table_update_function_get()`,
+or `table_delete_function_get()` to return the corresponding `ScanFunctionResult`.
+The worker's write functions implement the changes to the backing data source;
+declaring a table alone does not make it writable.
+
+`ReadOnlyCatalogInterface` rejects catalog DDL, but can expose these write functions
+on declarative tables. Table writes do not require the bundled
+[transactor](api/transactor.md); that is an optional database-access service with
+additional engine requirements.
+
+Index metadata can be declared with [`Index`][vgi.catalog.descriptors.Index]. Custom
+catalogs can implement `index_get()`, `index_create()`, and `index_drop()`; support
+depends on the catalog implementation and backing data source.
 
 ---
 

{vgi_python-0.41.0 → vgi_python-0.42.0}/docs/cli.md

@@ -545,7 +545,7 @@ vgi-fixture-worker --log-format json
 | `VGI_QUIET=1` | Suppress the interactive-terminal startup warning (same as `--quiet`) |
 | `VGI_FILTER_DEBUG=1` | Enable filter pushdown debug logging |
 | `VGI_BEARER_TOKENS` | Comma-separated `token=principal` pairs for static bearer auth (HTTP only) |
-| `VGI_JWT_ISSUER` | JWT issuer URL for JWT/JWKS auth (requires `vgi[oauth]` extra) |
+| `VGI_JWT_ISSUER` | JWT issuer URL for JWT/JWKS auth (requires `vgi-python[oauth]` extra) |
 | `VGI_JWT_AUDIENCE` | JWT audience string, comma-separated for multiple audiences (required when `VGI_JWT_ISSUER` is set) |
 | `VGI_JWT_JWKS_URI` | JWKS endpoint URL (auto-discovered if omitted) |
 | `VGI_OAUTH_RESOURCE` | OAuth resource URL for RFC 9728 metadata |

{vgi_python-0.41.0 → vgi_python-0.42.0}/docs/how-to/function-patterns.md

@@ -1,5 +1,5 @@
 ---
-description: "How to write each of the four VGI function patterns: scalar, table, table-in-out, and aggregate — with a complete runnable worker for each."
+description: "How to write each of the five VGI function patterns: scalar, table, table-in-out, aggregate, and buffering — with a complete runnable worker for each."
 ---
 
 # Function patterns
@@ -178,11 +178,14 @@ ATTACH 'aggregates' (TYPE vgi, LOCATION 'uv run sum_worker.py');
 SELECT category, aggregates.vgi_sum(value) FROM t GROUP BY category;
 ```
 
-??? info "State must be an `ArrowSerializableDataclass`"
-    Table generators and aggregates keep state between calls. Because that state is serialized
-    across parallel workers (aggregates) and HTTP round-trips, the framework requires it to extend
-    `ArrowSerializableDataclass`. Annotate fields with `ArrowType(...)` so the wire type is
-    explicit.
+??? info "State must be serializable"
+    Table generators and aggregates keep state between calls. A state type must provide
+    `serialize_to_bytes()` and `deserialize_from_bytes()` so the framework can carry it across
+    HTTP round-trips or persist it between aggregate calls. `ArrowSerializableDataclass`
+    implements these methods for you and is the usual starting point. Custom state types can
+    implement the same [`StreamStateCodec`][vgi.function.StreamStateCodec] contract without
+    inheriting from `ArrowSerializableDataclass`. See
+    [State Class](../aggregate-functions.md#state-class) for both approaches.
 
 ## Buffering
 

{vgi_python-0.41.0 → vgi_python-0.42.0}/docs/how-to/state-storage.md

@@ -22,9 +22,11 @@ function that coordinates partial results across workers.
 
 ## Two kinds of "state" — don't confuse them
 
-- **Generator cursor state** — the small `ArrowSerializableDataclass` a table generator keeps
-  *within one scan* (see [streaming with state](function-patterns.md#streaming-with-state)). It
-  lives in the worker for the duration of the call.
+- **Generator cursor state** — the small serializable object a table generator keeps
+  *within one scan* (see [streaming with state](function-patterns.md#streaming-with-state)).
+  Over HTTP, the framework serializes it between requests. `ArrowSerializableDataclass`
+  supplies the serialization methods; custom types can implement
+  [`StreamStateCodec`][vgi.function.StreamStateCodec] instead.
 - **Shared storage** (this page) — state that must outlive a single call or be shared across
   **separate worker processes**, e.g. combining partial aggregate results. This is backed by a
   pluggable store.

{vgi_python-0.41.0 → vgi_python-0.42.0}/docs/shared-storage.md

@@ -10,7 +10,7 @@ variable.
 | Backend | Value | Use Case | Dependencies |
 |---------|-------|----------|-------------|
 | SQLite | `sqlite` (default) | Local / subprocess transport | None (stdlib) |
-| Azure SQL | `azure-sql` | Azure cloud deployments | `vgi[azure]` |
+| Azure SQL | `azure-sql` | Azure cloud deployments | `vgi-python[azure]` |
 | Cloudflare DO | `cloudflare-do` | Edge / multi-cloud deployments | None (stdlib) |
 
 ## SQLite (Default)
@@ -36,7 +36,7 @@ workers run on separate hosts.
 1. Install the Azure extra:
 
 ```bash
-pip install vgi[azure]
+pip install 'vgi-python[azure]'
 ```
 
 2. Create an Azure SQL Database (Serverless recommended for cost):

{vgi_python-0.41.0 → vgi_python-0.42.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.41.0"
+version = "0.42.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.48.0",
+    "vgi-rpc>=0.49.0",
     "httpx2>=2.12.0",
 ]
 

vgi_python-0.42.0/tests/test_grant_auth.py

@@ -0,0 +1,290 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Identity credentials accepted as HTTP bearers: sealed grants and ``resolve_token``.
+
+vgi-rpc's ``Identity.v1`` mints grants "presented later by unattended
+automation as an ordinary bearer". These tests close that loop through
+vgi-python's own HTTP surface (``create_app``), not vgi-rpc in isolation:
+
+- with ``VGI_RPC_GRANT_KEYS`` set, ``issue_grant`` mints a sealed grant and a
+  ``vgi.v2`` call presenting it is authenticated as the grant's owner;
+- a worker that overrides ``resolve_token`` has it consulted for bearers;
+- the shared vectors (``vgi_rpc/conformance/grant_token_vectors.json``) are
+  accepted and rejected through the full chain;
+- VGI's proxy-proof gate still guards every request when grants are on.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+import types
+from collections.abc import Iterator
+from importlib.resources import files
+from typing import Any
+
+import pyarrow as pa
+import pytest
+from vgi_rpc.grants import GRANT_KEYS_ENV, GrantKeys, mint_grant_token
+from vgi_rpc.http import http_connect
+from vgi_rpc.http._testing import _SyncTestClient
+from vgi_rpc.rpc import AuthContext
+from vgi_rpc.rpc._token_identity import Identity
+
+from tests.test_serve import _PeerAuthWorker
+from vgi.arguments import Arguments
+from vgi.auth import TokenIdentity
+from vgi.client import Client, ClientError
+from vgi.rpc_server import build_rpc_server, resolve_grant_keys
+from vgi.serve import create_app
+
+_KEY_B64 = base64.b64encode(bytes(range(32))).decode()
+_OTHER_KEY_B64 = base64.b64encode(bytes(range(32, 64))).decode()
+_SIGNING_KEY = b"grant-auth-test-signing-key-0001"
+_IDENTITY = "vgi_rpc.Identity.v1"
+_GRANT_ENV = (GRANT_KEYS_ENV, "VGI_RPC_GRANT_AUDIENCE", "VGI_RPC_GRANT_MAX_TTL_SECONDS")
+
+_VECTORS = json.loads(files("vgi_rpc.conformance").joinpath("grant_token_vectors.json").read_text(encoding="utf-8"))
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:
+    """No ambient grant, auth or allowlist configuration leaks into a test."""
+    for key in (*_GRANT_ENV, "VGI_INTROSPECT_PRINCIPALS", "VGI_BEARER_TOKENS", "VGI_JWT_ISSUER"):
+        monkeypatch.delenv(key, raising=False)
+    for key in ("VGI_PROXY_PROOF_MODE", "VGI_PROXY_PROOF_ORIGIN_ID", "VGI_PROXY_PROOF_SECRETS"):
+        monkeypatch.delenv(key, raising=False)
+    yield
+
+
+def _header_authenticate(req: Any) -> AuthContext:
+    """Deployment authenticator: ``X-Test-Principal`` with a fresh ``auth_time``.
+
+    Raises ``ValueError`` for a bare bearer, as the chain contract requires, so
+    grants and ``resolve_token`` get to answer it.
+    """
+    principal = req.get_header("X-Test-Principal")
+    if principal:
+        return AuthContext(domain="test", authenticated=True, principal=principal, claims={"auth_time": time.time()})
+    if req.get_header("Authorization"):
+        raise ValueError("not a test-principal request")
+    return AuthContext.anonymous()
+
+
+def _whoami(app: Any, *, bearer: str) -> str:
+    """Call ``peer_auth_echo`` (a vgi.v2 scalar function) and return its principal."""
+    client = _SyncTestClient(app, default_headers={"Authorization": f"Bearer {bearer}"})
+    with Client.from_http("http://vgi.test", httpx_client=client) as vgi:
+        out = list(
+            vgi.scalar_function(
+                function_name="peer_auth_echo",
+                schema_path=["main"],
+                arguments=Arguments(positional=(pa.scalar("value"),)),
+                input=iter((pa.record_batch({"value": pa.array([1], type=pa.int64())}),)),
+            )
+        )
+    return str(out[0].column("result")[0].as_py())
+
+
+def _app(worker: type = _PeerAuthWorker, **kwargs: Any) -> Any:
+    return create_app(worker, describe=False, signing_key=_SIGNING_KEY, **kwargs)
+
+
+class TestGrantKeyConfiguration:
+    """Opt-in, from the environment or ``--grant-key``; malformed keys stop startup."""
+
+    def test_no_key_means_grants_off(self) -> None:
+        """No key means grants off."""
+        assert resolve_grant_keys() is None
+        assert _IDENTITY not in build_rpc_server(_PeerAuthWorker(quiet=True), transport="http").bindings
+
+    def test_env_keys_parse(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Env keys parse."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, f"{_KEY_B64},{_OTHER_KEY_B64}")
+        monkeypatch.setenv("VGI_RPC_GRANT_AUDIENCE", "aud")
+        keys = resolve_grant_keys()
+        assert keys is not None
+        assert keys.keys == (bytes(range(32)), bytes(range(32, 64)))
+        assert keys.audience == "aud"
+
+    def test_explicit_keys_win_over_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Explicit keys win over env."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, _OTHER_KEY_B64)
+        keys = resolve_grant_keys([_KEY_B64])
+        assert keys is not None
+        assert keys.keys == (bytes(range(32)),)
+
+    @pytest.mark.parametrize("bad", ["not-base64!", base64.b64encode(b"short").decode()])
+    def test_malformed_key_refuses_to_start(self, monkeypatch: pytest.MonkeyPatch, bad: str) -> None:
+        """Malformed key refuses to start."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, bad)
+        with pytest.raises(SystemExit):
+            _app()
+
+    def test_keys_alone_host_issue_grant_without_an_allowlist(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Minting is not an oracle, so the introspection allowlist rule does not apply."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, _KEY_B64)
+        server = build_rpc_server(_PeerAuthWorker(quiet=True), transport="http", grant_keys=resolve_grant_keys())
+        assert server.bindings[_IDENTITY].methods.keys() == {"issue_grant"}
+
+    def test_keys_are_http_only(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Keys are http only."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, _KEY_B64)
+        server = build_rpc_server(_PeerAuthWorker(quiet=True), transport="unix", grant_keys=resolve_grant_keys())
+        assert _IDENTITY not in server.bindings
+
+
+class TestSealedGrantEndToEnd:
+    """issue_grant with fresh auth, then a vgi.v2 call with ``Bearer <grant>``, as the owner."""
+
+    def test_minted_grant_authenticates_as_its_owner(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Minted grant authenticates as its owner."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, _KEY_B64)
+        app = _app(authenticate=_header_authenticate)
+
+        minter = _SyncTestClient(app, default_headers={"X-Test-Principal": "alice@example.com"})
+        with http_connect(Identity, client=minter) as identity:  # type: ignore[type-abstract]
+            grant = identity.issue_grant(purpose="nightly-report", scopes=["read"], ttl_seconds=600)
+        assert grant.token.startswith("vgig1.")
+
+        assert _whoami(app, bearer=grant.token) == "alice@example.com"
+
+    def test_tampered_grant_is_refused(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Tampered grant is refused."""
+        monkeypatch.setenv(GRANT_KEYS_ENV, _KEY_B64)
+        keys = GrantKeys.parse([_KEY_B64])
+        token, _ = mint_grant_token(keys, principal="alice", scopes=[], purpose="p", ttl_seconds=60)
+        tampered = token[:-2] + ("A" if token[-2] != "A" else "B") + token[-1]
+        with pytest.raises(ClientError):
+            _whoami(_app(authenticate=_header_authenticate), bearer=tampered)
+
+    def test_unknown_bearer_without_grants_configured_stays_unaccepted(self) -> None:
+        """No keys, no hook: nothing changes -- the deployment authenticator decides."""
+        app = _app(authenticate=_header_authenticate)
+        with pytest.raises(ClientError):
+            _whoami(app, bearer="vgig1.AAAA")
+
+
+class _ResolvingWorker(_PeerAuthWorker):
+    """Resolves one opaque credential; counts calls so routing is observable."""
+
+    calls: list[str] = []
+
+    @classmethod
+    def resolve_token(cls, token: str) -> TokenIdentity | None:
+        """Resolve token."""
+        cls.calls.append(token)
+        return TokenIdentity(principal="svc-reporting") if token == "opaque-api-key" else None
+
+
+class TestResolveTokenBearer:
+    """A worker's resolve_token is consulted for bearers it did not mint."""
+
+    @pytest.fixture
+    def app(self, monkeypatch: pytest.MonkeyPatch) -> Any:
+        """App."""
+        monkeypatch.setenv("VGI_INTROSPECT_PRINCIPALS", "proxy-a")
+        monkeypatch.setenv(GRANT_KEYS_ENV, _KEY_B64)
+        _ResolvingWorker.calls = []
+        return _app(_ResolvingWorker, authenticate=_header_authenticate)
+
+    def test_resolved_bearer_authenticates(self, app: Any) -> None:
+        """Resolved bearer authenticates."""
+        assert _whoami(app, bearer="opaque-api-key") == "svc-reporting"
+
+    def test_unresolved_bearer_is_refused(self, app: Any) -> None:
+        """Unresolved bearer is refused."""
+        with pytest.raises(ClientError):
+            _whoami(app, bearer="unknown-key")
+
+    def test_a_bad_grant_never_reaches_the_resolver(self, app: Any) -> None:
+        """A bad grant never reaches the resolver."""
+        with pytest.raises(ClientError):
+            _whoami(app, bearer="vgig1.AAAA")
+        assert "vgig1.AAAA" not in _ResolvingWorker.calls
+
+    def test_allowlist_rule_unchanged(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Allowlist rule unchanged."""
+        monkeypatch.delenv("VGI_INTROSPECT_PRINCIPALS", raising=False)
+        with pytest.raises(SystemExit):
+            _app(_ResolvingWorker)
+
+
+def _vector_env(monkeypatch: pytest.MonkeyPatch, verify_keys: list[str], audience: str, max_ttl: int) -> None:
+    monkeypatch.setenv(GRANT_KEYS_ENV, ",".join(verify_keys))
+    monkeypatch.setenv("VGI_RPC_GRANT_AUDIENCE", audience)
+    monkeypatch.setenv("VGI_RPC_GRANT_MAX_TTL_SECONDS", str(max_ttl))
+
+
+def _at(monkeypatch: pytest.MonkeyPatch, now: float) -> None:
+    """Pin the grant verifier's clock without touching the process clock."""
+    import vgi_rpc.grants
+
+    monkeypatch.setattr(vgi_rpc.grants, "time", types.SimpleNamespace(time=lambda: now))
+
+
+class TestSharedVectors:
+    """The shared vectors, accepted and rejected through create_app's whole chain."""
+
+    @pytest.mark.parametrize("case", _VECTORS["mint"], ids=lambda c: c["name"])
+    def test_minted_vector_authenticates(self, monkeypatch: pytest.MonkeyPatch, case: dict[str, Any]) -> None:
+        """Minted vector authenticates."""
+        verify = [case["minting_key_b64"], *_VECTORS["defaults"]["verify_keys_b64"]]
+        _vector_env(monkeypatch, list(dict.fromkeys(verify)), case["audience"], case["max_ttl_seconds"])
+        _at(monkeypatch, case["now"] + 1)
+        assert _whoami(_app(), bearer=case["token"]) == case["claims"]["principal"]
+
+    @pytest.mark.parametrize("case", _VECTORS["accept"], ids=lambda c: c["name"])
+    def test_accept_case(self, monkeypatch: pytest.MonkeyPatch, case: dict[str, Any]) -> None:
+        """Accept case."""
+        d = _VECTORS["defaults"]
+        _vector_env(
+            monkeypatch,
+            case.get("verify_keys_b64", d["verify_keys_b64"]),
+            case.get("audience", d["audience"]),
+            case.get("max_ttl_seconds", d["max_ttl_seconds"]),
+        )
+        _at(monkeypatch, case.get("now", d["now"]))
+        assert _whoami(_app(), bearer=case["token"]) != "anonymous"
+
+    @pytest.mark.parametrize("case", _VECTORS["reject"], ids=lambda c: c["name"])
+    def test_reject_case(self, monkeypatch: pytest.MonkeyPatch, case: dict[str, Any]) -> None:
+        """Reject case."""
+        d = _VECTORS["defaults"]
+        _vector_env(
+            monkeypatch,
+            case.get("verify_keys_b64", d["verify_keys_b64"]),
+            case.get("audience", d["audience"]),
+            case.get("max_ttl_seconds", d["max_ttl_seconds"]),
+        )
+        _at(monkeypatch, case.get("now", d["now"]))
+        with pytest.raises(ClientError):
+            _whoami(_app(), bearer=case["token"])
+
+
+class TestProxyProofGateStillGuards:
+    """Grants go inside VGI's proxy-proof gate, never beside it."""
+
+    @pytest.fixture
+    def gated(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Gated."""
+        monkeypatch.setenv("VGI_PROXY_PROOF_MODE", "require")
+        monkeypatch.setenv("VGI_PROXY_PROOF_ORIGIN_ID", "worker-a")
+        monkeypatch.setenv("VGI_PROXY_PROOF_SECRETS", "k:" + "11" * 32)
+        monkeypatch.setenv(GRANT_KEYS_ENV, _KEY_B64)
+
+    def test_gated_worker_with_grants_starts(self, gated: None) -> None:
+        """vgi-rpc refuses to OR grants beside a proxy gate; create_app composes inside it."""
+        from vgi.serve import _resolve_authenticate
+
+        _app(authenticate=_resolve_authenticate())
+
+    def test_valid_grant_without_proof_is_refused(self, gated: None) -> None:
+        """Valid grant without proof is refused."""
+        from vgi.serve import _resolve_authenticate
+
+        keys = GrantKeys.parse([_KEY_B64])
+        token, _ = mint_grant_token(keys, principal="alice", scopes=[], purpose="p", ttl_seconds=60)
+        with pytest.raises(ClientError):
+            _whoami(_app(authenticate=_resolve_authenticate()), bearer=token)

{vgi_python-0.41.0 → vgi_python-0.42.0}/uv.lock

@@ -2670,7 +2670,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.41.0"
+version = "0.42.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2790,7 +2790,7 @@ requires-dist = [
     { name = "vgi-python", extras = ["test-fixtures"], marker = "extra == 'test-fixtures-writable'" },
     { name = "vgi-python", extras = ["test-fixtures", "test-fixtures-writable", "http", "launch", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.48.0" },
+    { name = "vgi-rpc", specifier = ">=0.49.0" },
     { name = "vgi-rpc", extras = ["cli"], marker = "extra == 'launch'" },
     { name = "vgi-rpc", extras = ["cli", "conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'granian'" },
@@ -2821,7 +2821,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.48.0"
+version = "0.49.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2829,9 +2829,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/e9/b5/e3eded035fd7d947496ef2a923e83babe38da44420e943365ff8b456164d/vgi_rpc-0.48.0.tar.gz", hash = "sha256:862170c57d8a9708ee8bc6185c34a531adf569199a66a86fe35671364ee2732c", size = 1577079, upload-time = "2026-10-06T01:42:23.713Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d5/1c/29d313c20c578d711eadcff65680f7ebf4c574f157dbf45a6689d78f3fb8/vgi_rpc-0.49.0.tar.gz", hash = "sha256:84a1ea49cb24805bdad8ebe2006f63fb69a82fb5a8746b10b3f0a7345f4bb0a9", size = 1610726, upload-time = "2026-10-06T17:29:24.272Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c4/14/b23c4d1ed73330c11de59136634468d82fcdcd0f4c35f0eaec3eea9c2c63/vgi_rpc-0.48.0-py3-none-any.whl", hash = "sha256:4c41726e0ddbea1bd1e47feed77eb192d94da49111bf8bfecb7329d2be5747dd", size = 734936, upload-time = "2026-10-06T01:42:21.946Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/8d/c444dc959722506d3fa5c4fd623a790c3f140cccae2341d97c55d7df403a/vgi_rpc-0.49.0-py3-none-any.whl", hash = "sha256:faae05f9a3d08202c031d0b783c5ff93c6770833fd22fb1479a556267ad4ef63", size = 756201, upload-time = "2026-10-06T17:29:21.983Z" },
 ]
 
 [package.optional-dependencies]

{vgi_python-0.41.0 → vgi_python-0.42.0}/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