vgi-python 0.36.2__py3-none-any.whl → 0.37.1__py3-none-any.whl

vgi/_test_fixtures/secret_cache.py

@@ -0,0 +1,237 @@
+# Copyright 2026 Query Farm LLC - https://query.farm
+
+"""Cacheable fixtures whose results depend on a secret.
+
+The C++ result cache keys a secret-dependent result on a fingerprint of the
+secrets its bind resolved (never their values), so a result is reused while the
+secret is unchanged and recomputed the moment it is rotated, re-scoped or
+dropped. Each fixture here reads the ``vgi_example`` secret's ``secret_string``
+and advertises cacheability, one per cache path the fingerprint has to reach:
+
+* ``secret_cache_nonce()`` — producer table function; the secret is declared in
+  ``Meta.required_secrets``. Also exposed as the ``data.secret_cache_nonce``
+  table with ``inline_bind=True``, which covers the client's inline-bind path
+  (no bind RPC; the secrets are resolved client-side for init).
+* ``secret_cached_scalar(x)`` — scalar, per-value memoized; secret declared via
+  a ``Secret()`` annotation.
+* ``secret_cached_lateral(x)`` — blended map, per-value memoized, called under
+  ``LATERAL``; the secret is requested in ``on_bind`` (the two-phase bind).
+
+Every output carries a ``nonce`` minted only when the worker really runs. It is
+random rather than a counter because a pooled worker may run several processes,
+and a per-process counter can repeat across them: equal nonces prove a cache
+HIT, different ones a MISS, on any pool size.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Annotated, Any, ClassVar, cast
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import OutputCollector
+
+from vgi.arguments import Arg, OutputLength, Param, Returns, Secret, SecretLookupEntry
+from vgi.cache_control import CacheControl
+from vgi.invocation import BindResponse
+from vgi.metadata import FunctionExample
+from vgi.scalar_function import ScalarFunction
+from vgi.schema_utils import schema
+from vgi.table_function import (
+    BindParams,
+    ProcessParams,
+    TableFunctionGenerator,
+    bind_fixed_schema,
+    init_single_worker,
+)
+from vgi.table_in_out_function import RowTransformFunction
+
+if TYPE_CHECKING:
+    from vgi.protocol import VgiOutputCollector
+
+#: The secret type every fixture here reads. Registered by the C++ extension's
+#: test build (``CREATE SECRET ... (TYPE vgi_example, secret_string '...')``).
+SECRET_TYPE = "vgi_example"
+
+#: Long enough that TTL never lapses mid-test.
+_TTL_SECONDS = 300
+
+
+def _nonce() -> int:
+    """A value unique to this invocation, across every process in a worker pool."""
+    return int.from_bytes(os.urandom(7), "big")
+
+
+def _secret_string(secret: dict[str, Any]) -> str | None:
+    """The ``secret_string`` field of a resolved secret, or None when there is none."""
+    value = secret.get("secret_string")
+    if value is None:
+        return None
+    return str(value.as_py()) if isinstance(value, pa.Scalar) else str(value)
+
+
+# ---------------------------------------------------------------------------
+# secret_cache_nonce — producer
+# ---------------------------------------------------------------------------
+@dataclass(slots=True, frozen=True)
+class SecretCacheNonceArgs:
+    """Arguments for SecretCacheNonceFunction (none)."""
+
+
+@dataclass(kw_only=True)
+class _SecretCacheNonceState(ArrowSerializableDataclass):
+    """The one row to emit, minted on a real invocation."""
+
+    secret_string: str | None
+    nonce: int
+    done: bool = False
+
+
+@init_single_worker
+@bind_fixed_schema
+class SecretCacheNonceFunction(TableFunctionGenerator[SecretCacheNonceArgs, _SecretCacheNonceState]):
+    """One row: the secret's ``secret_string`` and a per-invocation nonce; cacheable.
+
+    ``initial_state`` runs only on a cache MISS, so the nonce is stable across
+    HITs. A rotated secret must MISS and report the new value; restoring the
+    original secret must HIT the entry it produced.
+    """
+
+    class Meta:
+        """Metadata for SecretCacheNonceFunction."""
+
+        name = "secret_cache_nonce"
+        description = "One row with a secret's value and a per-invocation nonce; cacheable per secret"
+        categories = ["generator", "cache", "secret", "testing"]
+        required_secrets = [SecretLookupEntry(secret_type=SECRET_TYPE)]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM secret_cache_nonce()",
+                description="The nonce is stable while the vgi_example secret is unchanged",
+            ),
+        ]
+
+    FunctionArguments = SecretCacheNonceArgs
+    FIXED_SCHEMA: ClassVar[pa.Schema] = schema(secret_string=pa.string(), nonce=pa.int64())
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[SecretCacheNonceArgs]) -> _SecretCacheNonceState:
+        """Read the secret and mint a nonce for this (real) invocation."""
+        secret = next(iter(params.secrets.of_type(SECRET_TYPE)), {})
+        return _SecretCacheNonceState(secret_string=_secret_string(secret), nonce=_nonce())
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[SecretCacheNonceArgs],
+        state: _SecretCacheNonceState,
+        out: OutputCollector,
+    ) -> None:
+        """Emit the single row once, advertising a cache TTL."""
+        if state.done:
+            out.finish()
+            return
+        batch = pa.RecordBatch.from_pydict(
+            {"secret_string": [state.secret_string], "nonce": [state.nonce]},
+            schema=params.output_schema,
+        )
+        cast("VgiOutputCollector", out).emit(batch, cache_control=CacheControl(ttl=_TTL_SECONDS))
+        state.done = True
+
+
+# ---------------------------------------------------------------------------
+# secret_cached_scalar — scalar, per-value
+# ---------------------------------------------------------------------------
+class SecretCachedScalarFunction(ScalarFunction):
+    """``x`` -> ``'<secret_string>|<nonce>'``, memoized per value per secret.
+
+    With no secret resolved the label is ``'|<nonce>'``.
+
+    One nonce per ``compute`` call, shared by the batch, so a served value keeps
+    the nonce of the call that produced it. ``per_value`` is a test choice, as on
+    ``cached_double_scalar``: the point is coverage of the tier, not economics.
+    """
+
+    CACHE_CONTROL = CacheControl(ttl=_TTL_SECONDS, per_value=True)
+
+    class Meta:
+        """Function metadata."""
+
+        name = "secret_cached_scalar"
+        description = "Returns '<secret_string>|<nonce>' per value; memoized per value per secret"
+        examples = [
+            FunctionExample(
+                sql="SELECT secret_cached_scalar(1)",
+                description="Stable while the vgi_example secret is unchanged",
+            ),
+        ]
+
+    @classmethod
+    def compute(
+        cls,
+        value: Annotated[pa.Int64Array, Param(doc="Any value; the output ignores it")],
+        _length: Annotated[int, OutputLength()],
+        vgi_example: Annotated[dict[str, pa.Scalar[Any]] | None, Secret(SECRET_TYPE)] = None,
+    ) -> Annotated[pa.StringArray, Returns(pa.string())]:
+        """Label every row with the secret's value ('' when none) and this call's nonce.
+
+        The framework omits a ``Secret()`` argument when no such secret exists,
+        hence the default: a dropped secret is a state this fixture must serve.
+        """
+        label = f"{_secret_string(vgi_example or {}) or ''}|{_nonce()}"
+        return pa.array([label] * _length, type=pa.string())
+
+
+# ---------------------------------------------------------------------------
+# secret_cached_lateral — blended map, per-value, two-phase secret
+# ---------------------------------------------------------------------------
+@dataclass(slots=True, frozen=True, kw_only=True)
+class _SecretCachedLateralArgs:
+    """One positional input column; the output ignores its value."""
+
+    x: Annotated[int, Arg(0, doc="Input column")]
+
+
+class SecretCachedLateralFunction(RowTransformFunction[_SecretCachedLateralArgs]):
+    """1->1 map emitting the secret's ``secret_string`` and a per-call nonce.
+
+    Requests the secret from ``on_bind`` — the two-phase bind, so the secret is
+    discovered at bind time rather than declared — and advertises ``per_value``
+    so a correlated ``LATERAL`` call is memoized per input value per secret.
+    """
+
+    class Meta:
+        """Function metadata."""
+
+        name = "secret_cached_lateral"
+        description = "Blended map emitting a secret's value and a per-call nonce; memoized per secret"
+        categories = ["blended", "cache", "secret", "test"]
+
+    @classmethod
+    def on_bind(cls, params: BindParams[_SecretCachedLateralArgs]) -> BindResponse:
+        """Request the secret (two-phase) and declare the output columns."""
+        params.secrets.get(SECRET_TYPE)
+        return BindResponse(output_schema=schema(secret_string=pa.string(), nonce=pa.int64()))
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_SecretCachedLateralArgs],
+        state: None,
+        batch: pa.RecordBatch,
+        out: OutputCollector,
+    ) -> None:
+        """Emit one row per input row, all carrying this call's nonce."""
+        secret = next(iter(params.secrets.of_type(SECRET_TYPE)), {})
+        rows = batch.num_rows
+        cast("VgiOutputCollector", out).emit(
+            pa.record_batch(
+                {
+                    "secret_string": pa.array([_secret_string(secret)] * rows, type=pa.string()),
+                    "nonce": pa.array([_nonce()] * rows, type=pa.int64()),
+                }
+            ),
+            cache_control=CacheControl(ttl=_TTL_SECONDS, per_value=True),
+        )

