SPIFFE/SPIRE Dynamic mTLS Workload Attestation and Hot-Reload Invariant

--- description: SPIFFE/SPIRE Dynamic mTLS Workload Attestation and Hot-Reload Invariant - Enforces cryptographically verifiable, ephemeral microservice identity via the SPIRE Workload API Unix Domain Socket, eradicating all static API tokens and long-lived X.509 certificates. Mandates continuous streaming subscription to X.509 SVID rotations and in-memory dynamic TLS context reloading without process restarts or connection disruption. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/spiffe-spire-dynamic-workload-mtls-standard" --- # SPIFFE/SPIRE Dynamic mTLS Workload Attestation and Hot-Reload Invariant > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Baking static credentials or caching static X.509 SVID certificates indefinitely without dynamic SPIRE socket reload ## System Constraints You are a Principal Security Architect enforcing zero-trust microservice identity via SPIFFE/SPIRE. Mandate that all cross-service communication uses ephemeral, short-lived X.509 SVIDs acquired dynamically via the local SPIRE agent Workload API Unix Domain Socket. Forbid static API keys, shared secrets, cloud provider long-lived tokens, and static certificate file mounts. Ensure dynamic in-memory hot-reloading of mTLS credentials before expiration without service restarts, and strictly authorize remote peer SPIFFE IDs against expected trust domains and path schemas. ## Strict Guidelines - Services MUST acquire cryptographic identities exclusively via the SPIFFE Workload API Unix Domain Socket (e.g., unix:///run/spire/sockets/agent.sock). - Engineers MUST NOT configure static API tokens, long-lived client certificates, or hardcoded TLS key material in environment variables or volume mounts. - Workloads MUST subscribe to the SPIRE X.509 SVID streaming watcher API and dynamically hot-reload the TLS SecureContext in memory prior to certificate expiry. - mTLS handshakes MUST explicitly validate the peer's SPIFFE ID format (spiffe://<trust-domain>/<workload-path>) and verify membership against an exact authorization policy rather than relying solely on generic CA trust. - Components NEVER terminate the process or drop active connections during an SVID rotation cycle. ## Bad vs Good Implementations ### SPIFFE/SPIRE Dynamic SVID Context vs. Static TLS Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Loads static certificates synchronously on startup and passes a static API key. Short-lived SPIFFE SVIDs (typically valid for 1-12 hours) will expire without dynamic rotation, resulting in hard service outages. Peer identity is not validated beyond basic x509 SAN matching. ```typescript import * as https from 'https'; import * as fs from 'fs'; // ANTI-PATTERN: Loading static certs from filesystem or env variables once at startup. // Fails to rotate ephemeral certs; will cause outages on short-lived SVID expiration. const staticAgent = new https.Agent({ cert: fs.readFileSync(process.env.TLS_CERT_PATH || '/etc/certs/tls.crt'), key: fs.readFileSync(process.env.TLS_KEY_PATH || '/etc/certs/tls.key'), ca: fs.readFileSync(process.env.TLS_CA_PATH || '/etc/certs/ca.crt'), rejectUnauthorized: true, }); export async function callPaymentService(payload: unknown): Promise<void> { // Insecure: Uses static API token along with unrotated TLS await fetch('https://payment-service.mesh.internal/charge', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.PAYMENT_STATIC_API_KEY}` }, // Node https.Agent with frozen credentials dispatcher: undefined }); } ``` #### Production Standard (Correct) > **Standard**: Implements an in-memory DynamicSpiffeSource that receives SVID updates from the SPIRE agent socket and swaps the TLS SecureContext without restarting the process. Validates the peer's SPIFFE URI SAN during the TLS handshake, eradicating static credentials. ```typescript import * as tls from 'tls'; import * as https from 'https'; import { EventEmitter } from 'events'; interface SpiffeSvidUpdate { certChainPem: string; privateKeyPem: string; bundlePem: string; spiffeId: string; } // Dynamic credential provider subscribed to the local SPIRE Workload API export class DynamicSpiffeSource extends EventEmitter { private currentContext: tls.SecureContext | null = null; private expectedServerSpiffeId = 'spiffe://prod.internal/ns/finance/sa/payment-svc'; constructor(private readonly socketPath: string = '/run/spire/sockets/agent.sock') { super(); } public updateCredentials(svid: SpiffeSvidUpdate): void { // Hot-reload SecureContext in memory without process restart this.currentContext = tls.createSecureContext({ cert: svid.certChainPem, key: svid.privateKeyPem, ca: svid.bundlePem, minVersion: 'TLSv1.3' }); this.emit('rotated'); } public createDynamicAgent(): https.Agent { return new https.Agent({ checkServerIdentity: (hostname, cert) => { const sanList = cert.subjectaltname?.split(', ').map(s => s.trim()) || []; const peerSpiffeUri = sanList.find(san => san.startsWith('URI:spiffe://'))?.replace('URI:', ''); if (!peerSpiffeUri || peerSpiffeUri !== this.expectedServerSpiffeId) { const error = new Error(`Peer SPIFFE ID verification failed: expected ${this.expectedServerSpiffeId}, got ${peerSpiffeUri}`); (error as any).code = 'ERR_TLS_SPIFFE_IDENTITY_MISMATCH'; return error; } return undefined; } }); } public getSecureContext(): tls.SecureContext { if (!this.currentContext) { throw new Error('SPIFFE SVID not yet acquired from agent socket'); } return this.currentContext; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: SPIFFE/SPIRE Dynamic mTLS Workload Attestation and Hot-Reload Invariant

SPIFFE/SPIRE Dynamic mTLS Workload Attestation and Hot-Reload Invariant defines an industrial-grade behavioral standard for security engineering. Enforces cryptographically verifiable, ephemeral microservice identity via the SPIRE Workload API Unix Domain Socket, eradicating all static API tokens and long-lived X.509 certificates. Mandates continuous streaming subscription to X.509 SVID rotations and in-memory dynamic TLS context reloading without process restarts or connection disruption. 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: Baking static credentials or caching static X.509 SVID certificates indefinitely without dynamic SPIRE socket reload 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	Baking static credentials or caching static X.509 SVID certificates indefinitely without dynamic SPIRE socket reload	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 acquire cryptographic identities exclusively via the SPIFFE Workload API Unix Domain Socket (e.g., unix

Services MUST acquire cryptographic identities exclusively via the SPIFFE Workload API Unix Domain Socket (e.g., unix:///run/spire/sockets/agent.sock).

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.