firma-authority (root module)

Module: firma_authority

Contents

Modules

• authorized_clients - Allow-list of authorized mTLS client identities.
• cedar_loader
• config
• issuance - Pure capability-issuance helper shared by the gRPC service and the
• keygen - Ed25519 (PASETO v4) signing-key generation.
• profiles - Embedded policy profile registry.
• revocation
• seed - On-disk seed format produced by firma authority issue and consumed
• server
• service
• tls_verifier - mTLS allow-list client certificate verifier.

---

Module: authorized_clients

Allow-list of authorized mTLS client identities.

Loaded from a TOML file at Authority startup. Each entry names a CN or DNS SAN that a Sidecar client certificate must present for the TLS handshake to succeed. The set is read once at startup; restart the Authority to rotate the allow-list.

Module: cedar_loader

Module: config

Module: issuance

Pure capability-issuance helper shared by the gRPC service and the firma-authority issue CLI subcommand.

Encapsulates: Cedar policy evaluation, TTL clamping, context-hash computation, claim assembly, and PASETO signing. Stays free of any transport (tonic) or process-IO dependency so it is straightforward to call from a CLI in-process and to unit-test.

Module: keygen

Ed25519 (PASETO v4) signing-key generation.

Keeping the on-disk format in one place guarantees every producer writes exactly what [crate::server] reads back: raw PASETO v4 key bytes, secret at 0o600 and public at 0o644.

Module: profiles

Embedded policy profile registry.

Authority autostart materialises one of these into its per-run policy directory on first boot. Today only developer is registered; future profiles (read_only, balanced, strict, production_safe) plug into the same cedar_for dispatch.

Module: revocation

Module: seed

On-disk seed format produced by firma authority issue and consumed by the sidecar’s [sidecar.capability_seed] config block.

Mirrored by the sidecar-side reader at crates/firma-sidecar/src/config/capability_seed.rs::SeedFile. The two structs intentionally duplicate the schema to avoid an authority → sidecar (or vice versa) crate dependency cycle; keep them in lockstep when adding fields.

Module: server

Module: service

Module: tls_verifier

mTLS allow-list client certificate verifier.

Wraps WebPkiClientVerifier (standard chain validation) with a CN/SAN allow-list check. Clients whose certificate chain is invalid OR whose identity is not in the allow-list are rejected at the TLS handshake level — no gRPC frame is ever received from them.

Identity extraction

The identity checked against the allow-list is, in order of preference:

1. The first DNS SAN in the Subject Alternative Name extension.
2. The Common Name (CN) from the Subject Distinguished Name.

At least one of these must appear in the authorized-clients list for the handshake to succeed.