vgi/_test_fixtures/table/__init__.py

@@ -113,6 +113,7 @@ from vgi._test_fixtures.table.partition_columns import (
     OverlappingRangePartitionedFunction,
     PartitionedWithExplicitOverrideFunction,
     RegionYearPartitionedFunction,
+    TrailingPartitionSalesFunction,
 )
 from vgi._test_fixtures.table.partition_columns_broken import (
     BrokenMissingPartitionValuesFunction,
@@ -264,6 +265,7 @@ __all__ = [
     "RFF_SIMPLE_COLUMNS",
     "RFF_STRUCT_COLUMNS",
     "RegionYearPartitionedFunction",
+    "TrailingPartitionSalesFunction",
     "RepeatValueIntFunction",
     "RepeatValueStrFunction",
     "RffMultiScanFunction",

vgi/_test_fixtures/table/partition_columns.py

@@ -23,6 +23,11 @@ Fixtures:
 * :class:`RegionYearPartitionedFunction` — multi-column SINGLE_VALUE.
   Each chunk has a single ``(region, year)`` tuple.
 
+* :class:`TrailingPartitionSalesFunction` — same contract as the
+  country fixture, but the partition column is declared LAST rather
+  than first, so the worker-schema and scan-local index spaces do not
+  coincide. Also exposed as a catalog table.
+
 * :class:`PartitionedWithProjectedOutColumnFunction` — declares
   partition on ``category`` but DOES NOT include ``category`` in the
   emitted batch. Uses the explicit ``partition_values=`` override on
@@ -49,7 +54,7 @@ from __future__ import annotations
 
 import struct
 from dataclasses import dataclass
-from typing import Annotated, ClassVar, cast
+from typing import Annotated, Any, ClassVar, cast
 
 import pyarrow as pa
 from vgi_rpc import ArrowSerializableDataclass
@@ -285,6 +290,126 @@ class RegionYearPartitionedFunction(TableFunctionGenerator[_RegionYearArgs, _Reg
         state.current_idx = rpp
 
 
+# =============================================================================
+# SINGLE_VALUE_PARTITIONS with the partition column NOT first
+# =============================================================================
+
+
+@dataclass(slots=True, frozen=True)
+class _TrailingPartitionArgs:
+    """Arguments for ``trailing_partition_sales``."""
+
+    rows_per_country: Annotated[int, Arg(0, doc="Rows to emit per country partition", ge=1)]
+
+
+@dataclass(kw_only=True)
+class _TrailingPartitionState(ArrowSerializableDataclass):
+    """Per-worker cursor over countries (same shape as the country fixture)."""
+
+    current_country: str | None = None
+    current_country_idx: int = -1
+    current_idx: int = 0
+
+
+@bind_fixed_schema
+@_cardinality_from_count
+class TrailingPartitionSalesFunction(TableFunctionGenerator[_TrailingPartitionArgs, _TrailingPartitionState]):
+    """``country`` is single-valued per chunk, but sits LAST in the schema.
+
+    Identical contract to :class:`CountryPartitionedSalesFunction`; the only
+    difference is where the partition column lives. That difference is the
+    point: every other partitioned fixture declares its partition column at
+    index 0, which makes two distinct index spaces accidentally agree.
+
+    ``CanUsePartitionedAggregate`` asks ``get_partition_info`` about
+    WORKER-SCHEMA indices, but the sink later asks ``get_partition_data``
+    about SCAN-LOCAL ones (positions in the scan's own ``column_ids``, after
+    projection pushdown). ``GROUP BY country`` projects just ``country`` and
+    ``sales``, so here the sink asks about scan-local 0 while the declared
+    index is 3 — and a client that compares them without mapping raises
+    "sink requested partition column 0 that is not in the declared partition
+    set", which is fatal. With the partition column at index 0 both spaces
+    say 0 and the bug is invisible.
+
+    Also registered as a catalog TABLE (``example.data.trailing_partition_sales``)
+    because the two paths install their scan functions separately: a client can
+    wire ``get_partition_info`` for direct function calls and miss it for
+    catalog tables, in which case the planner silently never picks
+    ``PARTITIONED_AGGREGATE`` for a table however it is declared.
+    """
+
+    FIXED_SCHEMA: ClassVar[pa.Schema] = pa.schema(
+        cast(
+            "list[pa.Field[Any]]",
+            [
+                pa.field("seq", pa.int64()),
+                pa.field("label", pa.string()),
+                pa.field("sales", pa.int64()),
+                partition_field("country", pa.string()),
+            ],
+        )
+    )
+
+    class Meta:
+        name = "trailing_partition_sales"
+        projection_pushdown = True
+        description = (
+            "Per-country sales rows, one Arrow batch per country, with the "
+            "SINGLE_VALUE partition column declared LAST in the schema "
+            "instead of first."
+        )
+        categories = ["generator", "partitioning"]
+        partition_kind = PartitionKind.SINGLE_VALUE_PARTITIONS
+        examples = [
+            FunctionExample(
+                sql="SELECT country, SUM(sales) FROM trailing_partition_sales(100) GROUP BY country",
+                description="Partitioned aggregate over a non-leading partition column",
+            ),
+        ]
+
+    @classmethod
+    def on_init(cls, params: InitParams[_TrailingPartitionArgs]) -> GlobalInitResponse:
+        items = [struct.pack(_QUEUE_ITEM_FMT, i) for i in range(len(_COUNTRIES))]
+        params.storage.queue_push(items)
+        return GlobalInitResponse()
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_TrailingPartitionArgs]) -> _TrailingPartitionState:
+        return _TrailingPartitionState()
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_TrailingPartitionArgs],
+        state: _TrailingPartitionState,
+        out: OutputCollector,
+    ) -> None:
+        if state.current_country is None or state.current_idx >= params.args.rows_per_country:
+            item = params.storage.queue_pop()
+            if item is None:
+                out.finish()
+                return
+            (state.current_country_idx,) = struct.unpack(_QUEUE_ITEM_FMT, item)
+            state.current_country = _COUNTRIES[state.current_country_idx]
+            state.current_idx = 0
+
+        rpc = params.args.rows_per_country
+        # Same deterministic sales values as country_partitioned_sales, so a
+        # test can assert the two agree column-for-column despite the layout.
+        base = state.current_country_idx * 1_000_000
+        batch = pa.RecordBatch.from_pydict(
+            {
+                "seq": list(range(rpc)),
+                "label": [f"{state.current_country}-{i}" for i in range(rpc)],
+                "sales": [base + i for i in range(rpc)],
+                "country": [state.current_country] * rpc,
+            },
+            schema=cls.FIXED_SCHEMA,
+        )
+        out.emit(batch)
+        state.current_idx = rpc
+
+
 # =============================================================================
 # Projected-out partition column — exercises explicit override path
 # =============================================================================

