Post-Quantum ML-KEM/X25519 Hybrid TLS 1.3 Key Exchange Enforcement

--- description: Post-Quantum ML-KEM/X25519 Hybrid TLS 1.3 Key Exchange Enforcement - Enforces mandatory hybrid post-quantum key exchange (FIPS 203 ML-KEM-768 combined with X25519) on all enterprise TLS 1.3 ingress terminations to defeat Harvest Now, Decrypt Later (HNDL) attacks. Disallows legacy TLS 1.2, prohibits classical-only key-exchange groups in secure profiles, and strictly mandates PQ-hybrid group preference ordering across API gateway listeners. globs: src/gateway/**/*.{ts,js}, src/infra/**/*.{ts,js}, src/server/**/*.{ts,js}, infra/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/pq-hybrid-mlkem-x25519-tls13-standard" --- # Post-Quantum ML-KEM/X25519 Hybrid TLS 1.3 Key Exchange Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Pure Classical ECDHE Key Agreement in Enterprise Ingress Terminations ## System Constraints You are a Principal Security Architect enforcing Post-Quantum Cryptography (PQC) standards across enterprise network ingress points. You must ensure that all TLS termination configurations and reverse proxy definitions mandate TLS 1.3 with hybrid Post-Quantum Key Encapsulation Mechanisms (specifically X25519MLKEM768 / X25519Kyber768Draft00) prioritized over classical groups. You must strictly reject any code or configuration that enables TLS 1.2 or permits non-hybrid classical-only key exchanges in high-security zones, safeguarding against 'Harvest Now, Decrypt Later' (HNDL) state-level adversaries. ## Strict Guidelines - Services MUST enforce 'TLSv1.3' as the absolute minimum TLS version (`minVersion: 'TLSv1.3'`); TLS 1.2 and below MUST NOT be enabled under any circumstances. - Ingress key exchange group configurations MUST prioritize 'X25519MLKEM768' (FIPS 203 compliant) or 'SecP256r1MLKEM768' ahead of any classical fallback groups. - Engineers MUST NOT allow non-hybrid classical-only ECDHE groups (e.g., pure 'X25519', 'P-256', 'P-384') without an explicit, cryptographically justified security exception for legacy clients. - Engineers MUST verify that the underlying OpenSSL/BoringSSL runtime supports FIPS 203 ML-KEM groups before binding ingress listeners. - Telemetry and audit logs MUST capture the negotiated TLS 1.3 group identifier per session to detect non-hybrid fallbacks and trigger real-time telemetry alerts on classical cipher degradation. - Components NEVER execute TLS renegotiation or dynamic downgrade handshakes when hybrid PQC key exchange fails; failed handshakes MUST result in immediate connection termination (ERR_TLS_HANDSHAKE_FAILURE). ## Bad vs Good Implementations ### Node.js HTTPS/TLS Gateway Ingress Listener Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring minVersion as 'TLSv1.2' and specifying ecdhCurve as 'auto' permits classical-only ECDHE key exchange without quantum resistance. An adversary harvesting encrypted traffic today can store it indefinitely and decrypt it once cryptographically relevant quantum computers (CRQCs) become operational. ```typescript import tls from 'node:tls'; import https from 'node:https'; // ANTI-PATTERN: Classical-only curve negotiation vulnerable to HNDL export function createGatewayServer(cert: string, key: string): https.Server { const secureContext = tls.createSecureContext({ cert, key, minVersion: 'TLSv1.2', // Flaw: Allows TLS 1.2 downgrade ecdhCurve: 'auto', // Flaw: Runtime defaults to classical X25519 or P-256 ciphers: 'HIGH:!aNULL:!MD5', }); return https.createServer({ secureContext }); } ``` #### Production Standard (Correct) > **Standard**: Pins both minVersion and maxVersion to 'TLSv1.3' and forces the ecdhCurve preference list to prioritize FIPS 203 hybrid ML-KEM-768 key exchanges (X25519MLKEM768, SecP256r1MLKEM768) over classical X25519. In addition, session handshake telemetry monitors group negotiation to flag potential classical downgrade attacks. ```typescript import tls from 'node:tls'; import https from 'node:https'; // PRODUCTION FIX: Explicit ML-KEM hybrid key-exchange with TLS 1.3 invariant export const PQC_SUPPORTED_GROUPS = [ 'X25519MLKEM768', 'SecP256r1MLKEM768', 'x25519_kyber768' ].join(':'); export interface TlsGatewayOptions { cert: string; key: string; ca?: string; } export function createPostQuantumGatewayServer(options: TlsGatewayOptions): https.Server { const secureContext = tls.createSecureContext({ cert: options.cert, key: options.key, ca: options.ca, minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', // Mandates ML-KEM hybrid curves prioritized ahead of fallback ecdhCurve: `${PQC_SUPPORTED_GROUPS}:X25519`, honorCipherOrder: true }); const server = https.createServer({ secureContext }); server.on('secureConnection', (socket: tls.TLSSocket) => { const negotiated = socket.getNegotiatedProtocol() || 'TLS 1.3'; const curve = socket.getEphemeralKeyInfo(); // Security invariant: Ensure session actually negotiated a hybrid group if (curve?.type === 'ECDH' && !curve.name?.includes('MLKEM') && !curve.name?.includes('kyber')) { socket.emit('pqcFallbackWarning', { remoteAddress: socket.remoteAddress, negotiatedGroup: curve.name, protocol: negotiated }); } }); return server; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Post-Quantum ML-KEM/X25519 Hybrid TLS 1.3 Key Exchange Enforcement

Post-Quantum ML-KEM/X25519 Hybrid TLS 1.3 Key Exchange Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces mandatory hybrid post-quantum key exchange (FIPS 203 ML-KEM-768 combined with X25519) on all enterprise TLS 1.3 ingress terminations to defeat Harvest Now, Decrypt Later (HNDL) attacks. Disallows legacy TLS 1.2, prohibits classical-only key-exchange groups in secure profiles, and strictly mandates PQ-hybrid group preference ordering across API gateway listeners. 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: Permitting Pure Classical ECDHE Key Agreement in Enterprise Ingress Terminations 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	Permitting Pure Classical ECDHE Key Agreement in Enterprise Ingress Terminations	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 enforce 'TLSv1.3' as the absolute minimum TLS version (`minVersion

Services MUST enforce 'TLSv1.3' as the absolute minimum TLS version (`minVersion: 'TLSv1.3'`); TLS 1.2 and below MUST NOT be enabled under any circumstances.

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.