Skip to content

firma-sidecar

firma_sidecar

Firma Sidecar — the enforcement layer between an agent and the outside world.

Every outbound agent call passes through the Sidecar. It is a single statically-linked binary with no persistent database; all state is in-memory and re-populated from Authority streams on restart.

Architecture

agent → interceptor → normalizer → Stage 1 → Stage 2 → connector → external

[interceptor] — Captures outbound agent traffic before it reaches the external system (HTTP proxy, gRPC hook, Unix socket).
[normalizer] — Intent Normalizer / Envelope Builder. Deterministically maps raw intercepted events into canonical ExecutionEnvelope instances with a normalized intent.action_class.
[enforcement] — Two-phase enforcement engine:
- Stage 1 (Capability Validation): token selection, parse, signature verify, expiry, revocation check.
- Stage 2 (Constraint Enforcement Engine / CEE): scope check, policy bundle freshness, Cedar policy evaluation.
[pipeline] — Orchestrates normalizer + both enforcement stages into a single enforce() entry point. This is the primary public API; all types needed to construct and inspect the pipeline are re-exported from here.
[audit] — Audit event emitter. Produces a signed event for every enforcement decision. Supports stdout, file, gRPC, and WAL output sinks.
[startup] — Per-subsystem builders that translate [config::SidecarConfig] into runtime components.

Modules

`firma_sidecar`

13 modules

`audit`

1 enum, 1 trait, 2 modules, 2 structs

`audit::builder`

1 enum, 1 struct

`audit::sink::file`

1 struct

`audit::sink::grpc`

1 struct

`audit::sink::stdout`

1 struct

`audit::sink::wal`

1 struct

`authority_client`

1 function, 2 structs, 6 modules

`authority_client::backoff`

1 struct

`authority_client::channel`

1 function

`authority_client::policy_bundle`

1 trait, 2 structs

`authority_client::readiness`

3 structs

`authority_client::revocation`

1 struct

`authority_client::swappable_policy`

1 struct

`config`

10 structs, 2 enums

`config::audit`

1 enum, 1 struct

`config::authority`

1 struct

`config::capability_seed`

2 structs

`config::connector`

2 structs

`config::enforcement`

6 structs

`config::revocation`

1 struct

`connector`

1 module

`connector::provider::http`

1 enum, 3 structs

`connector::registry`

1 struct

`credential`

1 enum, 1 module, 1 struct, 1 trait

`credential::provider::basic`

1 struct

`credential::provider::composite`

1 struct

`credential::provider::vault`

2 structs

`enforcement`

9 modules

`enforcement::capability_map`

2 structs

`enforcement::capability_validation`

2 structs

`enforcement::cedar_evaluator`

1 enum, 1 struct

`enforcement::constraint_enforcement`

1 struct, 1 trait

`enforcement::decision`

4 enums

`enforcement::error`

1 enum

`enforcement::registry`

1 enum, 2 structs

`enforcement::revocation`

2 structs

`enforcement::revocation::metrics`

1 struct

`enforcement::session_state`

1 trait, 2 structs

`handler`

2 structs, 5 enums, 5 functions

`health`

1 struct

`interceptor`

1 enum, 1 trait, 3 modules

`interceptor::grpc`

1 struct

`interceptor::http`

1 struct

`interceptor::unix_socket`

1 struct

`local_exec`

3 modules

`local_exec::endpoint`

1 struct

`local_exec::handler`

3 enums, 6 structs

`local_exec::token_store`

1 struct, 1 trait, 4 enums

`normalizer`

3 structs

`normalizer::mapping`

1 enum, 2 structs

`pipeline`

1 function, 2 structs

`startup`

10 modules

`startup::audit`

2 functions

`startup::authority`

1 function

`startup::capability`

3 functions

`startup::connector`

1 function

`startup::credential`

1 function

`startup::interceptor`

1 function, 1 struct

`startup::local_exec`

1 function

`startup::log_contract`

1 struct, 4 functions

`startup::pipeline`

1 function, 1 struct

`startup::preflight`

1 function, 1 struct