vgi/_test_fixtures/worker.py

@@ -130,6 +130,11 @@ from vgi._test_fixtures.scalar import (
     UpperCaseFunction,
     WhoAmIFunction,
 )
+from vgi._test_fixtures.secret_cache import (
+    SecretCachedLateralFunction,
+    SecretCachedScalarFunction,
+    SecretCacheNonceFunction,
+)
 from vgi._test_fixtures.table import (
     _VERSIONED_CONSTRAINTS_SCHEMAS,
     _VERSIONED_SCHEMAS,
@@ -243,6 +248,7 @@ from vgi._test_fixtures.table import (
     SplitZeroFunction,
     StructSettingsFunction,
     TenThousandFunction,
+    TrailingPartitionSalesFunction,
     TxCachedValueFunction,
     TypedProbeFunction,
     UnionVarargsFunction,
@@ -450,6 +456,9 @@ _EXAMPLE_CATALOG = Catalog(
                 BufferInputFunction,
                 FilterBySettingFunction,
                 SecretInOutFunction,
+                # Secret-dependent + per_value: cached per secret fingerprint
+                # (see vgi/_test_fixtures/secret_cache.py).
+                SecretCachedLateralFunction,
                 RepeatInputsFunction,
                 SlowCancellableInOutFunction,
                 MultiBatchFinishFunction,
@@ -528,6 +537,7 @@ _EXAMPLE_CATALOG = Catalog(
                 OverlappingRangePartitionedFunction,
                 PartitionedWithExplicitOverrideFunction,
                 RegionYearPartitionedFunction,
+                TrailingPartitionSalesFunction,
                 # Deliberately-broken batch_index fixtures (see
                 # vgi/_test_fixtures/table/batch_index_broken.py). Registered
                 # so SQL integration tests in batch_index_contract.test can
@@ -571,6 +581,7 @@ _EXAMPLE_CATALOG = Catalog(
                 SecretDemoFunction,
                 MultiSecretDemoFunction,
                 ScopedSecretDemoFunction,
+                SecretCacheNonceFunction,
                 ExpressionFilterTestFunction,
                 SequenceFunction,
                 # Split-capable scans (plan() -> named units -> per-split init).
@@ -650,6 +661,7 @@ _EXAMPLE_CATALOG = Catalog(
                 RandomBytesFunction,
                 RandomIntFunction,
                 ReturnSecretValueFunction,
+                SecretCachedScalarFunction,
                 # Schema-disambiguation probes: each name is also registered in
                 # the `data` schema below with a different body. The scalar
                 # covers the scalar bind path; the table-in-out and buffered
@@ -883,6 +895,20 @@ _EXAMPLE_CATALOG = Catalog(
                     columns=schema(n=pa.int64()),
                     comment="123456 integers; stats served by the sequence function, not the table",
                 ),
+                # PartitionColumns as a CATALOG TABLE. A table's scan function is
+                # built through a different path than a direct function call, so a
+                # client can support partitioned aggregates for one and silently
+                # not the other; only a table exercises the catalog path. Paired
+                # with a partition column declared last — see the fixture docstring.
+                Table(
+                    name="trailing_partition_sales",
+                    function=TrailingPartitionSalesFunction,
+                    arguments=Arguments(positional=(pa.scalar(100),)),
+                    comment=(
+                        "Per-country sales, SINGLE_VALUE partition column declared last; "
+                        "GROUP BY country must plan as PARTITIONED_AGGREGATE"
+                    ),
+                ),
                 # Result-cache fixtures, exposed as function-backed tables so the
                 # catalog-attached path (SELECT ... FROM ex.data.<name>) exercises
                 # the C++ result cache. See vgi/_test_fixtures/table/cache.py.
@@ -896,6 +922,15 @@ _EXAMPLE_CATALOG = Catalog(
                     function=CacheNonceFunction,
                     comment="One-row cacheable result whose value changes per real invocation",
                 ),
+                # A secret-dependent cacheable table, pre-bound (inline_bind) so a
+                # scan takes the client's no-RPC bind path, where the secrets the
+                # cache keys on are resolved client-side. See secret_cache.py.
+                Table(
+                    name="secret_cache_nonce",
+                    function=SecretCacheNonceFunction,
+                    inline_bind=True,
+                    comment="One-row cacheable result keyed on the vgi_example secret",
+                ),
                 Table(
                     name="cache_multicol",
                     function=CacheMultiColFunction,

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/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/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:

{vgi_python-0.36.2.dist-info → vgi_python-0.37.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.36.2
+Version: 0.37.1
 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.dist-info → vgi_python-0.37.1.dist-info}/RECORD

@@ -5,7 +5,7 @@ vgi/aggregate_function.py,sha256=NYxudbvQ9ZLkP2w5hRdd4YgsGUZ_0cVfqqXnlmJPfls,273
 vgi/argument_spec.py,sha256=SADH97VlFu3asI8CWZ_I7XTuSxwqFciFgdupdAf-tkY,34231
 vgi/arguments.py,sha256=ncnC1CS7KN-2rDjSw9vdf1uHqV5ozebet_eZtcq_ujw,72300
 vgi/attach_header.py,sha256=sxpzCOVa5fl_-kQSCZgeUxS5I9Kuv8VCUjAOF5s1pr0,3782
-vgi/auth.py,sha256=m97hDDR8bXIQRBvqhHQZesBrNkAnKgSH6jhuXtGubjI,4688
+vgi/auth.py,sha256=qMhaLlQfn6F_ovMg4vwD8fl55THalWrSQ9A_V8arGDU,5195
 vgi/cache_control.py,sha256=IyBp9gZTCc4Y-4V7Rs05_o5lSEjbR2jt6cddXPU0dKw,7812
 vgi/copy_from_function.py,sha256=oroQe5qYzZTJ-ppzQTQ-OruEF1ZlwTBNLBoXYfN-P2o,7133
 vgi/copy_to_function.py,sha256=8l0v_DyEF1EnFwinStrZDQ-yNFfGJsv3Mr5o2jG30f0,9279
@@ -30,13 +30,13 @@ 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=5UmvRAGcHj5RKCOUQMXG9RFVYAbLZsHwwk1qVI9fipY,63844
+vgi/serve.py,sha256=DfHSp6B30v_EgWoswsqtmfQ4Fwz1PrnJqvUo1GwM2hA,64416
 vgi/split_token.py,sha256=tutcksj-hgWrLY7UW3sSqkyoaD-cMqNTOeff40MGl_g,10850
 vgi/table_buffering_function.py,sha256=O5TcIdqk8-YViCQCkb8bOevO-zhe3IoyzLgwXDO3Cjc,19531
 vgi/table_filter_pushdown.py,sha256=4Qo4OAOLjTYQ5pinNTOjLCDnb96OHqpcxJlbSJo3cJU,67144
 vgi/table_function.py,sha256=8Pti3uFnsRaPCVG-CGYl9r3GHJF146Fp_62oXXwHKKw,73502
 vgi/table_in_out_function.py,sha256=F2QEtsbGEYHDVyQ4Cf9OCW7HlWXeqekAyx607foB-bs,19393
-vgi/worker.py,sha256=MGMQmy6PPKCqo5q_9fBS3z3zf4y6-UKdJAJiHGfnk50,249553
+vgi/worker.py,sha256=0ez46DE5tc1-78ll29lBP7KRKdDJnkOv89gdr4RjLrE,253453
 vgi/write_results.py,sha256=-OrUcz6E9ahhC_pnKYAwIMR2LpapwQafLC4IOnPTmec,2851
 vgi/_test_fixtures/__init__.py,sha256=xQq-QQLk8USQ6TZHsPiPcZldNNUdcJ2gToXMPGzScLI,444
 vgi/_test_fixtures/attach_options.py,sha256=ZNgNTNF1RymSfnU-uVIDTLvCpc283h6O8tZ1UuEa3Lc,12516
@@ -51,13 +51,14 @@ vgi/_test_fixtures/global_functions.py,sha256=G1h0w5o6bHMULDFLZuNjrZVrBbO6Cre6kT
 vgi/_test_fixtures/http_server.py,sha256=AviomIEClCEuA9WPgQOzrMtQ484N04rQupK8dWO1tOE,19449
 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
 vgi/_test_fixtures/simple_writable.py,sha256=OmyENVnsgJmYH0_5sNWMt_Xgj9JoPaOu7uI5_ROZDKg,32020
 vgi/_test_fixtures/table_in_out.py,sha256=AlBBsbwsMfZkCjGxoCub--OJqmQAim5PgWxAdpbO9Ik,93190
 vgi/_test_fixtures/table_in_out_same_name.py,sha256=jdsQNdKn64T54W_TcLB-rhydI69Y0Uzr5n6FU7v9rIU,8649
 vgi/_test_fixtures/twin_catalogs.py,sha256=UFsFuZ_nFpe62HatGnOMru36vk35Xt3Ta1Hkr1aWN9w,4450
 vgi/_test_fixtures/versioned.py,sha256=gnxNejc4cNGPKl_DxJk1SU8Ielj-rwmQYGkiShXzxK4,5786
 vgi/_test_fixtures/versioned_tables.py,sha256=_JHPe6LaiO0x2We28Ion8hh6pSATmHZYvAczB4uwBsA,22272
-vgi/_test_fixtures/worker.py,sha256=ybrkhnYchWhbdMbUYKHHsnB6W0K5y9-QplyJSx2Bs7Y,96508
+vgi/_test_fixtures/worker.py,sha256=wNsVolPolKxcmvcq3G_G2GeiVGvYOvEr-nj57OqR-T4,98381
 vgi/_test_fixtures/accumulate/__init__.py,sha256=4hYT8jqRoVHSjV9TB7v0Z1CMJtdLuPaDWSz4J2fvMDs,868
 vgi/_test_fixtures/accumulate/worker.py,sha256=4a2VaCoOIXPEoJpkNume7FoBlQzs9kRl8b-_ZJMHvnQ,30165
 vgi/_test_fixtures/aggregate/__init__.py,sha256=2GCp80FNrsWFOA2SV3lCffzLjoN5AKwrf57t2YRg8O0,2393
@@ -90,7 +91,7 @@ vgi/_test_fixtures/scalar/settings_secrets.py,sha256=ZOGkGY0CoD3ous_ij0--ss5byB4
 vgi/_test_fixtures/scalar/type_info.py,sha256=2WeTxakT-_tcWybPfkCrAHVAMOadFN3tb8E3_EmqIyw,6304
 vgi/_test_fixtures/schema_reconcile/__init__.py,sha256=rCCtM5bd67-PTPeIYg9SCJaKUSglA6YeXsedQBEUlmA,1324
 vgi/_test_fixtures/schema_reconcile/worker.py,sha256=_r-cCQC3r48F0yTEdZC5zQYN_vuCx1HIkoP8_idBJHk,23680
-vgi/_test_fixtures/table/__init__.py,sha256=qwTsNJLlsWgD4wEJav8e6pU1MQl8jV8Gvw6wR0v9crM,9945
+vgi/_test_fixtures/table/__init__.py,sha256=IDPDX_T3V1J_CgICHPwOC2EmioWh-8q1imG-29j30XA,10019
 vgi/_test_fixtures/table/_common.py,sha256=m_99LRrDlULKGg8W8gJQQ29-_RxFINFlCMi3JtM0Y08,7753
 vgi/_test_fixtures/table/batch_index.py,sha256=P5ds0xgikuEQanSEWVWKMLbdvIzUeJraI-GuSoPdb6U,11641
 vgi/_test_fixtures/table/batch_index_broken.py,sha256=kZOGrLL7ZW1rmwPmNEYRmiF_vqIfHsfXioq5vKPWHk0,7314
@@ -102,7 +103,7 @@ vgi/_test_fixtures/table/make_series.py,sha256=K-G_YNq25Kb7I5bp6XK4rCZzwMYNTxgKH
 vgi/_test_fixtures/table/misc.py,sha256=71WOIFqk5ntnEIqsG-57rZ9DY7ShQqMKHi7yluNAlM4,16250
 vgi/_test_fixtures/table/order_modes.py,sha256=FU6CoHCK61VyDdFVbl_MnlgZKGINsDsTwDmv3uD8590,6214
 vgi/_test_fixtures/table/pairs.py,sha256=qY7ZtnSnRoo_5EwtOcSw3zwmXCaZS0oO6ujpfRrWzlo,18450
-vgi/_test_fixtures/table/partition_columns.py,sha256=X3zJIo7P-7-FxHovYKE_reBRugU43H7Msnz4JOxMpJ0,21191
+vgi/_test_fixtures/table/partition_columns.py,sha256=mJVqt1YSFskkhoX3GdVDTypI6xYF5zcbFDNqXWBjtJ4,26419
 vgi/_test_fixtures/table/partition_columns_broken.py,sha256=r4u2Kx5XfUtVeRc-1BRW-kVychJyrrYGdYYuvZnm1MM,11265
 vgi/_test_fixtures/table/profiling_example.py,sha256=Rt3fgKxJhr7Q8QQRss2-OV13wh2mDXNZjnXW9sBMokQ,6754
 vgi/_test_fixtures/table/required_filters.py,sha256=StJeS2tQYyXjivNs_tkcRBq4rVtIGoGQDWcggib1Rxg,7079
@@ -152,8 +153,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.36.2.dist-info/METADATA,sha256=kwE2GNB9zbRBOopkbMvkpJoV6dW7sbz8p6f5CGUtU-s,25617
-vgi_python-0.36.2.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
-vgi_python-0.36.2.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
-vgi_python-0.36.2.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
-vgi_python-0.36.2.dist-info/RECORD,,
+vgi_python-0.37.1.dist-info/METADATA,sha256=OHlynVvSIFSRgUwmDrC4VM_feodAW72FCUVuvBJ5Wx4,25617
+vgi_python-0.37.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vgi_python-0.37.1.dist-info/entry_points.txt,sha256=3Kz1vgodw3pOL_xjtSyDB55-ZRy-U2X-X_Bdr582x0Q,165
+vgi_python-0.37.1.dist-info/licenses/LICENSE,sha256=pbJb4zZasP6n5ifEV81wFu017TarjydaYVmGbHcehtY,6103
+vgi_python-0.37.1.dist-info/RECORD,,

{vgi_python-0.36.2.dist-info → vgi_python-0.37.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.3
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any