capability
Module: capability
Section titled “Module: capability”Contents
Section titled “Contents”Modules
guard- Best-effort removal of the per-session capability seed file on drop.issue- Per-session live capability issuance forfirma run.refresh- Background capability-token refresher forfirma run.
Functions
read_capability_token- Read the operator-supplied capability token for afirma runsession.
Module: guard
Section titled “Module: guard”Best-effort removal of the per-session capability seed file on drop.
The seed lives at $XDG_RUNTIME_DIR/firma/capabilities/<sandbox_id>.toml
and must not outlive the run that minted it.
Module: issue
Section titled “Module: issue”Per-session live capability issuance for firma run.
Calls the Authority’s IssueCapability RPC once per invocation, verifies
the returned token locally, and writes the resulting [CapabilitySeed] to
$XDG_RUNTIME_DIR/firma/capabilities/<sandbox_id>.toml. The sidecar then
loads it via [sidecar.capability_seed].
The request always names every action class ([REQUESTED_ACTIONS]); the
policy set applied to the agent decides which of them are granted. An
agent’s capabilities therefore follow its policies with no local edit.
firma_run::capability::read_capability_token
Section titled “firma_run::capability::read_capability_token”Function
Read the operator-supplied capability token for a firma run session.
Only [CapabilitySource::File] carries an operator-provided seed. Run parses
the canonical [firma_core::CapabilitySeed] TOML and injects only its
raw_token into the agent process environment (see build_execution_env).
This is a one-shot Run read with no Run-managed background refresh. A local
Sidecar independently reads and watches the same file; a pre-managed
external Sidecar owns its seed configuration. The Firma-minted per-session
path uses [refresh::CapabilityRefresher] instead.
Errors
Section titled “Errors”Returns [RunError::Capability] when the file is unreadable, is not a
canonical capability seed, or contains an empty raw_token.
fn read_capability_token(source: &crate::config::CapabilitySource) -> Result<Option<String>, crate::error::RunError>Module: refresh
Section titled “Module: refresh”Background capability-token refresher for firma run.
The per-session capability seed minted at startup carries a short TTL
(default 15 min, [super::issue::DEFAULT_TTL_SECONDS]). Without renewal the
sidecar’s Stage 1 validation begins denying every protected call once the
token expires, stalling long agent sessions.
[CapabilityRefresher] spawns a background thread that re-calls the
Authority’s IssueCapability RPC — reusing the same session identity and
credentials assembled at startup, so no interactive re-auth occurs — and
atomically rewrites the seed file before expiry. Picking the rewritten seed
up in a running sidecar requires the sidecar’s own capability-source
reload, which lands separately — it is not part of this crate. Without it the
refreshed token only benefits a sidecar (re)started after the rewrite.
Fail-closed: if the Authority is unreachable the refresher retries with capped backoff but never serves a stale token itself. While a refresh is outstanding the old token simply expires and the sidecar denies, exactly as it would without a refresher.