SPIFFE/SPIRE Ephemeral SVID Rotation & In-Memory Reload Invariant

--- description: SPIFFE/SPIRE Ephemeral SVID Rotation & In-Memory Reload Invariant - Enforces sub-hour X.509 SVID lifecycles paired with non-blocking, atomic TLS configuration hot-reloads to eliminate connection stalls in zero-trust mesh architectures. Workloads must consume the SPIFFE Workload API stream and dynamically swap active TLS SecureContext instances in memory without dropping in-flight connections or requiring process restarts. Static certificate loading or blocking read/write locks during SVID rotation are strictly prohibited. globs: src/security/**/*.{ts,tsx,js}, src/transport/**/*.{ts,tsx,js}, src/network/**/*.{ts,tsx,js}, src/grpc/**/*.{ts,tsx,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-svid-rotation-atomic-reload" --- # SPIFFE/SPIRE Ephemeral SVID Rotation & In-Memory Reload Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Static TLS Context Initialization & Process Restart SVID Recycling ## System Constraints You are a Principal Security Architect enforcing the SPIFFE/SPIRE Ephemeral SVID Rotation & In-Memory Reload Invariant. You must mandate zero-downtime, in-memory atomic reloading of X.509 SVIDs with sub-hour TTLs (typically 10-60 minutes). Never permit static disk reads for SVID private keys, process restarts on rotation, or synchronization mechanisms that block concurrent TLS handshakes during credential renewal. ## Strict Guidelines - Workloads MUST subscribe to the SPIFFE Workload API streaming gRPC endpoint (or local Workload API client) to receive updated X509-SVIDs asynchronously. - Engineers MUST ALWAYS implement atomic, non-blocking secure context swapping (e.g., using dynamic SecureContext references or SNICallback hooks) when applying new SVID certificates and private keys. - Engineers MUST NOT persist ephemeral private keys or SVID bundles to local disk storage; all operations MUST be purely resident in memory or UNIX domain socket streams. - Services MUST gracefully drain or retain existing TLS sessions established under the previous SVID without forcibly severing established client connections upon certificate rotation. - Services MUST reject certificates with remaining lifecycles exceeding 3600 seconds unless an explicit architectural waiver for offline edge environments is attached. - Components NEVER acquire exclusive blocking mutexes across active TLS handshake paths during SVID updates; pointer swapping or immutable context replacement must be O(1) lock-free or read-copy-update semantics. ## Bad vs Good Implementations ### Static Certificate Initialization vs. Atomic In-Memory SecureContext Hot-Reload #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading short-lived SVIDs once at startup will cause TLS handshakes to fail completely as soon as the certificate expires (sub-hour TTL). Restarting the process to reload credentials causes TCP connection resets and introduces downtime across the mesh. ```typescript import * as https from 'node:https'; import * as fs from 'node:fs'; // ANTI-PATTERN: Loading SVID statically once at startup. // Ephemeral SVIDs (<60m TTL) will expire, throwing ERR_SSL_EXPIRED_CERTIFICATE // and requiring process death/restart to refresh credentials. const options: https.ServerOptions = { cert: fs.readFileSync('/var/run/secrets/spire/svid.crt'), key: fs.readFileSync('/var/run/secrets/spire/svid.key'), ca: fs.readFileSync('/var/run/secrets/spire/bundle.crt'), requestCert: true, rejectUnauthorized: true, }; export const server = https.createServer(options, (req, res) => { res.writeHead(200); res.end('OK'); }); server.listen(8443); ``` #### Production Standard (Correct) > **Standard**: Demonstrates an atomic reference update of `tls.SecureContext` via an asynchronous streaming client connected to the SPIFFE Workload API. New TLS handshakes immediately resolve to the freshly rotated SVID via `SNICallback` without blocking concurrent connections or restarting the service. ```typescript import * as https from 'node:https'; import * as tls from 'node:tls'; import { WorkloadApiClient, X509SVID } from '@spiffe/workload-api'; interface DynamicCertStore { currentContext: tls.SecureContext | null; } const certStore: DynamicCertStore = { currentContext: null }; // Production Invariant: Non-blocking SecureContext atomic pointer swap export function updateSecureContext(svid: X509SVID, trustBundle: Buffer): void { const newContext = tls.createSecureContext({ cert: svid.certBuffer, key: svid.privateKeyBuffer, ca: trustBundle, minVersion: 'TLSv1.3', }); // Atomic reference swap: in-flight handshakes finish without thread-blocking contention certStore.currentContext = newContext; } export const server = https.createServer({ SNICallback: (_servername, callback) => { if (!certStore.currentContext) { return callback(new Error('SPIRE SVID not yet acquired from Workload API'), undefined); } return callback(null, certStore.currentContext); }, requestCert: true, rejectUnauthorized: true, }); export async function initWorkloadWatcher(client: WorkloadApiClient): Promise<void> { const stream = await client.watchX509Context(); for await (const context of stream) { const svid = context.defaultSvid; const trustBundle = context.bundle; updateSecureContext(svid, trustBundle); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Ephemeral SVID Rotation & In-Memory Reload Invariant

SPIFFE/SPIRE Ephemeral SVID Rotation & In-Memory Reload Invariant defines an industrial-grade behavioral standard for security engineering. Enforces sub-hour X.509 SVID lifecycles paired with non-blocking, atomic TLS configuration hot-reloads to eliminate connection stalls in zero-trust mesh architectures. Workloads must consume the SPIFFE Workload API stream and dynamically swap active TLS SecureContext instances in memory without dropping in-flight connections or requiring process restarts. Static certificate loading or blocking read/write locks during SVID rotation are strictly prohibited. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Static TLS Context Initialization & Process Restart SVID Recycling Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Static TLS Context Initialization & Process Restart SVID Recycling	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Workloads MUST subscribe to the SPIFFE Workload API streaming gRPC endpoint (or local Workload API client) to receive updated X509-SVIDs asynchronously.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.