cayu.egress.grants

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

VirtualCredentialGrant

from cayu.egress import VirtualCredentialGrant

A per-session binding of a virtual credential to a real secret reference.

The grant is what the sandbox is allowed to present; it carries a SecretRef (a pointer), never a resolved secret value. Only the broker, outside the sandbox, exchanges the presented value for the real secret. A grant is therefore safe to log, store, and hand to the sandbox.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
grant_id	str	required
session_id	str	required
env_name	str	required
presented_value	str	required
secret	SecretRef	required
destination	str	required
credential_kind	str	required
policy_name	str | None	None
created_at	datetime	required
expires_at	datetime | None	None
metadata	dict[str, Any]	Field(default_factory=dict)

validate_nonblank (method)

VirtualCredentialGrant.validate_nonblank(value: str, info) -> str

validate_destination (method)

VirtualCredentialGrant.validate_destination(value: str, info) -> str

validate_policy_name (method)

VirtualCredentialGrant.validate_policy_name(value: str | None, info) -> str | None

copy_ref (method)

VirtualCredentialGrant.copy_ref(value: SecretRef) -> SecretRef

copy_metadata (method)

VirtualCredentialGrant.copy_metadata(value: dict[str, Any]) -> dict[str, Any]

is_expired (method)

VirtualCredentialGrant.is_expired(now: datetime) -> bool

Release source · Runtime guarantees · Capability guides

VirtualCredentialLease

from cayu.egress import VirtualCredentialLease

An active broker request’s lease on a live virtual credential grant.

init (method)

VirtualCredentialLease.__init__(registry: VirtualCredentialRegistry, grant: VirtualCredentialGrant) -> None

ensure_active (method)

VirtualCredentialLease.ensure_active() -> None

close (method)

VirtualCredentialLease.close() -> None

Release source · Runtime guarantees · Capability guides

VirtualCredentialRegistry

from cayu.egress import VirtualCredentialRegistry

Mints, binds, and revokes per-session virtual credentials.

The registry holds no real secret material — only grants, which carry SecretRef pointers. It is the broker’s source of truth for whether a presented value is currently a live, unexpired, unrevoked credential.

init (method)

VirtualCredentialRegistry.__init__(*, clock: Callable[[], datetime]=_utcnow) -> None

mint (method)

VirtualCredentialRegistry.mint(*, session_id: str, env_name: str, secret: SecretRef, destination: str, credential_kind: str, policy_name: str | None=None, ttl_seconds: float | None=None, metadata: dict[str, Any] | None=None, presented_value: str | None=None) -> VirtualCredentialGrant

Create and register a new virtual credential grant.

bind (method)

VirtualCredentialRegistry.bind(grant: VirtualCredentialGrant) -> VirtualCredentialGrant

Register an externally-constructed grant.

acquire (method)

VirtualCredentialRegistry.acquire(presented_value: str) -> VirtualCredentialLease

Acquire a live grant for one broker request.

The lease lets teardown mark a grant revoked while an already-started request is still resolving, and lets the broker re-check liveness before the real credential is sent upstream.

lookup (method)

VirtualCredentialRegistry.lookup(presented_value: str, *, now: datetime | None=None) -> VirtualCredentialGrant

Return the live grant for a presented value or raise.

Raises VirtualCredentialError for unknown, revoked, or expired values. The broker calls this before any policy check or vault resolve.

revoke (method)

VirtualCredentialRegistry.revoke(presented_value: str) -> bool

Revoke by presented value. Returns whether a grant was removed.

revoke_and_wait (method)

async VirtualCredentialRegistry.revoke_and_wait(presented_value: str) -> bool

Revoke by presented value and wait for active broker leases to drain.

revoke_values (method)

VirtualCredentialRegistry.revoke_values(presented_values: Sequence[str]) -> tuple[int, tuple[str, ...]]

Revoke values synchronously and return the affected grant identities.

The separate drain identities let an owner revoke every authority before it settles work that is holding the corresponding request leases.

revoke_values_and_wait (method)

async VirtualCredentialRegistry.revoke_values_and_wait(presented_values: Sequence[str]) -> int

Revoke every presented value, then wait for all active leases to drain.

Revocation is intentionally two-phase: first mark every matching grant revoked without awaiting, then wait for in-flight broker leases. That prevents teardown of a multi-credential session from leaving later credentials live while an earlier credential’s active request drains.

wait_for_inactive_grants (method)

async VirtualCredentialRegistry.wait_for_inactive_grants(grant_ids: Sequence[str]) -> None

Wait until every listed grant has no active broker request leases.

revoke_session (method)

VirtualCredentialRegistry.revoke_session(session_id: str) -> int

Revoke every grant bound to session_id. Returns the count.

revoke_session_and_wait (method)

async VirtualCredentialRegistry.revoke_session_and_wait(session_id: str) -> int

Revoke every session grant and wait for active broker leases to drain.

was_revoked (method)

VirtualCredentialRegistry.was_revoked(grant_id: str) -> bool

active_grants (method)

VirtualCredentialRegistry.active_grants() -> tuple[VirtualCredentialGrant, ...]

Release source · Runtime guarantees · Capability guides