capability

Module: capability

Contents

Modules

• guard - Best-effort removal of the per-session capability seed file on drop.
• issue - Per-session live capability issuance for firma run.
• refresh - Background capability-token refresher for firma run.

Functions

• read_capability_token - Read the operator-supplied capability token for a firma run session.

---

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

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 [capability_seed].

firma_run::capability::read_capability_token

Function

Read the operator-supplied capability token for a firma run session.

Only [CapabilitySource::File] carries a bring-your-own token; the token is injected into the agent process environment once at launch (see build_execution_env). Rotation is delegated to the agent via the FIRMA_CAPABILITY_FILE env var, so this is a one-shot read with no background refresh — the firma-minted per-session path uses [refresh::CapabilityRefresher] instead.

Errors

Returns [RunError::Capability] when the file is unreadable or empty.

fn read_capability_token(source: &crate::config::CapabilitySource) -> Result<Option<String>, crate::error::RunError>

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.