token_store

Module: local_exec::token_store

Contents

Structs

• InMemoryTokenStore - In-memory, mutex-protected approval token store.

Enums

• ApproveResult - Outcome of a [TokenStore::approve] call.
• RevokeResult - Outcome of a [TokenStore::revoke] call.
• TokenState
• TokenValidationResult - Outcome of a [TokenStore::validate_and_consume] call.

Traits

• TokenStore - Contract for an approval token store.

---

firma_sidecar::local_exec::token_store::ApproveResult

Enum

Outcome of a [TokenStore::approve] call.

Variants:

• Ok - Token transitioned to Approved (or was already Approved — idempotent).
• NotFound - Token ID not found.
• AlreadyConsumed - Token was already consumed before the approval arrived.
• AlreadyRevoked - Token was already revoked.
• Expired - Token expired before the approval arrived.

Traits: Eq, Copy

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &ApproveResult) -> bool
• Clone
  • fn clone(self: &Self) -> ApproveResult

firma_sidecar::local_exec::token_store::InMemoryTokenStore

Struct

In-memory, mutex-protected approval token store.

Tokens are identified by UUID v4 strings. All state transitions are atomic under the internal [Mutex]. There is no external database dependency.

Call [TokenStore::prune_expired] periodically (e.g., from a background task) to reclaim memory. Tokens are retained for a brief grace window after expiry so that the store can distinguish Expired from Unknown on a late retry.

Methods:

• fn new(ttl: Duration) -> Self - Create a new store. ttl is the lifetime of each issued token.
• fn issue(self: &Self, fingerprint: String, session_id: String, sandbox_id: String, agent_id: Option<String>) -> String - Issue a new approval token in [TokenState::Pending] state.
• fn validate_and_consume(self: &Self, token_id: &str, fingerprint: &str, session_id: &str, sandbox_id: &str, agent_id: Option<&str>) -> TokenValidationResult - Validate and atomically consume a token.
• fn approve(self: &Self, token_id: &str) -> ApproveResult - Approve a pending token, making it consumable by firma-run.
• fn revoke(self: &Self, token_id: &str) -> RevokeResult - Revoke a pending or approved token, preventing any future consumption.
• fn prune_expired(self: &Self) - Remove records that are past their expiry grace window.

Trait Implementations:

• TokenStore
  • fn issue(self: &Self, fingerprint: String, session_id: String, sandbox_id: String, agent_id: Option<String>) -> String
  • fn validate_and_consume(self: &Self, token_id: &str, fingerprint: &str, session_id: &str, sandbox_id: &str, agent_id: Option<&str>) -> TokenValidationResult
  • fn approve(self: &Self, token_id: &str) -> ApproveResult
  • fn revoke(self: &Self, token_id: &str) -> RevokeResult
  • fn prune_expired(self: &Self)

firma_sidecar::local_exec::token_store::RevokeResult

Enum

Outcome of a [TokenStore::revoke] call.

Variants:

• Ok - Token transitioned to Revoked (or was already Revoked — idempotent).
• NotFound - Token ID not found.
• AlreadyConsumed - Token was already consumed; revocation has no further effect.
• Expired - Token already expired.

Traits: Eq, Copy

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &RevokeResult) -> bool
• Clone
  • fn clone(self: &Self) -> RevokeResult

firma_sidecar::local_exec::token_store::TokenState

Enum

Variants:

• Pending - Issued and awaiting operator approval — not yet consumable by firma-run.
• Approved - Operator approved; ready for a single consumption by firma-run.
• Consumed - Successfully consumed by a validate_and_consume call. Terminal.
• Expired - TTL elapsed before consumption. Terminal.
• Revoked - Explicitly revoked by an operator before consumption. Terminal.

Traits: Copy, Eq

Trait Implementations:

• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &TokenState) -> bool
• Clone
  • fn clone(self: &Self) -> TokenState

firma_sidecar::local_exec::token_store::TokenStore

Trait

Contract for an approval token store.

Implementations must be Send + Sync so they can be shared behind an Arc across connection-handler tasks.

The default implementation is [InMemoryTokenStore]. Custom backends (Redis, distributed stores, test doubles) implement this trait and are passed to [super::handler::LocalExecHandler::with_store].

Methods:

• issue: Issue a new approval token in [TokenState::Pending] state and return
• validate_and_consume: Validate and atomically consume a token.
• approve: Approve a pending token, making it consumable by firma-run.
• revoke: Revoke a pending or approved token, preventing any future consumption.
• prune_expired: Remove records past their expiry grace window.

firma_sidecar::local_exec::token_store::TokenValidationResult

Enum

Outcome of a [TokenStore::validate_and_consume] call.

Variants:

• Valid - Token is approved, valid, and has been atomically consumed. Caller may proceed.
• Unknown - Token ID not found in the store (unknown or already pruned).
• Pending - Token exists but has not yet been approved by an operator. Caller should retry later.
• Expired - Token TTL elapsed before this call.
• AlreadyConsumed - Token was already consumed by a prior call (replay attempt).
• Revoked - Token was explicitly revoked by an operator.
• FingerprintMismatch - The request fingerprint does not match the one bound at issuance.
• ContextMismatch - session_id, sandbox_id, or agent_id do not match the bound values.

Traits: Eq, Copy

Trait Implementations:

• Clone
  • fn clone(self: &Self) -> TokenValidationResult
• Debug
  • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
• PartialEq
  • fn eq(self: &Self, other: &TokenValidationResult) -> bool