Skip to content

keelgate.capabilities

Stability of each symbol (stable or provisional) is listed in the API contract. Narrative and semantics are in the integration contract.

Capability definitions and scoped, explicitly issued grants. Deny by default.

Budget

Bases: BaseModel

A spending ceiling, in whatever cost units the tools declare.

BudgetLedger

Bases: Protocol

Where a grant's remaining budget is tracked.

Implement this to share budgets across processes. Reservations must be atomic so spend can never exceed the grant.

Capability

Bases: str

A validated capability string. Immutable, hashable, and still a str.

CapabilityGrant

Bases: BaseModel

The verified claims of a grant. Only ever built by :class:GrantVerifier.

allows 

allows(capability: str) -> bool

True only for an exact, explicitly granted capability.

GrantError

Bases: Exception

Base class: the presented grant cannot be used.

GrantExpiredError

Bases: GrantError

The grant's lifetime has ended.

GrantInvalidError

Bases: GrantError

Malformed, wrongly signed, wrong purpose, or otherwise untrustworthy.

GrantNotYetValidError

Bases: GrantError

The grant's not-before time has not arrived.

GrantRevokedError

Bases: GrantError

The grant was revoked after it was issued.

GrantSigner

Holds the Ed25519 private key and signs grants. Guard it like a root key.

public_key_pem 

public_key_pem() -> bytes

The verifier-side half; safe to distribute.

GrantVerifier

Verifies grant tokens against a set of trusted public keys.

Holds only public keys: it can accept grants but never mint one.

verify 

verify(token: str) -> CapabilityGrant

Return the grant claims, or raise a :class:GrantError.

InMemoryBudgetLedger

Atomic per-grant spend tracking.

Process-local; a shared store is needed wherever several processes honour the same grant.

release 

release(grant_id: str, amount: float) -> None

Return a reservation for an action that never executed.

try_reserve 

try_reserve(
    grant_id: str, amount: float, limit: float
) -> bool

Spend amount against limit atomically; False if it would exceed.

InMemoryRevocationList

Process-local revocations. A shared store is needed for multi-process use.

InvalidCapabilityError

Bases: ValueError

Raised for a malformed capability string, including any wildcard.

RevocationList

Bases: Protocol

Where revoked grant ids are recorded.

Implement this to share revocations across processes.

SignedGrant dataclass

A freshly issued grant: the bearer token and its parsed grant.

SqliteBudgetLedger

Atomic per-grant spend, persisted. Implements :class:BudgetLedger.

release 

release(grant_id: str, amount: float) -> None

Return a reservation for an action that never executed.

try_reserve 

try_reserve(
    grant_id: str, amount: float, limit: float
) -> bool

Spend amount against limit in one transaction; False if it would exceed.

SqliteRevocationList

Persisted revocations. Implements :class:RevocationList.

UnknownKeyError

Bases: GrantError

Signed by a key the verifier does not trust.

issue_grant 

issue_grant(
    signer: GrantSigner,
    *,
    agent_id: str,
    tenant_id: str,
    capabilities: Iterable[str],
    max_cost: float,
    ttl: timedelta,
    clock: Clock = utc_now,
    not_before: datetime | None = None,
    max_ttl: timedelta = DEFAULT_MAX_TTL,
) -> SignedGrant

Mint a grant. Raises ValueError rather than issuing anything unsafe.

capabilities must be non-empty and wildcard-free. ttl must be positive and no longer than max_ttl.