local_exec

Module: local_exec

Contents

Modules

• endpoint - Local-exec governance UDS endpoint.
• handler - Local-exec governance request handler.
• token_store - Approval token state machine for HITL local-exec governance.

---

Module: endpoint

Local-exec governance UDS endpoint.

[LocalExecEndpoint::run] binds a Unix domain socket, accepts connections from firma-run clients and operator management tools, and dispatches each request through the [LocalExecHandler].

Protocol

One newline-terminated JSON object per connection (request then response). Requests are dispatched by the action field:

• "local.exec" — governance request from firma-run; responds with [LocalExecResponse].
• "local.exec.approve" / "local.exec.revoke" — management commands from an operator or the firma token CLI; responds with [LocalExecManagementResponse].

Security

On Linux the endpoint validates the peer UID via SO_PEERCRED before parsing the request. Connections from a different UID are rejected fail-closed with no response. On non-Linux Unix the credential check is omitted (the socket file’s filesystem permissions are the primary access control).

Lifecycle

The endpoint removes any stale socket file before binding and removes it again on shutdown (cancel signal). The background token-pruning task runs on the same cancellation token and shares the Arc<dyn TokenStore>.

Module: handler

Local-exec governance request handler.

[LocalExecHandler::decide] is the entry point for governance decisions:

• Fresh request (no approval_token): apply the configured [DefaultAction] and, when the action is PendingHitl, issue a new approval token in TokenState::Pending state bound to the request context.
• Retry with token (approval_token present): validate the token against the store. [TokenValidationResult::Valid] produces allow; [TokenValidationResult::Pending] produces pending_hitl (keep polling); every other state is a fail-closed deny.

[LocalExecHandler::decide_management] handles operator approval and revocation commands over the same UDS endpoint:

• local.exec.approve — transitions a Pending token to Approved, making it consumable by the next firma-run retry.
• local.exec.revoke — transitions a Pending or Approved token to Revoked, permanently blocking the corresponding execution.

All deny paths include a human-readable reason string so operators can diagnose why a launch was blocked.

Module: token_store

Approval token state machine for HITL local-exec governance.

The [TokenStore] trait defines the contract. Tokens go through:

Pending  → Approved   (operator explicitly approves via management API)
Pending  → Revoked    (operator explicitly revokes via management API)
Pending  → Expired    (TTL elapsed before operator decision)
Approved → Consumed   (single successful validate_and_consume call)
Approved → Expired    (TTL elapsed before firma-run retried after approval)

Every property listed in the architecture spec is enforced:

• Short-lived: tokens carry an absolute expiry.
• Single-use: the Consumed transition is atomic; a second call returns [TokenValidationResult::AlreadyConsumed].
• Server-side tracked: state lives in the store, never on the wire.
• Context-bound: each token is bound to the fingerprint, session_id, sandbox_id, and optionally agent_id that were present at issuance. Any mismatch returns [TokenValidationResult::ContextMismatch] or [TokenValidationResult::FingerprintMismatch].
• Operator-gated: Pending tokens return [TokenValidationResult::Pending] on retry until an operator explicitly approves them. Only [TokenState::Approved] tokens are consumable.

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