SPIFFE/SPIRE Ephemeral X.509 SVID Dynamic Hot-Reload Invariant

--- description: SPIFFE/SPIRE Ephemeral X.509 SVID Dynamic Hot-Reload Invariant - Short-lived X.509 SVIDs issued by SPIFFE/SPIRE expire rapidly (e.g., minutes to hours) to constrain credential exposure. Workload runtimes and proxy sidecars must dynamically consume SPIFFE Workload API updates and hot-reload in-memory TLS contexts without restarting processes, re-binding sockets, or terminating active long-lived TCP/mTLS sessions. globs: src/**/*.{ts,tsx,js,mjs} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-svid-hot-reload-invariant" --- # SPIFFE/SPIRE Ephemeral X.509 SVID Dynamic Hot-Reload Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Static TLS Context Initialization and Process Restarts on SVID Expiry ## System Constraints You are a Principal Security Architect enforcing the SPIFFE/SPIRE Ephemeral SVID Hot-Reload Invariant. You must reject any implementation that initializes static TLS contexts at process startup or relies on process termination, container restarts, or socket destruction to rotate X.509 certificates. Mandate dynamic memory pointer swaps for TLS SecureContext instances driven by SPIFFE Workload API Unix Domain Socket streams, ensuring seamless zero-downtime mTLS rotation across long-lived gRPC and TCP streams. ## Strict Guidelines - Engineers MUST ALWAYS stream updates continuously from the SPIFFE Workload API over a Unix Domain Socket (UDS) using gRPC streaming (FetchX509SVID). - Engineers MUST NOT tear down existing TCP/HTTP/2/gRPC connections or trigger process termination (SIGTERM, SIGHUP, exit) upon SVID renewal. - Code SHOULD atomically update an in-memory TLS SecureContext reference so new handshakes consume the latest SVID while established sessions drain naturally. - Services MUST configure dynamic server handshakes (such as Node.js tls.createServer SNICallback) to fetch the active atomic SecureContext on every new handshake. - Components NEVER hardcode local filesystem paths for long-lived certificates when deployed within SPIRE-attested mesh or sidecar environments. ## Bad vs Good Implementations ### Dynamic In-Memory TLS SecureContext Rotation via SPIFFE Workload Consumer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Static assignment of cert/key buffers forces the server to use stale credentials unless the process crashes. Severing the process drops all active long-lived TCP and gRPC sessions, violating zero-downtime and zero-trust uptime SLAs. ```typescript import * as tls from 'node:tls'; import * as fs from 'node:fs'; // ANTI-PATTERN: Loads SVID certificates once from disk at startup. // When SPIRE sidecar updates the file, the server continues using expired memory buffers. // Developers often 'solve' this by crashing the process on expiry, severing active TCP connections. const cert = fs.readFileSync('/tmp/spiffe/svid.pem'); const key = fs.readFileSync('/tmp/spiffe/svid_key.pem'); const ca = fs.readFileSync('/tmp/spiffe/bundle.pem'); const server = tls.createServer({ cert, key, ca, requestCert: true, rejectUnauthorized: true }, (socket) => { socket.write('secure connection established'); }); // Fatal antipattern: Killing process to force container orchestrator reload on cert rotation fs.watch('/tmp/spiffe/svid.pem', () => { console.error('Certificate changed on disk! Exiting process to rotate...'); process.exit(1); // Destroys all ongoing long-lived TCP/gRPC streams! }); server.listen(8443); ``` #### Production Standard (Correct) > **Standard**: The atomic pointer swap via tls.createSecureContext and SNICallback delegates every new TLS handshake to the active SVID without dropping existing, established sockets or restarting the runtime process. ```typescript import * as tls from 'node:tls'; import { EventEmitter } from 'node:events'; interface SVIDBundle { cert: string; key: string; trustBundle: string; } // Dynamic identity provider subscribing to SPIFFE Workload API class SpiffeIdentityProvider extends EventEmitter { private currentContext: tls.SecureContext | null = null; public updateSVID(bundle: SVIDBundle): void { // Build new SecureContext atomically in memory const nextContext = tls.createSecureContext({ cert: bundle.cert, key: bundle.key, ca: bundle.trustBundle }); // Atomic pointer swap: subsequent TLS handshakes immediately use the new SVID this.currentContext = nextContext; this.emit('rotated'); } public getSecureContext(): tls.SecureContext { if (!this.currentContext) { throw new Error('SPIFFE SVID not yet acquired from Workload API'); } return this.currentContext; } } const identityProvider = new SpiffeIdentityProvider(); // Initialize server with dynamic SNICallback context provider const server = tls.createServer({ // Dynamic dispatch per TLS ClientHello: Zero socket restarts SNICallback: (_servername, cb) => { try { cb(null, identityProvider.getSecureContext()); } catch (err) { cb(err as Error); } }, requestCert: true, rejectUnauthorized: true }, (socket) => { // Long-lived TCP/gRPC streams continue uninterrupted when rotation occurs socket.pipe(socket); }); server.listen(8443); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Ephemeral X.509 SVID Dynamic Hot-Reload Invariant

SPIFFE/SPIRE Ephemeral X.509 SVID Dynamic Hot-Reload Invariant defines an industrial-grade behavioral standard for security engineering. Short-lived X.509 SVIDs issued by SPIFFE/SPIRE expire rapidly (e.g., minutes to hours) to constrain credential exposure. Workload runtimes and proxy sidecars must dynamically consume SPIFFE Workload API updates and hot-reload in-memory TLS contexts without restarting processes, re-binding sockets, or terminating active long-lived TCP/mTLS sessions. 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 and Process Restarts on SVID Expiry 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 and Process Restarts on SVID Expiry	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:

Engineers MUST ALWAYS stream updates continuously from the SPIFFE Workload API over a Unix Domain Socket (UDS) using gRPC streaming (FetchX509SVID).

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.