token

Module: token

Contents

Modules

• paseto

Structs

• CapabilityClaims - Payload of a signed capability token.
• InvalidTokenIdError - Error returned when a [TokenId] string fails validation.
• TokenId - Unique identifier for a capability token.

Enums

• TokenError - Errors from token signing, verification, and revocation operations.
• TokenState - Lifecycle state of a capability token.

Functions

• matches_resource_scope

Traits

• RevocationStore - Check and record token revocations.
• TokenSigner - Serialize and cryptographically sign capability claims into a token string.
• TokenVerifier - Parse, verify signature, validate expiry, and return capability claims.

---

firma_core::token::CapabilityClaims

Struct

Payload of a signed capability token.

Represents the authority’s grant to an agent for a scoped set of actions and resources within a session. Carried inside a PASETO v4 or JWT token.

Field names mirror the proto CapabilityToken message in firma/v1/types.proto.

Fields:

• token_id: TokenId - Globally unique identifier for this token. Used for revocation lookups.
• agent_id: crate::agent::AgentId - Identity of the agent this token was issued to.
• session_id: crate::session::SessionId - Session within which this token is valid.
• action_set: Vec<String> - Allowed action set (e.g., ["http:GET", "tool:execute"]). May be empty.
• resource_scope: String - Resource scope pattern this token covers (e.g., "api.example.com/*").
• issued_at: chrono::DateTime<chrono::Utc> - When the Authority issued this token.
• expiry: chrono::DateTime<chrono::Utc> - When this token expires. Validation enforced by TokenVerifier, not at construction.
• context_hash: String - Hex-encoded SHA-256 of the Cedar context snapshot at issuance time.
• budget_ceiling: Option<f64> - Maximum cumulative budget the Authority grants for this token’s

Trait Implementations:

• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• PartialEq
  • fn eq(self: &Self, other: &CapabilityClaims) -> bool
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Clone
  • fn clone(self: &Self) -> CapabilityClaims

firma_core::token::InvalidTokenIdError

Struct

Error returned when a [TokenId] string fails validation.

Tuple Struct: ()

Trait Implementations:

• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• From
  • fn from(source: uuid::Error) -> Self
• Error
  • fn source(self: &Self) -> ::core::option::Option<&dyn ::thiserror::__private18::Error>

firma_core::token::RevocationStore

Trait

Check and record token revocations.

Methods:

• is_revoked: Check if a token has been revoked by its ID.
• add_revocation: Record a token revocation.

firma_core::token::TokenError

Enum

Errors from token signing, verification, and revocation operations.

Variants:

• ParseFailure{ reason: String } - Token could not be parsed from the raw string.
• SignatureInvalid{ reason: String } - Token signature verification failed.
• Expired{ token_id: TokenId } - Token has expired.
• Revoked{ token_id: TokenId } - Token has been revoked.
• Malformed{ reason: String } - Token payload is malformed or missing required fields.

Traits: Error

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Display
  • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

firma_core::token::TokenId

Struct

Unique identifier for a capability token.

Generated by the Authority at issuance time via [TokenId::new]. Serialises and deserialises as a plain UUID string.

Tuple Struct: ()

Methods:

• fn new() -> Self - Generate a new unique token ID.

Traits: Eq, Copy

Trait Implementations:

• TryFrom
  • fn try_from(s: String) -> Result<Self, <Self as >::Error>
• AsRef
  • fn as_ref(self: &Self) -> &uuid::Uuid
• PartialEq
  • fn eq(self: &Self, other: &TokenId) -> bool
• FromStr
  • fn from_str(s: &str) -> Result<Self, <Self as >::Err>
• Clone
  • fn clone(self: &Self) -> TokenId
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Hash
  • fn hash<__H>(self: &Self, state: & mut __H)
• Default
  • fn default() -> Self
• Display
  • fn fmt(self: &Self, f: & mut std::fmt::Formatter) -> std::fmt::Result
• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_core::token::TokenSigner

Trait

Serialize and cryptographically sign capability claims into a token string.

Format-agnostic — implementations choose the token format (PASETO v4, JWT, etc.). All implementations must be object-safe for dynamic dispatch.

Methods:

• sign: Sign the given claims and return a serialized token string.

firma_core::token::TokenState

Enum

Lifecycle state of a capability token.

Terminal states (Expired, Revoked, Aborted) cannot transition to any other state.

Variants:

• Issued - Token created by Authority, not yet delivered to agent.
• Active - Token delivered to agent, available for use.
• InUse - Token currently attached to an in-flight execution.
• Expired - Token TTL has elapsed. Terminal.
• Revoked - Token explicitly revoked by Authority or policy. Terminal.
• Aborted - Token invalidated due to policy abort. Terminal.

Traits: Eq, Copy

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> TokenState
• Serialize
  • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• Deserialize
  • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
• PartialEq
  • fn eq(self: &Self, other: &TokenState) -> bool

firma_core::token::TokenVerifier

Trait

Parse, verify signature, validate expiry, and return capability claims.

Format-agnostic — implementations choose the token format (PASETO v4, JWT, etc.). All implementations must be object-safe for dynamic dispatch.

Methods:

• verify: Verify a raw token string and return the validated claims.

firma_core::token::matches_resource_scope

Function

fn matches_resource_scope(scope: &str, resource: &str) -> bool

Module: paseto