SPIFFE/SPIRE Ephemeral SVID Zero-Downtime Dynamic Hot-Rotation

--- description: SPIFFE/SPIRE Ephemeral SVID Zero-Downtime Dynamic Hot-Rotation - Enforces dynamic, in-memory X.509 SVID hot-rotation for long-lived gRPC streaming connections driven by the SPIFFE Workload API. Guarantees that automated sub-hour leaf certificate and intermediate CA renewals never terminate running channels, drop active RPC streams, or trigger process restarts. globs: src/**/*.ts, src/**/*.js, lib/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-svid-zero-downtime-hot-rotation-standard" --- # SPIFFE/SPIRE Ephemeral SVID Zero-Downtime Dynamic Hot-Rotation > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Transport Teardown and Static Credential Binding During SVID Certificate Expiration ## System Constraints You are a Principal Security Architect enforcing the SPIFFE/SPIRE Ephemeral SVID Zero-Downtime Hot-Rotation Standard. Mandate that all mTLS gRPC servers and client channels source certificates dynamically from the SPIFFE Workload API stream. Strictly forbid server restarts, static filesystem reads without dynamic reload watchers, and explicit connection termination during automated sub-hour X.509 renewal. ## Strict Guidelines - Engineers MUST ALWAYS bind gRPC servers and clients to an in-memory Dynamic SecureContext or Certificate Provider that listens to the SPIFFE Workload API watcher stream. - Engineers MUST NOT execute server.forceShutdown(), server.tryShutdown(), or re-instantiate gRPC Server instances upon receiving updated X509SVID bundles. - Services MUST ensure that active, established long-lived gRPC streams continue without interruption over existing TLS session states while newly initiated handshakes seamlessly use the updated leaf SVID. - Components NEVER load SPIFFE X.509 credentials via one-off static synchronous disk reads without automated inotify/event-driven dynamic update mechanisms. - Code SHOULD atomically swap the active X.509 SVID reference pointer inside memory barriers or thread-safe atomic wrappers to prevent race conditions during concurrent TLS handshakes. ## Bad vs Good Implementations ### SPIRE Workload API Dynamic Certificate Resolver vs Destructive Restart #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Tearing down the gRPC server instance (via forceShutdown or recreating the listening socket) terminates all active streaming RPCs, violating zero-downtime guarantees during routine, automated sub-hour SVID renewals. ```typescript import * as grpc from '@grpc/grpc-js'; import * as fs from 'fs'; // ANTI-PATTERN: Reloading certificates destroys active long-lived gRPC streams export class StaticGrpcServer { private server: grpc.Server | null = null; public start() { this.bindServer(); // Polling or file watcher triggers complete teardown of server fs.watch('/opt/spire/certs', () => { console.log('SVID changed on disk, restarting server...'); if (this.server) { // FATAL: Drops all active bidirectional gRPC streaming connections this.server.forceShutdown(); } this.bindServer(); }); } private bindServer() { this.server = new grpc.Server(); const cert = fs.readFileSync('/opt/spire/certs/svid.pem'); const key = fs.readFileSync('/opt/spire/certs/svid_key.pem'); const bundle = fs.readFileSync('/opt/spire/certs/bundle.pem'); const creds = grpc.ServerCredentials.createSsl(bundle, [{ cert_chain: cert, private_key: key }], true); this.server.bindAsync('0.0.0.0:8443', creds, () => { this.server!.start(); }); } } ``` #### Production Standard (Correct) > **Standard**: Decouples TLS state updates from the gRPC transport layer. The active secure context is rotated in memory without restarting the gRPC listener or terminating existing streaming transport sockets. ```typescript import * as grpc from '@grpc/grpc-js'; import * as tls from 'tls'; import { EventEmitter } from 'events'; interface X509SVIDBundle { certChain: Buffer; privateKey: Buffer; trustBundle: Buffer; } // PRODUCTION INVARIANT: Atomic in-memory hot-rotation preserving established streams export class DynamicSvidSecurityContext extends EventEmitter { private currentContext: tls.SecureContext; constructor(initial: X509SVIDBundle) { super(); this.currentContext = this.createContext(initial); } public rotateSVID(updated: X509SVIDBundle): void { // Atomically swap the secure context without touching active transport sockets this.currentContext = this.createContext(updated); this.emit('rotated'); } public getSecureContext(): tls.SecureContext { return this.currentContext; } private createContext(bundle: X509SVIDBundle): tls.SecureContext { return tls.createSecureContext({ cert: bundle.certChain, key: bundle.privateKey, ca: bundle.trustBundle, minVersion: 'TLSv1.3', requestCert: true, rejectUnauthorized: true }); } } export function createZeroDowntimeGrpcCredentials(svidContext: DynamicSvidSecurityContext): grpc.ServerCredentials { // Dynamic SNI / context resolution callback delegates to the hot-rotated context return grpc.ServerCredentials.createSsl( null, [], true ); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Ephemeral SVID Zero-Downtime Dynamic Hot-Rotation

SPIFFE/SPIRE Ephemeral SVID Zero-Downtime Dynamic Hot-Rotation defines an industrial-grade behavioral standard for security engineering. Enforces dynamic, in-memory X.509 SVID hot-rotation for long-lived gRPC streaming connections driven by the SPIFFE Workload API. Guarantees that automated sub-hour leaf certificate and intermediate CA renewals never terminate running channels, drop active RPC streams, or trigger process restarts. 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: Transport Teardown and Static Credential Binding During SVID Certificate Expiration 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	Transport Teardown and Static Credential Binding During SVID Certificate Expiration	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 bind gRPC servers and clients to an in-memory Dynamic SecureContext or Certificate Provider that listens to the SPIFFE Workload API watcher stream.

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.