SPIFFE/SPIRE Workload API X.509 SVID Zero-Downtime Memory-Only Rotation Invariant

--- description: SPIFFE/SPIRE Workload API X.509 SVID Zero-Downtime Memory-Only Rotation Invariant - Enforces lock-free, zero-downtime, memory-only rotation of X.509 SVIDs received via the SPIFFE Workload API stream. Precludes disk-snoop attacks by prohibiting disk persistence of ephemeral keys and prevents file-descriptor exhaustion and TLS handshake stalls by hot-swapping certificates via atomic reference pointers. globs: src/**/tls/**/*.{ts,js,go}, src/**/identity/**/*.{ts,js,go}, src/**/security/**/*.{ts,js,go}, src/**/transport/**/*.{ts,js,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-x509-svid-in-memory-atomic-rotation" --- # SPIFFE/SPIRE Workload API X.509 SVID Zero-Downtime Memory-Only Rotation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Persisting Ephemeral SVIDs to Disk or Restarting Listeners on Key Rotation ## System Constraints You are a Principal Security Architect enforcing the SPIFFE/SPIRE Workload API X.509 SVID Zero-Downtime Memory-Only Rotation Invariant. You must reject any code that writes SPIFFE private keys or certificates to storage media, restarts network listeners upon identity rotation, or creates race conditions during TLS renegotiation. Mandate atomic in-memory swapping using dynamic SNI/certificate selection hooks. ## Strict Guidelines - Services MUST consume X.509 SVIDs directly from the SPIFFE Workload API Unix Domain Socket (UDS) streaming connection. - Engineers MUST NEVER write SPIFFE X.509 SVID cryptographic material (private keys, leaf certs, intermediate bundles) to ephemeral or persistent block storage. - Services MUST implement zero-downtime hot-reloading using dynamic TLS context callbacks (e.g., tls.Config.GetCertificate in Go, SNICallback / dynamic SecureContext in Node.js) rather than tearing down and rebinding server sockets. - Components MUST store the active SecureContext or certificate state behind an atomically updated reference or lock-free pointer to eliminate handshake race conditions and file-descriptor churn. - Streams connecting to the Workload API MUST automatically reconnect with exponential backoff and jitter upon channel disruption without dropping active TLS listeners or terminating running processes. ## Bad vs Good Implementations ### Node.js TLS Server Dynamic SecureContext In-Memory Swap vs File Persistence #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Writing private keys to /tmp exposes ephemeral keys to unprivileged disk inspection and container file-system leaks. Destroying and recreating the TLS server on every rotation drops active in-flight handshakes and exhausts file descriptors. ```typescript import * as fs from 'fs'; import * as tls from 'tls'; import { SpiffeWorkloadClient } from './spiffe'; const client = new SpiffeWorkloadClient(); let server: tls.Server; client.on('x509-update', (svid) => { // ANTI-PATTERN: Dumping ephemeral private keys and certs to disk fs.writeFileSync('/tmp/svid.key', svid.privateKey); fs.writeFileSync('/tmp/svid.crt', svid.certificateChain); // ANTI-PATTERN: Tearing down active server socket, dropping active handshakes if (server) { server.close(); } server = tls.createServer({ key: fs.readFileSync('/tmp/svid.key'), cert: fs.readFileSync('/tmp/svid.crt'), }, (socket) => { socket.write('secure communication established'); }); server.listen(8443); }); ``` #### Production Standard (Correct) > **Standard**: Memory-only lifecycle management preserves security by never touching secondary storage. The SNICallback atomically retrieves the newest SecureContext reference on every incoming TLS handshake without interrupting existing connections or resetting the underlying socket. ```typescript import * as tls from 'tls'; import { SpiffeWorkloadClient, X509SVID } from './spiffe'; class AtomicTlsContextManager { private currentContext: tls.SecureContext; constructor(initialSvid: X509SVID) { this.currentContext = this.createContext(initialSvid); } public updateSvid(svid: X509SVID): void { // Atomic in-memory swap of SecureContext; zero disk I/O, zero socket resets this.currentContext = this.createContext(svid); } public getSecureContext(): tls.SecureContext { return this.currentContext; } private createContext(svid: X509SVID): tls.SecureContext { return tls.createSecureContext({ key: svid.privateKeyPem, cert: svid.certChainPem, ca: svid.bundlePem, minVersion: 'TLSv1.3' }); } } export async function bootstrapSecureServer(client: SpiffeWorkloadClient): Promise<tls.Server> { const initialSvid = await client.fetchX509SVID(); const contextManager = new AtomicTlsContextManager(initialSvid); const server = tls.createServer({ SNICallback: (_servername, cb) => { cb(null, contextManager.getSecureContext()); } }, (socket) => { socket.write('secure communication established'); }); // Continuously listen to Workload API stream in memory without restarts client.watchX509SVID((newSvid) => { contextManager.updateSvid(newSvid); }); return server.listen(8443); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Workload API X.509 SVID Zero-Downtime Memory-Only Rotation Invariant

SPIFFE/SPIRE Workload API X.509 SVID Zero-Downtime Memory-Only Rotation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces lock-free, zero-downtime, memory-only rotation of X.509 SVIDs received via the SPIFFE Workload API stream. Precludes disk-snoop attacks by prohibiting disk persistence of ephemeral keys and prevents file-descriptor exhaustion and TLS handshake stalls by hot-swapping certificates via atomic reference pointers. 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: Persisting Ephemeral SVIDs to Disk or Restarting Listeners on Key Rotation 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	Persisting Ephemeral SVIDs to Disk or Restarting Listeners on Key Rotation	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:

Services MUST consume X.509 SVIDs directly from the SPIFFE Workload API Unix Domain Socket (UDS) streaming connection.

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.