Capability reference
Read a signed capability, find an exact field, and determine what the evaluator must enforce.
On this page
A capability token binds identity, authority, lifetime, and verification material in one signed object. The example below is the token from the repository-review example: one worker can read source and write a report, with a different path constraint for each operation. For the reasoning behind grants and delegation, read Capabilities.
Annotated capability
id cap-01a10d…650a91 issuer 8aa418fbf9…b67893 subject 052303e01f…08ef4f scope { repo / read_file invoke → repository/ repo / write_report invoke → reports/ } issued_at 1791232245 expires_at 1791232545 lineage directly issued schema chio.capability.v1 algorithm Ed25519 (implicit) signature d92e65ff08…a5bc0e
The issuer signed for one subject. The token ID names this grant of authority; it is distinct from the worker’s identity.
Each operation has its own path prefix. Neither grant permits delegation. Reading the source does not authorize writing there.
The token lasts 300 seconds. The start is inclusive; the expiry is exclusive. The delegation chain is omitted.
The signature binds the canonical signing body. Issuer trust, current validity, revocation, and request authorization still need checks.
Inspect and copy the complete captured token
{
"schema": "chio.capability.v1",
"id": "cap-01a10dc2-feb0-716a-84dd-610fc7650a91",
"issuer": "8aa418fbf98a79525bbf556ec481d76a609d974ac5cb16a812c5685ef9b67893",
"subject": "052303e01f511d7ecbc80ff56bc4838affaaca9d4a4d17723af48517ed08ef4f",
"scope": {
"grants": [
{
"server_id": "repo",
"tool_name": "read_file",
"operations": [
"invoke"
],
"constraints": [
{
"type": "path_prefix",
"value": "repository/"
}
]
},
{
"server_id": "repo",
"tool_name": "write_report",
"operations": [
"invoke"
],
"constraints": [
{
"type": "path_prefix",
"value": "reports/"
}
]
}
]
},
"issued_at": 1791232245,
"expires_at": 1791232545,
"signature": "d92e65ff081ceaec9f31d82a613de7304958f2963b8a1aef3728ee768937b3751179a70616da32a11642203557ee35b7b31ffef9a6e4accd3094c39a6fa5bc0e"
}The reading view groups related fields, but the signature binds one canonical object. Changing a path, subject, or expiry is an authority change. Editing the JSON does not create a valid replacement token.
Try expires_at, path_prefix, or DPoP. Each entry has its own link.
Token fields
Types below are the Rust types. Required means the serialized field must be present. Defaulted and optional fields may be absent; their omission does not skip the corresponding validation when they are used.
schema
Identifies the signed-artifact format. Omission deserializes as chio.capability.v1; an unsupported schema does not gain the default schema’s verification semantics.
Example"chio.capability.v1"
id
Identifies this token for revocation, lineage, and accounting. It is distinct from the subject key and from the IDs of requests made under the token.
Examplecap-01a10dc2-feb0-716a-84dd-610fc7650a91
issuer
The authority that signed the token. Verifying its signature does not by itself establish that this issuer is trusted by the receiving kernel.
Example8aa418fbf98a79525bbf556ec481d76a609d974ac5cb16a812c5685ef9b67893
subject
The agent key to which this authority is bound. Request evaluation checks the caller’s identity against it. A required DPoP proof separately establishes possession of the corresponding private key.
Example052303e01f511d7ecbc80ff56bc4838affaaca9d4a4d17723af48517ed08ef4f
scope
Contains grants, resource_grants, and prompt_grants. Each list defaults to empty and is omitted when empty. A present scope with no applicable grant cannot authorize an invocation.
Examplegrants[1] → repo / write_report / invoke / reports/
issued_at
Start of the validity window, as Unix seconds. A verifier supplied with a time before this value rejects the token because its validity window has yet to open.
Example1791232245
expires_at
Exclusive end of the validity window, as Unix seconds. Equality is already expired: a token is time-valid only when issued_at ≤ now < expires_at.
Example1791232545
delegation_chain
Ordered signed links describing delegated authority. An empty list is omitted. Accepted chain shapes, parent bindings, and scope witnesses depend on the selected delegation verifier.
ExampleOmitted in the directly issued repository-review token
aggregate_invocation_budget
Carries an invocation ceiling for a capability or delegation family. Family bindings and runtime accounting are required; merely copying this field does not establish a shared counter.
ExampleOmitted in the repository-review token; no aggregate invocation ceiling
algorithm
Declares the signing algorithm. The verifier checks consistency with the signature’s encoded algorithm and the configured cryptographic floor. The default label is omitted on serialization.
ExampleOmitted in the Ed25519 repository-review token
caveats
Typed caveat material included in the schema-aware signing body. A representable caveat is not proof that every evaluation path enforces its predicate.
ExampleOmitted when empty
scope_attenuations
High-level reductions carried by an attenuated token. They must agree with the token and its proof; they are not unsigned instructions that a caller may edit.
ExampleOmitted when absent or empty
attenuation_proof
Evidence supporting the child’s scope reduction. A subset witness and evidence of genuine parent authority answer separate questions.
ExampleOmitted in a directly issued token
budget_share_bps
A delegated share in basis points. Values above 10000 fail validation. Checking sibling allocations requires the relevant registry; the field alone cannot prevent sibling over-allocation.
Example2500 = a 25% share
Compare a proposed share with the parent’s remaining capacity.
signature
Signature over the canonical signing body. Use the library’s verifier rather than signing the displayed JSON text, whose whitespace and field ordering are presentation choices.
Exampled92e65ff081ceaec9f31d82a613de7304958f2963b8a1aef3728ee768937b3751179a70616da32a11642203557ee35b7b31ffef9a6e4accd3094c39a6fa5bc0e
The last valid second
For the captured token, the two neighboring times below have different results even though they differ by only one second. Other checks must still pass.
now = 1791232544Within the time windownow = 1791232545ExpiredInspect the complete Rust token type
pub struct CapabilityToken {
/// Versioned signed-artifact schema. Wire schema identifier; tokens that
/// omit this field default to `chio.capability.v1`.
#[serde(default = "default_capability_schema")]
pub schema: String,
/// Unique token ID (UUIDv7 recommended, used for revocation).
pub id: String,
/// Capability Authority (or delegating agent) that issued this token.
pub issuer: PublicKey,
/// Agent this capability is bound to (DPoP sender constraint).
pub subject: PublicKey,
/// What this token authorizes.
pub scope: ChioScope,
/// Unix timestamp (seconds) when the token was issued.
pub issued_at: u64,
/// Unix timestamp (seconds) when the token expires.
pub expires_at: u64,
/// Ordered list of delegation links from the root CA to this token.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub delegation_chain: Vec<DelegationLink>,
/// Optional invocation ceiling shared by this capability or its delegation family.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub aggregate_invocation_budget: Option<AggregateInvocationBudget>,
/// Signing algorithm. Absent means Ed25519 (the default).
#[serde(default, skip_serializing_if = "is_default_optional_algorithm")]
pub algorithm: Option<SigningAlgorithm>,
/// Typed caveats. Empty tokens omit this on the wire.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub caveats: Vec<Caveat>,
/// High-level attenuation request exposed on attenuated tokens.
#[serde(default, skip_serializing_if = "is_none_or_empty")]
pub scope_attenuations: Option<Vec<Attenuation>>,
/// Wire witness proving child-scope attenuation.
#[serde(default, skip_serializing_if = "is_none_or_empty_attenuation_proof")]
pub attenuation_proof: Option<AttenuationProof>,
/// Fixed-point sub-agent budget share in basis points. Values above
/// 10000 are rejected by validation.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub budget_share_bps: Option<u16>,
/// Signature over canonical JSON of all fields above.
pub signature: Signature,
}Scope and grant fields
ChioScope separates tool, resource, and prompt grants. A runtime must support the requested operation and its constraints. The portable tool-call evaluator matches the grants list; the other lists do not silently become tool permissions.
ToolGrant
A grant joins a target, permitted operations, and conditions on their use. A matching target is only the start of authorization.
server_idString · required- The registered server. Exact name or whole-field
*. Example:workspace. tool_nameString · required- The operation on that server. Exact name or whole-field
*;read_*is not a partial glob. Example:read_file. operationsVec<Operation> · required- The rights permitted on the target.
["invoke"]permits invocation without delegation. constraintsVec<Constraint> · default empty- Conditions that must hold. The repository-review example’s write grant contains
path_prefix: reports/. Each selected constraint needs a supported enforcement path. max_invocationsOption<u32> · optional- Invocation ceiling for this grant. Example:
3. Enforcement requires runtime accounting; a stateless signature check cannot count calls. max_cost_per_invocationOption<MonetaryAmount> · optional- Per-invocation monetary ceiling. Amounts carry integer minor units and a currency, such as
{"units": 100, "currency": "USD"}. max_total_costOption<MonetaryAmount> · optional- Total monetary ceiling. Example:
{"units": 500, "currency": "USD"}. Requires the relevant budget accounting path. dpop_requiredOption<bool> · optionaltruerequires a supported proof of possession for each request. Absent or false does not require DPoP at this grant.
ResourceGrant
uri_pattern: String and operations: Vec<Operation> are required. Coverage accepts exact equality, a whole *, or a trailing-prefix wildcard. Prefix coverage is textual: file:///workspace* also covers file:///workspace-archive. It is not filesystem path containment.
PromptGrant
prompt_name: String and operations: Vec<Operation> are required. Prompt names use the resource/prompt pattern-coverage relation. That does not broaden the separate tool-name matcher.
Operation rights
pub enum Operation {
/// Invoke the tool (execute it).
Invoke,
/// Read the result of a previous invocation.
ReadResult,
/// Read a resource.
Read,
/// Subscribe to resource updates.
Subscribe,
/// Retrieve a prompt.
Get,
/// Delegate this grant to another agent.
Delegate,
}Invocation requires Invoke on a matching grant. Delegation requires Delegate on the parent grant covering the authority being passed on. A delegation right on another target does not authorize forwarding this grant.
Constraints, by the question they answer
Each constraint has a snake-case wire tag and, when needed, a payload. The catalog contains 27 variants. “Portable matcher” means that path can evaluate the constraint. “Requires a dedicated runtime path” means the portable matcher refuses it; the type’s existence alone is not a support claim.
Where may it operate?
Restrict paths, network targets, audiences, and memory stores.
path_prefix PathPrefix
Portable matcher
File path parameter must start with this prefix.
- Payload
String- Enforcement
- Portable matching examines path-like string arguments. The adapter still owns filesystem resolution and containment; this check does not resolve symlinks.
domain_exact DomainExact
Portable matcher
Network domain must match exactly.
- Payload
String- Enforcement
- Uses the portable domain matcher. Pair request matching with an egress boundary if the adapter can choose destinations independently.
domain_glob DomainGlob
Portable matcher
Network domain must match a glob pattern.
- Payload
String- Enforcement
- Uses domain-pattern matching. This does not change server_id or tool_name matching, which permits only exact names or a whole-field wildcard.
audience_allowlist AudienceAllowlist
Portable matcher
Communication: allowed recipient channels or IDs.
- Payload
Vec<String>- Enforcement
- Evaluated during portable request matching. It remains one check within the complete authorization path.
memory_store_allowlist MemoryStoreAllowlist
Portable matcher
Memory governance: memory stores the grant may write to.
- Payload
Vec<String>- Enforcement
- Evaluated during portable request matching. It remains one check within the complete authorization path.
What input may it accept?
Bound argument size or values. Matching behavior is specific to each constraint.
max_length MaxLength
Portable matcher
String parameter must not exceed this length.
- Payload
usize- Enforcement
- Evaluated during portable request matching. It remains one check within the complete authorization path.
max_args_size MaxArgsSize
Portable matcher
Serialized argument payload must not exceed this many bytes.
- Payload
usize- Enforcement
- Evaluated during portable request matching. It remains one check within the complete authorization path.
regex_match RegexMatch
Requires a dedicated runtime path
Parameter must match a regular expression.
- Payload
String- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
custom Custom
Portable matcher
Extensibility: arbitrary key-value constraint.
- Payload
String, String- Enforcement
- Compares a named request argument with an expected string. It is not a hook that automatically implements an arbitrary policy extension.
What data or output may it use?
Constrain data access, model use, memory writes, and expected output evidence.
table_allowlist TableAllowlist
Requires a dedicated runtime path
Data layer: database tables the grant may reference. Evaluated against parsed SQL by `chio-data-guards`; the kernel records the constraint and leaves enforcement to that guard.
- Payload
Vec<String>- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
column_denylist ColumnDenylist
Requires a dedicated runtime path
Data layer: forbidden columns, formatted as `"table.column"`. Evaluated by `chio-data-guards`; kernel treats it as an advisory constraint and does not reject at the request-matching stage.
- Payload
Vec<String>- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
max_rows_returned MaxRowsReturned
Requires a dedicated runtime path
Data layer: maximum number of rows a query may return. Enforced post-invocation by downstream result-shaping guards.
- Payload
u64- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
operation_class OperationClass
Requires a dedicated runtime path
Data layer: operation class the grant authorises.
- Payload
SqlOperationClass- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
content_review_tier ContentReviewTier
Requires a dedicated runtime path
Communication: content review tier demanded of downstream guards.
- Payload
ContentReviewTier- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
model_constraint ModelConstraint
Requires a dedicated runtime path
Model routing: constrain the models this grant may execute under.
- Payload
{ allowed_model_ids: Vec<String>, min_safety_tier: Option<ModelSafetyTier> }- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
memory_write_deny_patterns MemoryWriteDenyPatterns
Requires a dedicated runtime path
Memory governance: regex patterns that block writes. Patterns are compiled lazily during kernel evaluation so invalid regexes do not break construction or round-trip serialization.
- Payload
Vec<String>- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
output_digest_sha256 OutputDigestSha256
Requires a dedicated runtime path
Delivery: an Allow for this grant is valid only if the final post-transform output content hash equals this expected digest, otherwise the request is denied before any irreversible money movement. The value is a canonical lowercase 64-character hex SHA-256 digest. Unlike the argument-side constraints above, this is enforced at the output-aware durable terminal, not at request matching; the request matcher only admits the carrier. Every surface that cannot prove the output-aware terminal ordering rejects the constraint before it mutates budget or payment.
- Payload
String- Enforcement
- Requires the dedicated output-digest authority path. A similarly named Custom key cannot substitute for it.
Which approval or assurance is required?
Bind governed work to transaction context, approval, spend, and assurance requirements.
governed_intent_required GovernedIntentRequired
Requires a dedicated runtime path
Requests must carry a governed transaction intent.
- Payload
No payload- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
require_approval_above RequireApprovalAbove
Requires a dedicated runtime path
Requests at or above this threshold require a valid approval token.
- Payload
{ threshold_units: u64 }- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
require_cumulative_approval_above RequireCumulativeApprovalAbove
Requires a dedicated runtime path
Cumulative authorized spend at or above this threshold requires approval.
- Payload
{ threshold: MonetaryAmount, approval_budget_id: String, approval_budget_epoch: u64, cumulative_approval_root_binding: Option<Box<CumulativeApprovalRootBinding>> }- Enforcement
- Needs cumulative spend state and the required root, epoch, currency, and approval bindings. Its delegation subset rule is more specific than ordinary constraint equality.
seller_exact SellerExact
Requires a dedicated runtime path
Requests must carry commerce approval context for this exact seller.
- Payload
String- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
minimum_runtime_assurance MinimumRuntimeAssurance
Requires a dedicated runtime path
Governed requests must carry valid runtime attestation at or above this tier.
- Payload
RuntimeAssuranceTier- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
minimum_autonomy_tier MinimumAutonomyTier
Requires a dedicated runtime path
Governed requests at or above this autonomy tier must carry autonomy context and pass bond gating.
- Payload
GovernedAutonomyTier- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
max_transaction_amount_usd MaxTransactionAmountUsd
Requires a dedicated runtime path
Financial: maximum transaction amount in USD. The value is a decimal string (e.g. `"100.00"`) because `rust_decimal` is not in the workspace.
- Payload
String- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
require_dual_approval RequireDualApproval
Requires a dedicated runtime path
Financial: whether the grant requires dual approval before execution.
- Payload
bool- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
What purchase or recovery evidence is required?
Bind finding delivery and recovery to the dedicated authority path.
require_finding_purchase RequireFindingPurchase
Requires a dedicated runtime path
Delivery: this grant authorizes exactly one purchased finding reveal. The provider-signed marker names the exact finding and listing being sold and closes over the settlement rail, so omitted purchase context can never downgrade into a generic digest-constrained call. Admission requires the request to name the same finding, a verified purchase context, and the settlement profile the selector admits. Surfaces without purchase-aware admission reject the marker before any budget or payment mutation.
- Payload
Box<FindingPurchaseMarkerV1>- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
require_finding_recovery RequireFindingRecovery
Requires a dedicated runtime path
Delivery: this grant authorizes a bounded no-charge redelivery of a finding whose paid delivery was already settled. Recovery is a distinct authorization profile: it never satisfies a purchase marker and never enters a payment path. Admission requires the dedicated recovery carrier named by this marker and an exact top-level `finding_id` argument. Surfaces without recovery-aware admission reject the marker before dispatch.
- Payload
Box<FindingRecoveryMarkerV1>- Enforcement
- Refused by portable request matching. Use an evaluator with explicit support for this variant and its required context or state.
A network grant with explicit limits
This serialized grant permits http_get on srv-net, with an invocation ceiling and input constraints. The network domain, length, and argument-size restrictions travel with the grant:
{
"server_id": "srv-net",
"tool_name": "http_get",
"operations": [
"invoke",
"read_result"
],
"max_invocations": 50,
"constraints": [
{
"type": "domain_glob",
"value": "*.chio-protocol.dev"
},
{
"type": "max_length",
"value": 1024
},
{
"type": "max_args_size",
"value": 4096
},
{
"type": "custom",
"value": [
"rate_limit",
"10/min"
]
}
]
}The custom entry names a rate-limit extension; the host must provide its evaluator. This is a serialization example from the public binding vectors, not a live credential.
Complete signed capability
{
"expires_at": 1710000800,
"id": "cap-bindings-complex-constraints",
"issued_at": 1710000200,
"issuer": "66be7e332c7a453332bd9d0a7f7db055f5c5ef1a06ada66d98b39fb6810c473a",
"scope": {
"grants": [
{
"constraints": [
{
"type": "domain_glob",
"value": "*.chio-protocol.dev"
},
{
"type": "max_length",
"value": 1024
},
{
"type": "max_args_size",
"value": 4096
},
{
"type": "custom",
"value": [
"rate_limit",
"10/min"
]
}
],
"max_invocations": 50,
"operations": [
"invoke",
"read_result"
],
"server_id": "srv-net",
"tool_name": "http_get"
}
]
},
"signature": "f07e2f37668b446180eefaf981bbc06ac380d9f716ff25a9e4236ee30a5b4f3b395dcf2fd2ee9fe31ea36aa612dea37b8a2e29789b6162ab713ae19b489d7901",
"subject": "0b513ad9b4924015ca0902ed079044d3ac5dbec2306f06948c10da8eb6e39f2d"
}Keep a parent constraint when narrowing a grant
Ordinary parent constraints must remain present unchanged in a delegated grant. Adding a narrower path condition can reduce authority. Replacing the original condition drops a required constraint, even if the new path appears narrower.
path_prefix: repository/path_prefix: repository/
path_prefix: repository/tests/This illustrates constraint preservation only. Delegation also requires the parent’s delegation right, valid signatures, appropriate parent bindings, and the supported lineage shape. Cumulative approval has a dedicated subset rule; see Delegation & Attenuation.
Reserved Custom keys
Custom performs a value comparison. Reserved authority keys must use their dedicated constraints. The portable matcher rejects these keys instead of treating them as generic comparisons or falling back to an unconstrained grant:
output_digest_sha256require_finding_purchaserequire_finding_recoveryrecovery_of_receipt_idrecovery_of_capability_id
Algorithms and cryptographic floors
The signing-algorithm enum names Ed25519, P-256, P-384, and hybrid signatures. Verification support depends on build features and the configured floor. P-256/P-384 verification requires the FIPS feature; hybrid verification requires its post-quantum implementation.
pub enum SigningAlgorithm {
/// Edwards-curve signature on Curve25519. Default, non-FIPS.
#[default]
Ed25519,
/// ECDSA on NIST P-256 / secp256r1 with SHA-256. Requires `fips` feature.
P256,
/// ECDSA on NIST P-384 / secp384r1 with SHA-384. Requires `fips` feature.
P384,
/// Classical signature plus ML-DSA-65. Requires `pq` feature.
Hybrid,
}AllowClassicalCapabilityCryptoFloor · default- Classical-only signatures; the default verifier floor.
AllowHybridCapabilityCryptoFloor- Classical-only or hybrid signatures.
PqRequiredCapabilityCryptoFloor- Hybrid signatures; classical-only tokens are rejected.
Floor-aware verification checks the declared algorithm against the encoded signature, rejects disallowed families, then performs schema and cryptographic verification. AllowHybrid permits hybrid; it does not require it. The bare signature-verification method has a narrower contract than the floor-aware capability verifier.
Delegation chains
Delegation links record the parent capability identifier, delegator, delegatee, declared reductions, timestamp, and optional scope binding. Scope witnesses demonstrate a subset relation; trusted roots and signed parent bindings establish the claimed parent authority. The runtime also checks stored lineage where required.
Inspect a signed delegation link
pub struct DelegationLink {
/// Capability ID of the ancestor token delegated at this step.
pub capability_id: String,
/// Public key of the agent that delegated.
pub delegator: PublicKey,
/// Public key of the agent that received the delegation.
pub delegatee: PublicKey,
/// How the scope was narrowed in this delegation step.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub attenuations: Vec<Attenuation>,
/// Unix timestamp of the delegation.
pub timestamp: u64,
/// Delegation chain-binding: SHA-256 hash of the canonical scope authorized
/// at this hop. Absent on older links; verifiers can enforce presence via
/// feature gate. Verifiers gated behind the `delegation_chain_binding`
/// feature flag enforce that this matches the parent_scope_hash carried by
/// the next hop.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub scope_hash: Option<ScopeHash>,
/// Authenticated preservation marker for a delegation-family invocation budget.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub aggregate_budget: Option<AggregateBudgetDelegationMarker>,
/// Authenticated preservation marker for cumulative approval root bindings.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub cumulative_approval: Option<CumulativeApprovalDelegationMarker>,
/// Ed25519 signature by the delegator over the canonical form of the
/// other fields in this link.
pub signature: Signature,
}The chain-binding verifier accepts the chain shapes that Delegation & Attenuation specifies, alongside the independent swarm-witness path, and rejects an attenuated multi-link token of any other shape. A vector of links alone establishes no particular shape.
Verification entry points
verify_capability checks issuer trust, schema/signature, the default crypto floor, applicable feature exclusions, and the supplied time window. It uses a no-op sibling registry. Richer verification entry points add configured floors, negotiated features, root evidence, and an enforcing registry.
Token verification does not match a specific request, query live revocation, verify a request's DPoP proof, or dispatch a tool. Portable evaluation adds subject/scope/guard checks against supplied context; hosted evaluation adds live admission and execution services. See Core & Shell.
Revocation state
A valid signature does not establish that authority remains active. The hosted runtime consults its revocation store for the token and its delegation ancestors before admitting the call. These are separate state reads, not one universal lookup or an immutable snapshot guarantee.
Inspect the revocation-store interface
pub trait RevocationStore: Send + Sync {
/// Check if a capability ID has been revoked.
fn is_revoked(&self, capability_id: &str) -> Result<bool, RevocationStoreError>;
/// Revoke a capability. Returns `true` if it was newly revoked.
fn revoke(&self, capability_id: &str) -> Result<bool, RevocationStoreError>;
fn observe_revocation(
&self,
capability_id: &str,
) -> Result<RevocationObservation, RevocationStoreError> {
Ok(RevocationObservation {
revoked: self.is_revoked(capability_id)?,
commit: None,
})
}
/// Whether this store loses its revocation set on process restart. The
/// default is the safe (loud) assumption so an unknown store is treated as
/// ephemeral; durable and remote stores override to `false`.
fn is_ephemeral(&self) -> bool {
true
}
}The in-memory store is ephemeral. Durable implementations, including SQLite-backed storage, report that they survive restart. The trait defaults is_ephemeral() to true, and configuration-driven kernels reject ephemeral revocation stores unless explicitly allowed. Returning false is a declaration of the implementation's contract, not a durability test.
Nodes pointed at the trust control plane with --control-url consult its revocation store uncached, and a failed lookup denies. Rotate Keys, Revoke covers the operator workflow.
Proof of possession
DPoP binds a per-request proof to the capability subject key. When a matching grant requires it, the hosted verifier checks the signed proof and replay state, so a copied token alone fails that requirement. A federated grant always requires the proof at the receiving kernel's door; see Proof of possession.
Some(true)dpop_required- Require the supported request proof. Delegation must preserve the requirement.
Some(false)orNonedpop_required- This grant does not require DPoP. Other transport or deployment authentication can still apply.
The proof schema is chio.dpop_proof.v1. Replay protection depends on the runtime's nonce store and scope; portable token verification alone does not provide it.
Worked example
The annotated token was issued by the repository-review example's host for its repository worker. The example project contains the complete issuance code, request construction, and receipt verification for an admitted and a refused write.