SPIFFE/SPIRE Ephemeral SVID Dual-Active Overlap Rotation Invariant

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Synchronous Single-Certificate Atomic Pointer Replacement Causing In-Flight mTLS Resets) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

SPIFFE/SPIRE Ephemeral SVID Dual-Active Overlap Rotation Invariant

--- description: SPIFFE/SPIRE Ephemeral SVID Dual-Active Overlap Rotation Invariant - Mandates dual-active overlapping validity windows when consuming ephemeral X.509 SVIDs from SPIRE Workload APIs. Enforces asynchronous TLS certificate hot-reloading with graceful in-flight handshake drain periods, eliminating TCP RST spikes and TLS handshake failures during sub-hour credential rotations. globs: src/**/tls/**/*.{ts,js,go}, src/**/spiffe/**/*.{ts,js,go}, src/**/crypto/**/*.{ts,js,go}, src/**/network/**/*.{ts,js,go} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-dual-active-svid-rotation-invariant" --- # SPIFFE/SPIRE Ephemeral SVID Dual-Active Overlap Rotation Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Synchronous Single-Certificate Atomic Pointer Replacement Causing In-Flight mTLS Resets ## System Constraints You are a Principal Security and Infrastructure Architect enforcing SPIFFE/SPIRE ephemeral X.509 SVID continuous rotation invariants. You must prevent in-flight connection termination, TCP RST bursts, and TLS negotiation failures during high-frequency SVID issuance. Mandate dual-active overlapping credential buffers, asynchronous TLS context swaps, and grace-period validation for all Workload API integrations. ## Strict Guidelines - Engineers MUST ALWAYS maintain at least two valid SVIDs in memory (current active and predecessor draining) during rotation cycles until the predecessor's drain window expires. - Engineers MUST NOT synchronously evict or terminate active TLS context handles upon receiving a SPIRE Workload API X509SVIDResponse update. - Services MUST configure SVID renewal triggers at no later than 50% of total SVID Time-To-Live (TTL) to ensure adequate overlap time for concurrent TLS handshakes. - Inbound TLS configurations MUST verify incoming peer certificates against the dynamic SPIRE trust bundle rather than a static in-memory certificate snapshot. - Components NEVER drop or reset existing TCP sessions when a new SVID is staged; active connections MUST drain naturally while new handshakes bind to the newest SVID. ## Bad vs Good Implementations ### Dual-Active Dynamic TLS Context Provider with Drain Window #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Synchronously replacing the single active TLS context upon every SPIRE update abruptly invalidates active handshakes and resets connections undergoing mTLS negotiation, triggering cascading TCP connection reset storms under high rotation frequencies. ```typescript import * as tls from 'tls'; import { EventEmitter } from 'events'; interface SVIDMessage { cert: string; key: string; } export class InsecureSVIDManager { private currentContext: tls.SecureContext | null = null; constructor(spireStream: EventEmitter) { // ANTI-PATTERN: Immediate synchronous pointer overwrite. // In-flight handshakes referencing currentContext fail immediately with bad_certificate or connection reset. spireStream.on('svid_update', (svid: SVIDMessage) => { this.currentContext = tls.createSecureContext({ cert: svid.cert, key: svid.key }); }); } public getSecureContext(): tls.SecureContext { if (!this.currentContext) throw new Error('SVID not initialized'); return this.currentContext; } } ``` #### Production Standard (Correct) > **Standard**: Implements dual-active overlap caching by retaining the predecessor SVID in a draining pool for a configurable grace period, guaranteeing that ongoing and delayed TLS handshakes successfully finish without TCP resets. ```typescript import * as tls from 'tls'; import { EventEmitter } from 'events'; import { X509Certificate } from 'crypto'; interface SVIDMessage { cert: string; key: string; } interface ManagedSVID { context: tls.SecureContext; notAfterMs: number; notBeforeMs: number; } export class DualActiveSVIDManager { private activeSVID: ManagedSVID | null = null; private drainingSVID: ManagedSVID | null = null; private readonly DRAIN_GRACE_PERIOD_MS = 60_000; constructor(spireStream: EventEmitter) { spireStream.on('svid_update', (svid: SVIDMessage) => { this.rotate(svid); }); } private rotate(svid: SVIDMessage): void { const parsed = new X509Certificate(svid.cert); const notBeforeMs = Date.parse(parsed.validFrom); const notAfterMs = Date.parse(parsed.validTo); const newContext = tls.createSecureContext({ cert: svid.cert, key: svid.key }); // Demote current to draining state to allow in-flight handshakes to complete if (this.activeSVID) { this.drainingSVID = this.activeSVID; setTimeout(() => { if (this.drainingSVID === this.activeSVID) return; this.drainingSVID = null; }, this.DRAIN_GRACE_PERIOD_MS); } this.activeSVID = { context: newContext, notBeforeMs, notAfterMs }; } public getSecureContext(): tls.SecureContext { const now = Date.now(); if (this.activeSVID && now <= this.activeSVID.notAfterMs) { return this.activeSVID.context; } if (this.drainingSVID && now <= this.drainingSVID.notAfterMs) { return this.drainingSVID.context; } throw new Error('No valid overlapping SVID available'); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Ephemeral SVID Dual-Active Overlap Rotation Invariant

SPIFFE/SPIRE Ephemeral SVID Dual-Active Overlap Rotation Invariant defines an industrial-grade behavioral standard for security engineering. Mandates dual-active overlapping validity windows when consuming ephemeral X.509 SVIDs from SPIRE Workload APIs. Enforces asynchronous TLS certificate hot-reloading with graceful in-flight handshake drain periods, eliminating TCP RST spikes and TLS handshake failures during sub-hour credential rotations. 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: Synchronous Single-Certificate Atomic Pointer Replacement Causing In-Flight mTLS Resets 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	Synchronous Single-Certificate Atomic Pointer Replacement Causing In-Flight mTLS Resets	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 maintain at least two valid SVIDs in memory (current active and predecessor draining) during rotation cycles until the predecessor's drain window expires.

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.