SPIFFE/SPIRE Dynamic X.509 SVID Sub-Hourly mTLS Rotation Invariant

--- description: SPIFFE/SPIRE Dynamic X.509 SVID Sub-Hourly mTLS Rotation Invariant - Enforces non-disruptive, dynamic rotation of short-lived SPIFFE X.509 SVIDs over sub-hourly TTL cycles via the SPIFFE Workload API. Mandates hot-swapping in-memory TLS SecureContext instances and trust bundles without terminating active TCP connections or restarting workload processes across heterogeneous cloud boundaries. globs: src/network/**/*.{ts,js}, src/security/**/*.{ts,js}, src/transport/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-x509-svid-mtls-zero-downtime-rotation" --- # SPIFFE/SPIRE Dynamic X.509 SVID Sub-Hourly mTLS Rotation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Static Disk-Loaded Certificates or Process Restarts on SVID Expiration Leading to Connection Drops ## System Constraints You are a Principal Engineer enforcing SPIFFE/SPIRE Workload Identity Automated X.509 SVID mTLS Handshake Invariant. Mandate that all TLS server and client connections use the SPIFFE Workload API Unix Domain Socket to stream short-lived X.509 SVIDs and federated trust bundles. Workload identities must be rotated in-memory with sub-hourly cadences without dropping active TCP connections or requiring process restarts. Disallow reading static PEM files from disk at boot and disallow any TLS configuration that requires a server restart upon certificate renewal. ## Strict Guidelines - Engineers MUST ALWAYS integrate with the SPIFFE Workload API via Unix Domain Socket (UDS) to stream X.509 SVIDs and federated trust bundles dynamically. - Engineers MUST NOT cache TLS SecureContext instances statically or load X.509 certificates as immutable startup-only files. - Services MUST atomically swap in-memory TLS SecureContext references on Workload API rotation events so that active TCP sessions persist unaffected while new handshakes immediately negotiate with the latest SVID. - Code SHOULD validate the peer's SPIFFE ID explicitly during the mTLS handshake callback against an authoritative URI SAN whitelist or trust domain policy. - Components NEVER terminate the process, cycle worker pools, or tear down listening TCP sockets to apply renewed X.509 SVID certificates. ## Bad vs Good Implementations ### Dynamic SPIFFE SVID In-Memory Context Hot-Swapping vs. Static Cert Initialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading certificates synchronously from disk binds the TLS server to an immutable context. When SPIRE updates short-lived SVIDs on disk or via agent sockets, the server cannot detect the changes without restarting, causing connection aborts and production outages during sub-hourly rotations. ```typescript import * as tls from 'node:tls'; import * as fs from 'node:fs'; // Anti-pattern: Static certificate load at boot. Rotation requires process restart, // dropping all active multicloud TCP streams when sub-hourly SVIDs expire. const staticOptions: tls.TlsOptions = { key: fs.readFileSync('/var/run/secrets/tls.key'), cert: fs.readFileSync('/var/run/secrets/tls.crt'), ca: fs.readFileSync('/var/run/secrets/trust_bundle.crt'), requestCert: true, rejectUnauthorized: true, }; export const server = tls.createServer(staticOptions, (socket) => { socket.write('Secure session established'); }); server.listen(8443); ``` #### Production Standard (Correct) > **Standard**: Uses dynamic TLS context swapping via SNICallback backed by the SPIFFE Workload API stream. New connections negotiate using the freshest sub-hourly SVID, existing TCP streams remain connected without disruption, and peer SPIFFE IDs are strictly validated via URI SAN inspection. ```typescript import * as tls from 'node:tls'; import { EventEmitter } from 'node:events'; interface SpiffeSvidUpdate { svidCertPem: string; privateKeyPem: string; federatedBundlePem: string; expectedSpiffeId: string; } export class DynamicSpiffeTlsManager extends EventEmitter { private currentContext: tls.SecureContext | null = null; private allowedSpiffeId: string; constructor(allowedSpiffeId: string) { super(); this.allowedSpiffeId = allowedSpiffeId; } public updateSvid(update: SpiffeSvidUpdate): void { // Create an atomic new SecureContext without affecting active sockets this.currentContext = tls.createSecureContext({ cert: update.svidCertPem, key: update.privateKeyPem, ca: update.federatedBundlePem, minVersion: 'TLSv1.3', }); this.emit('rotated'); } public createServer(): tls.Server { return tls.createServer({ requestCert: true, rejectUnauthorized: true, SNICallback: (_servername, cb) => { if (!this.currentContext) { return cb(new Error('SPIFFE SVID context uninitialized'), undefined); } return cb(null, this.currentContext); }, checkServerIdentity: (_host, cert) => { const sanUri = cert.subjectaltname ?.split(',') .map(s => s.trim()) .find(s => s.startsWith('URI:spiffe://')); if (!sanUri || sanUri.replace('URI:', '') !== this.allowedSpiffeId) { const err = new Error(`Untrusted SPIFFE ID: ${sanUri}`); (err as any).code = 'ERR_TLS_CERT_ALTNAME_INVALID'; return err; } return undefined; } }); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Dynamic X.509 SVID Sub-Hourly mTLS Rotation Invariant

SPIFFE/SPIRE Dynamic X.509 SVID Sub-Hourly mTLS Rotation Invariant defines an industrial-grade behavioral standard for security engineering. Enforces non-disruptive, dynamic rotation of short-lived SPIFFE X.509 SVIDs over sub-hourly TTL cycles via the SPIFFE Workload API. Mandates hot-swapping in-memory TLS SecureContext instances and trust bundles without terminating active TCP connections or restarting workload processes across heterogeneous cloud boundaries. 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 Disk-Loaded Certificates or Process Restarts on SVID Expiration Leading to Connection Drops 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 Disk-Loaded Certificates or Process Restarts on SVID Expiration Leading to Connection Drops	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 integrate with the SPIFFE Workload API via Unix Domain Socket (UDS) to stream X.509 SVIDs and federated trust bundles dynamically.

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.