SPIFFE/SPIRE Dynamic SVID Ephemeral Rotation and Connection Draining Invariant

--- description: SPIFFE/SPIRE Dynamic SVID Ephemeral Rotation and Connection Draining Invariant - Enforces zero-downtime mTLS identity rotation via SPIFFE Workload API by requiring dynamic TLS context swapping and non-destructive connection draining. Systems must hot-swap X509-SVIDs and trust bundles atomically without dropping in-flight multiplexed HTTP/2 or gRPC streams or closing active sockets. Abrupt listener recreation or synchronous socket drops during SVID updates violate zero-trust availability guarantees. globs: src/**/tls/**/*.{ts,js,go}, src/**/security/**/*.{ts,js,go}, src/**/network/**/*.{ts,js,go}, src/**/server/**/*.{ts,js,go}, src/**/spiffe/**/*.{ts,js,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-dynamic-svid-rotation-draining-standard" --- # SPIFFE/SPIRE Dynamic SVID Ephemeral Rotation and Connection Draining Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Hard Restart of Network Listeners or Abrupt Socket Termination on SPIFFE SVID Renewal ## System Constraints You are a Principal Security Architect enforcing the SPIFFE/SPIRE Dynamic SVID Ephemeral Rotation and Connection Draining Invariant. Mandate that all incoming and outgoing mTLS connections hot-swap X509-SVID certificates and trust bundles dynamically in memory without restarting listeners or dropping active sessions. Enforce HTTP/2 graceful draining via GOAWAY frames when sunsetting aged connections, ensuring in-flight RPCs are uninterrupted. ## Strict Guidelines - Engineers MUST ALWAYS reload X509-SVIDs and federated trust bundles dynamically in memory via atomic context swaps (e.g., dynamic SNICallback or tls.createSecureContext) without restarting the underlying network listener. - Engineers MUST NOT invoke server.close(), process restarts, or abruptly sever existing TCP/TLS sockets when a new SVID is issued by the SPIRE Workload API. - Services MUST handle multiplexed protocols (HTTP/2, gRPC) by issuing graceful GOAWAY frames with monotonic stream IDs when retiring connections near SVID expiration, permitting in-flight transactions to conclude. - Components NEVER execute blocking synchronous file reads or blocking cryptographic key parsing during runtime TLS handshake callbacks; pre-parsed contexts must be prepared asynchronously upon Workload API stream events. - Code SHOULD enforce minimum overlap grace periods between SVID updates and certificate expiration to guarantee rotation completes well before validity windows lapse. ## Bad vs Good Implementations ### Dynamic TLS SecureContext Swapping vs. Listener Recreation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Recreating the server or tearing down the TLS listener on certificate rotation abruptly terminates long-lived HTTP/2 streams, causes connection refused errors during socket re-binding, and breaks ephemeral SVID zero-downtime requirements. ```typescript import tls from 'tls'; import http2 from 'http2'; let server: http2.Http2SecureServer | null = null; // ANTI-PATTERN: Recreating the server listener on SPIFFE SVID rotation kills active connections and drops HTTP/2 streams export function onSvidRotated(newCert: string, newKey: string, trustBundle: string): void { if (server) { // Drops in-flight requests and abruptly closes established TCP sockets server.close(); } server = http2.createSecureServer({ cert: newCert, key: newKey, ca: trustBundle, requestCert: true, rejectUnauthorized: true }); server.listen(8443); } ``` #### Production Standard (Correct) > **Standard**: Uses `tls.createSecureContext` and `SNICallback` to atomically swap TLS credentials for new connections while leaving established sockets intact. Active HTTP/2 sessions receive non-destructive `GOAWAY` frames, permitting in-flight streams to complete naturally. ```typescript import tls from 'tls'; import http2 from 'http2'; interface SecureContextBundle { readonly context: tls.SecureContext; readonly serialNumber: string; readonly expiresAt: number; } class DynamicSpiffeTlsManager { private currentBundle: SecureContextBundle | null = null; private readonly server: http2.Http2SecureServer; constructor() { this.server = http2.createSecureServer({ // Invariant: Dynamically resolve secure context per handshake without dropping existing sockets SNICallback: (_servername, cb) => { if (!this.currentBundle) { return cb(new Error('SVID not initialized from Workload API'), undefined); } cb(null, this.currentBundle.context); }, requestCert: true, rejectUnauthorized: true }); } // Invariant: Hot-swap secure context atomically; drain existing HTTP/2 sessions gracefully public updateSvid(newCert: string, newKey: string, trustBundle: string, serial: string, expiresAt: number): void { const newContext = tls.createSecureContext({ cert: newCert, key: newKey, ca: trustBundle, minVersion: 'TLSv1.3' }); // Atomic pointer update for subsequent TLS handshakes this.currentBundle = { context: newContext, serialNumber: serial, expiresAt }; // Gracefully drain existing sessions without disrupting in-flight RPCs for (const session of this.server.sessions) { if (!session.destroyed && !session.closed) { session.goaway(http2.constants.NGHTTP2_NO_ERROR); } } } public listen(port: number): void { this.server.listen(port); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Dynamic SVID Ephemeral Rotation and Connection Draining Invariant

SPIFFE/SPIRE Dynamic SVID Ephemeral Rotation and Connection Draining Invariant defines an industrial-grade behavioral standard for security engineering. Enforces zero-downtime mTLS identity rotation via SPIFFE Workload API by requiring dynamic TLS context swapping and non-destructive connection draining. Systems must hot-swap X509-SVIDs and trust bundles atomically without dropping in-flight multiplexed HTTP/2 or gRPC streams or closing active sockets. Abrupt listener recreation or synchronous socket drops during SVID updates violate zero-trust availability guarantees. 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: Hard Restart of Network Listeners or Abrupt Socket Termination on SPIFFE SVID Renewal 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	Hard Restart of Network Listeners or Abrupt Socket Termination on SPIFFE SVID Renewal	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 reload X509-SVIDs and federated trust bundles dynamically in memory via atomic context swaps (e.g., dynamic SNICallback or tls.createSecureContext) without restarting the underlying network listener.

Engineers MUST ALWAYS reload X509-SVIDs and federated trust bundles dynamically in memory via atomic context swaps (e.g., dynamic SNICallback or tls.createSecureContext) without restarting the underlying network listener.

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.