Module spiffe 

SPIFFE/SPIRE mTLS identity (DW-107).

Identity in the service mesh is provided by SPIFFE (Secure Production Identity Framework for Everyone) via SPIRE (the SPIFFE Runtime Environment). Each workload fetches X.509 SVIDs (SPIFFE Verifiable Identity Documents) from the SPIRE Workload API, exposed over a Unix domain socket. An X.509 SVID is an X.509 certificate whose URI SAN carries the workload’s SPIFFE ID (spiffe://<trust-domain>/<path>). The SPIFFE ID is the authentication identity used for policy decisions; the trust bundle (the SPIRE signing CAs) is used to verify peer SVIDs.

Implementation

The Workload API client is implemented behind a transport abstraction (WorkloadApiTransport) so the fetch logic is testable without a real SPIRE agent. The production transport (GrpcWorkloadApi) uses tonic over a Unix domain socket and is gated behind the ent cargo feature (which brings in tonic + prost; the mesh feature itself is flag-only). A FakeWorkloadApi is provided for tests.

Integration point

The mTLS TLS config in security::tls would consume the SVID certificate/key (as the presented client/server cert) and the trust bundle (as the peer-verification root store). The peer’s SPIFFE ID is extracted from the verified peer certificate’s URI SAN and used as the auth identity (the consumer / principal for policy decisions). This seam is documented here and kept as a hand-off (mesh produces the SVID material; security consumes it) so the dependency direction stays downward.

Structs

FakeWorkloadApi

A fake Workload API transport for tests. Returns preconfigured SVIDs and trust bundles without opening a socket. Deterministic (no real I/O, no timers).

SpiffeClient

The SPIFFE Workload API client: connects to the SPIRE agent over a Unix socket, fetches X.509 SVIDs for the workload, and refreshes them before expiry.

SpiffeConfig

The resolved SPIFFE configuration: the trust domain, the Workload API socket path, and the SVID refresh interval. Built from the config schema (MeshSpiffeConfig) at compile time.

SpiffeIdentity

A SPIFFE ID: the trust domain and the path that together form the workload identity (spiffe://<trust-domain>/<path>).

SpiffeSvid

An X.509 SVID: the certificate chain, the private key, and the expiry the workload presents to prove its SPIFFE identity.

SpiffeTrustBundle

The SPIFFE trust bundle: the X.509 root certificates (the SPIRE signing CAs) used to verify peer SVIDs. The bundle is fetched from the Workload API alongside the SVID and refreshed on the same schedule.

Enums

SpiffeError

Error returned by the SPIFFE Workload API calls.

SvidRefreshResult

The outcome of an SVID refresh attempt, captured for the dwara_spiffe_svid_refresh_total{result} metric. The CLOSED two-value label set: success when the Workload API returned a fresh SVID, error when the fetch failed (the client keeps serving the previous SVID until it expires).

Traits

WorkloadApiTransport

The transport abstraction for the SPIRE Workload API. The production implementation (GrpcWorkloadApi) uses tonic over a Unix domain socket (ent-gated); tests use FakeWorkloadApi.