Struct CapabilityToken 

pub struct CapabilityToken {

    pub schema: String,
    pub id: String,
    pub issuer: PublicKey,
    pub subject: PublicKey,
    pub scope: ChioScope,
    pub issued_at: u64,
    pub expires_at: u64,
    pub delegation_chain: Vec<DelegationLink>,
    pub aggregate_invocation_budget: Option<AggregateInvocationBudget>,
    pub algorithm: Option<SigningAlgorithm>,
    pub caveats: Vec<Caveat>,
    pub scope_attenuations: Option<Vec<Attenuation>>,
    pub attenuation_proof: Option<AttenuationProof>,
    pub budget_share_bps: Option<u16>,
    pub signature: Signature,
}

A Chio capability token. Scoped, time-bounded, cryptographically signed.

The signature field covers the canonical JSON of all other fields. Verification re-serializes the token (excluding the signature), computes the canonical form, and checks the signature against issuer using the algorithm declared by the algorithm field (defaulting to Ed25519 when absent).

Fields

schema: String

Versioned signed-artifact schema. Wire schema identifier; tokens that omit this field default to chio.capability.v1.

id: String

Unique token ID (UUIDv7 recommended, used for revocation).

issuer: PublicKey

Capability Authority (or delegating agent) that issued this token.

subject: PublicKey

Agent this capability is bound to (DPoP sender constraint).

scope: ChioScope

What this token authorizes.

issued_at: u64

Unix timestamp (seconds) when the token was issued.

expires_at: u64

Unix timestamp (seconds) when the token expires.

delegation_chain: Vec<DelegationLink>

Ordered list of delegation links from the root CA to this token.

aggregate_invocation_budget: Option<AggregateInvocationBudget>

Optional invocation ceiling shared by this capability or its delegation family.

algorithm: Option<SigningAlgorithm>

Signing algorithm. Absent means Ed25519 (the default).

caveats: Vec<Caveat>

Typed caveats. Empty tokens omit this on the wire.

scope_attenuations: Option<Vec<Attenuation>>

High-level attenuation request exposed on attenuated tokens.

attenuation_proof: Option<AttenuationProof>

Wire witness proving child-scope attenuation.

budget_share_bps: Option<u16>

Fixed-point sub-agent budget share in basis points. Values above 10000 are rejected by validation.

signature: Signature

Signature over canonical JSON of all fields above.

Implementations

impl CapabilityToken

pub fn body(&self) -> CapabilityTokenBody

Extract the body (everything except the signature) for re-verification.

pub fn signing_body(&self) -> CapabilityTokenSigningBody

Extract the schema-aware body used for newly-issued signatures.

pub fn validate_schema(&self) -> Result<(), Error>

Reject unknown schema IDs and budget amplification.

pub fn validate_chain_binding( &self, trust_root_scope_hash: &String, ) -> Result<(), Error>

Delegation chain-binding check.

Closes the P0 soundness bug where attenuation_proof.parent_scope_hash was unbound from the issuer’s actual upstream parent capability. An issuer with true authority scope_X can no longer mint a token claiming parent_scope = scope_BIGGER and have the verifier accept it: this check requires parent_scope_hash to equal either

• trust_root_scope_hash (when the chain is empty: a direct issue from the trust-root authority binds the witness to the verifier-known authority hash); or
• delegation_chain.last().scope_hash (when delegation has occurred: the witness must bind to the immediate predecessor’s authorized scope, which is itself signed by the predecessor’s key as part of the chain).

Combined with [validate_delegation_chain_with_trust_root], this closes the chain-binding gap: there is no longer a way to inflate parent_scope and supply a “looks plausible but is unsound” witness that the verifier accepts.

Direct non-attenuated tokens omit attenuation_proof, so this check is a no-op for those tokens.

pub fn requires_chain_binding(&self) -> bool

Whether the token’s shape requires the chain-binding rule to fire.

Chain binding closes the P0 soundness gap where an issuer could mint an attenuated token claiming parent_scope = scope_BIGGER and supply an internally consistent witness. The rule binds attenuation_proof.parent_scope_hash to either the trust-root scope hash (direct issue) or delegation_chain.last().scope_hash (delegated chain). The rule is therefore meaningful only when the token actually introduces narrowing relative to its parent: an explicit attenuation_proof, non-empty scope_attenuations, or a budget_share_bps value that narrows the parent budget.

A non-empty delegation_chain by itself is NOT a trigger: each DelegationLink carries its own signature (DelegationLink.signature), the leaf token is signed by its issuer, and signature/connectivity invariants over the chain are enforced by [validate_delegation_chain]. A plain pass-through delegation that introduces no new attenuation has nothing to bind against the parent scope, so requiring attenuation_proof would render every plain delegated token unverifiable while adding no soundness.

pub fn validate_chain_binding_with_features( &self, trust_root_scope_hash: &String, negotiated: &CapabilityNegotiation, ) -> Result<(), Error>

pub fn sign( body: CapabilityTokenBody, keypair: &Keypair, ) -> Result<CapabilityToken, Error>

Sign a capability token body with the given Ed25519 keypair.

This is the bare Ed25519 signing entry point: the algorithm envelope field is omitted from the serialized output, so the artifact is byte-identical to one signed through the SigningBackend path with the default Ed25519 algorithm.

pub fn sign_aggregate_family_root( body: CapabilityTokenBody, max_invocations: u32, keypair: &Keypair, ) -> Result<CapabilityToken, Error>

Issue a direct delegation-family aggregate root with a CA-authenticated binding.

pub fn sign_cumulative_approval_family_root( body: CapabilityTokenBody, keypair: &Keypair, ) -> Result<CapabilityToken, Error>

Issue a direct cumulative-approval family root with CA-authenticated bindings.

