Struct Capability

Source

pub struct Capability<P, R>where
    P: Permission,
    R: Resource,
{ /* private fields */ }

Expand description

An unforgeable proof that subject subject holds permission P on resource R.

Construct via PolicyEngine::mint_capability. The phantom parameters P and R are erased at runtime but enforced at compile time.

Implementations§

Source §

impl<P, R> Capability<P, R>
where P: Permission, R: Resource,

Source

pub fn subject(&self) -> &str

The subject that holds this capability.

Source

pub fn resource_id(&self) -> &str

The resource identifier this capability covers.

Source

pub fn issued_at(&self) -> SystemTime

When the policy engine minted this capability.

A capability is a point-in-time decision: policy changes after this instant are not reflected in the token. Long-lived holders should re-request rather than cache, or gate use on is_fresh.

Source

pub fn expires_at(&self) -> SystemTime

When this capability expires.

Source

pub fn is_fresh(&self, max_age: Duration) -> bool

Whether this capability was minted within the last max_age.

Use this to bound the window between the policy check and the action (TOCTOU): cap.is_fresh(Duration::from_secs(60)).

Source

pub fn is_expired(&self) -> bool

Whether this capability’s lease has expired.

Source

pub fn is_revoked(&self) -> bool

Whether this capability was revoked via its RevocationEpoch.

Always false for capabilities minted without a revocation binding.

Source

pub fn ensure_active(&self) -> Result<(), CapabilityUseError>

Validate that this capability can still be used (not expired, not revoked).

Source

pub fn permission_name() -> &'static str

The permission name (from the type parameter).

Source §

impl<P, R> Capability<P, R>
where P: Permission, R: Resource,

Source

pub fn coerce<Q>(self) -> Capability<Q, R>
where Q: Permission, P: Implies<Q>,

Downcast this capability to a less-privileged one.

Only callable when P: Implies<Q> — the compiler enforces the lattice. This is a zero-cost operation: subject and resource are preserved; only the permission type parameter changes.

§Example

let write_cap: Capability<CanWrite, Report> =
    agent.request_capability(&report).await?;
// CanWrite → CanRead is a valid lattice relationship:
let read_cap: Capability<CanRead, Report> = write_cap.coerce();

Source

pub fn coerce_ref<Q>(&self) -> Capability<Q, R>
where Q: Permission, P: Implies<Q>,

Like coerce, but borrows — the original (higher) capability is retained.

This is safe for the same reason coerce is: P: Implies<Q> means the holder of P already has every right Q grants, so deriving a Q token grants nothing new.