Rotating Secrets Engine

Service-to-service authentication does not rely on a static shared secret. The BE runs a RotatingSecretEngine (SDK secrets/rotating-secret.ts) that owns every s2s secret and rotates it on a timer.

The slot model

Each secret lives in Redis as a slot { current, previous, rotated_at }:

• Rotation: every rotationMs (default 60 min) a fresh secret replaces current; the old one becomes previous. The Redis key expires after rotationMs + graceMs.
• Grace window: for graceMs (default 5 min) after rotation, verifiers accept both current and previous (validClientShieldSecrets) — so an in-flight request signed just before rotation never fails.
• Broadcast: each rotation publishes the shielded secret.rotated event; consumers refresh their cached slot immediately instead of waiting for a miss.

Serving secrets — governed, allowlisted

Consumers fetch a secret over the NATS secret.get correlation route. The route is:

• publisher-verified — only registered services may call it
• allowlisted — SERVED_SECRETS in modules/secrets/secret-engine.ts declares exactly which (scope, name) refs exist; anything else is refused with an error log. A service can never fetch an arbitrary secret.

Currently served: service_client_shield_secret — the secret stamped on every s2s call (x-client-shield-secret header) and verified by the client-shield middleware on every inbound internal route.

Fallbacks and failure modes

• The config_entries row service_client_shield_secret (type secret, __ROTATED_BY_SECRET_ENGINE__ placeholder) is the static fallback only — it exists so the config loader can boot services before the engine's first rotation. It is never the production value.
• If Redis is unavailable the engine logs an explicit error and rotation simply does not happen — consumers keep accepting the last slot.
• The engine also keeps the BE's own outbound slot warm, so BE→US calls (proxy, NATS auth headers) always stamp current.

Why rotation matters

A leaked s2s secret expires within the hour by design — no deploy, no config change, no coordination. Combined with the allowlist and the publisher verifier, the blast radius of a compromised service identity is bounded to one rotation window.