pub fn sign_cumulative_approval_family_root_at_epoch( body: CapabilityTokenBody, signer_key_epoch: u64, keypair: &Keypair, ) -> Result<CapabilityToken, Error>

Issue a direct cumulative-approval family root at a named signer key epoch.

pub fn sign_attenuated( body: CapabilityTokenAttenuationBody, keypair: &Keypair, ) -> Result<CapabilityToken, Error>

Sign an attenuated capability token with caveats and an attenuation proof.

pub fn sign_with_backend( body: CapabilityTokenBody, backend: &dyn SigningBackend, ) -> Result<CapabilityToken, Error>

Sign a capability token body with an arbitrary SigningBackend.

Use this entry point to produce FIPS-algorithm (P-256 / P-384) tokens when operating under the fips feature. The body.issuer field must equal backend.public_key(); otherwise verification will fail.

The resulting token’s algorithm envelope field is populated with the backend’s algorithm. It is informational only – verification dispatches off the signature hex prefix, not this field.

pub fn sign_aggregate_family_root_with_backend( body: CapabilityTokenBody, max_invocations: u32, backend: &dyn SigningBackend, ) -> Result<CapabilityToken, Error>

Backend-agnostic direct delegation-family aggregate-root issuance.

pub fn sign_cumulative_approval_family_root_with_backend( body: CapabilityTokenBody, backend: &dyn SigningBackend, ) -> Result<CapabilityToken, Error>

Backend-agnostic cumulative-approval family-root issuance.

pub fn sign_cumulative_approval_family_root_with_backend_at_epoch( body: CapabilityTokenBody, signer_key_epoch: u64, backend: &dyn SigningBackend, ) -> Result<CapabilityToken, Error>

Backend-agnostic cumulative-approval family-root issuance at a key epoch.

pub fn verify_signature(&self) -> Result<bool, Error>

Verify the token’s signature against its issuer key.

Dispatches off the algorithm carried by signature and issuer. For FIPS algorithms, the fips feature must be enabled at the crate level or verification returns Ok(false).

pub fn verify_signature_with_floor( &self, floor: CapabilityCryptoFloor, ) -> Result<bool, CapabilityFloorVerifyError>

Verify the token’s signature and enforce the kernel-side crypto_floor posture in one pass.

Verification dispatches off Signature::algorithm():

• SigningAlgorithm::Hybrid tokens are accepted under CapabilityCryptoFloor::AllowHybrid and CapabilityCryptoFloor::PqRequired and rejected under CapabilityCryptoFloor::AllowClassical.
• Classical tokens (Ed25519 / P-256 / P-384) are accepted under CapabilityCryptoFloor::AllowClassical and CapabilityCryptoFloor::AllowHybrid and rejected under CapabilityCryptoFloor::PqRequired.

The floor check fires BEFORE the cryptographic verification step so a forged classical signature on a hybrid-only deployment cannot burn CPU cycles on a doomed verify call (and so the rejection path is explicit in the audit trail).

algorithm envelope-field consistency is also checked here: when the optional CapabilityToken::algorithm field is present, it MUST agree with Signature::algorithm(). A mismatch is a downgrade signal and is rejected fail-closed.

Errors

Returns CapabilityFloorVerifyError::RejectedByCryptoFloor when the signature algorithm violates the floor. CapabilityFloorVerifyError::AlgorithmMismatch when the envelope field disagrees with the signature material. CapabilityFloorVerifyError::Crypto when canonical re-serialization fails.

pub fn verify_signature_at(&self, now: u64) -> Result<bool, Error>

Verify the signature AND enforce the validity window in one pass.

This is the sanctioned entry point when a verifier also needs freshness: it fails closed on expiry / not-yet-valid tokens, which the bare CapabilityToken::verify_signature does not check. A clock is threaded explicitly via now (unix seconds) so there is no hidden wall-clock read in this pure check.

Ordering is deliberate and fail-closed: the cryptographic signature is checked FIRST. A token with an invalid (or forged) signature is rejected before the time window is consulted, so an attacker cannot use the error variant to distinguish “expired” from “never validly signed”.

Returns Ok(true) only when the signature verifies and now is within [issued_at, expires_at). Returns Ok(false) when the signature does not verify. Returns Error::CapabilityNotYetValid / Error::CapabilityExpired when the signature is valid but the token is outside its validity window.

pub fn verify_signature_with_floor_at( &self, floor: CapabilityCryptoFloor, now: u64, ) -> Result<bool, CapabilityFloorVerifyError>

Verify the signature, enforce the crypto_floor posture, AND enforce the validity window in one pass.

Equivalent to CapabilityToken::verify_signature_with_floor followed by CapabilityToken::validate_time, with the same fail-closed ordering: floor + signature are checked before the time window, so a floor violation or invalid signature is reported ahead of expiry. A clock is threaded explicitly via now (unix seconds).

Errors

Propagates every error of CapabilityToken::verify_signature_with_floor. When the signature and floor pass but the token is outside its validity window, the time error is surfaced as CapabilityFloorVerifyError::Crypto wrapping Error::CapabilityNotYetValid / Error::CapabilityExpired.

pub fn is_expired_at(&self, now: u64) -> bool

Check whether this token is expired at the given unix timestamp.

pub fn is_valid_at(&self, now: u64) -> bool

Check whether this token is valid at the given unix timestamp (issued_at <= now < expires_at).

pub fn validate_time(&self, now: u64) -> Result<(), Error>

Validate time bounds, returning an error on failure.

Trait Implementations

impl Clone for CapabilityToken

fn clone(&self) -> CapabilityToken

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CapabilityToken

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CapabilityToken

fn deserialize<__D>( __deserializer: __D, ) -> Result<CapabilityToken, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for CapabilityToken

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.