Skip to content

capability

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


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.

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.

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>

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.