Struct CapabilityEngine 

pub struct CapabilityEngine<P: PolicyBackend> { /* private fields */ }

The Hessra Capability Engine.

Evaluates policy, orchestrates token minting/verification, and manages information flow control via context tokens.

The engine is generic over a PolicyBackend implementation, allowing different policy models (CList, RBAC, ABAC, etc.) to be plugged in.

Implementations

impl<P: PolicyBackend> CapabilityEngine<P>

pub fn new(policy: P, keypair: KeyPair) -> Self

Create a new engine with a policy backend and signing keypair.

pub fn with_generated_keys(policy: P) -> Self

Create a new engine that generates its own keypair.

Useful for local/development use where the engine manages its own keys.

pub fn public_key(&self) -> PublicKey

Get the engine’s public key (for token verification).

pub fn policy(&self) -> &P

Get a reference to the policy backend.

pub fn evaluate( &self, subject: &ObjectId, target: &ObjectId, operation: &Operation, context: Option<&ContextToken>, ) -> PolicyDecision

Evaluate whether a capability request would be granted, without minting.

Checks both the capability space (does the subject hold this capability?) and exposure restrictions (would context exposure block this?).

pub fn mint_capability( &self, subject: &ObjectId, target: &ObjectId, operation: &Operation, context: Option<&ContextToken>, ) -> Result<MintResult, EngineError>

Mint a capability token for a subject to access a target with an operation.

The engine:

1. Evaluates the policy (capability space + exposure restrictions)
2. If granted, mints a capability token via hessra-cap-token
3. If the target has data classifications, auto-applies exposure to the context

Returns a MintResult containing the token and optionally an updated context.

pub fn verify_capability( &self, token: &str, target: &ObjectId, operation: &Operation, ) -> Result<(), EngineError>

Verify a capability token for a target and operation.

This is capability-first verification: no subject is required. The token IS the proof of authorization.

pub fn mint_capability_with_options( &self, subject: &ObjectId, target: &ObjectId, operation: &Operation, context: Option<&ContextToken>, options: MintOptions, ) -> Result<MintResult, EngineError>

Mint a capability token with additional restrictions.

Like mint_capability, but supports namespace restriction and custom time config. This is useful when the caller needs to propagate namespace restrictions or control token lifetime.

pub fn issue_capability( &self, subject: &ObjectId, target: &ObjectId, operation: &Operation, options: MintOptions, ) -> Result<String, EngineError>

Issue a capability token directly, without policy evaluation.

Use this when the caller has already performed authorization checks through its own mechanisms (e.g., enterprise RBAC, custom domain logic). For the fully-managed path that includes policy evaluation, use mint_capability or mint_capability_with_options instead.

pub fn attenuate_with_designations( &self, token: &str, designations: &[Designation], ) -> Result<String, EngineError>

Attenuate a capability token with designations.

Adds designation checks to narrow the token’s scope to specific object instances. The verifier must provide matching designation facts.

pub fn mint_designated_capability( &self, subject: &ObjectId, target: &ObjectId, operation: &Operation, designations: &[Designation], context: Option<&ContextToken>, ) -> Result<MintResult, EngineError>

Convenience: mint a capability and immediately attenuate with designations.

pub fn verify_designated_capability( &self, token: &str, target: &ObjectId, operation: &Operation, designations: &[Designation], ) -> Result<(), EngineError>

Verify a capability token that includes designation checks.

pub fn mint_identity( &self, subject: &ObjectId, config: IdentityConfig, ) -> Result<String, EngineError>

Mint an identity token for a subject.

pub fn authenticate(&self, token: &str) -> Result<ObjectId, EngineError>

Verify an identity token and return the authenticated object ID.

This verifies the token as a bearer token (no specific identity required).

pub fn verify_identity( &self, token: &str, expected_identity: &ObjectId, ) -> Result<(), EngineError>

Verify an identity token for a specific identity.

pub fn mint_context( &self, subject: &ObjectId, session_config: SessionConfig, ) -> Result<ContextToken, EngineError>

Mint a fresh context token for a subject (new session, no exposure).

pub fn add_exposure( &self, context: &ContextToken, data_source: &ObjectId, ) -> Result<ContextToken, EngineError>

Add exposure to a context token from a specific data source.

Looks up the data source’s classification in the policy and adds the corresponding exposure labels to the context token.

pub fn add_exposure_label( &self, context: &ContextToken, label: ExposureLabel, source: &ObjectId, ) -> Result<ContextToken, EngineError>

Add a specific exposure label directly to a context token.

pub fn fork_context( &self, parent: &ContextToken, child_subject: &ObjectId, session_config: SessionConfig, ) -> Result<ContextToken, EngineError>

Fork a context token for a sub-agent, inheriting the parent’s exposure.

pub fn extract_exposure( &self, context: &ContextToken, ) -> Result<Vec<ExposureLabel>, EngineError>

Extract exposure labels from a context token by re-parsing the Biscuit.

pub fn list_grants(&self, subject: &ObjectId) -> Vec<CapabilityGrant>

List all capability grants for a subject.

pub fn can_delegate(&self, subject: &ObjectId) -> bool

Check if a subject can delegate capabilities.