Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Handshake Enforcement

--- description: Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Handshake Enforcement - Enforces post-quantum hybrid key encapsulation (X25519MLKEM768 / SecP256r1MLKEM768) as mandatory supported groups across all enterprise TLS 1.3 client agents and server termination listeners. Mitigates harvest-now-decrypt-later (HNDL) cryptographic attacks by rejecting classical-only ephemeral key exchanges on high-assurance zero-trust mesh ingress and egress paths. Mandates deterministic configuration of FIPS 203 ML-KEM-768 hybrid groups with strict fallback prevention. globs: src/**/tls/**/*.ts, src/**/network/**/*.ts, src/**/infrastructure/**/*.ts, src/**/config/**/*.ts, infra/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/mlkem768-hybrid-tls-handshake-invariant" --- # Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Handshake Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Classical-Only Ephemeral Key Exchange in Zero-Trust TLS Handshakes ## System Constraints You are a Principal Security Architect enforcing Post-Quantum Cryptography (PQC) standards for enterprise zero-trust communication. Mandate that all TLS 1.3 socket creations, HTTPS agents, and cryptographic listener profiles specify ML-KEM-768 hybrid key exchange (X25519MLKEM768 or SecP256r1MLKEM768) as the primary supported group. Disallow classical-only curves, non-TLS 1.3 protocols, and permissive fallback modes that expose sensitive payloads to Harvest Now, Decrypt Later (HNDL) adversaries. ## Strict Guidelines - Engineers MUST ALWAYS enforce TLS 1.3 as the strict minimum and maximum protocol version (`minVersion: 'TLSv1.3'`) when configuring zero-trust transport contexts. - Engineers MUST ALWAYS prioritize FIPS 203 hybrid groups (e.g., `X25519MLKEM768:x25519`) in the `ecdhCurve` or `supported_groups` configuration string. - Engineers MUST NOT allow implicit OpenSSL or Node.js 'auto' curve selection that defaults to classical P-256 or X25519 without quantum-resistant encapsulation. - Services MUST verify the negotiated group (`tlsSocket.getEphemeralKeyInfo()`) post-handshake and immediately abort connections that fail to establish a post-quantum hybrid session. - Components NEVER instantiate bare `http.Agent` or `https.Agent` without an explicit, hardened `secureContext` enforcing hybrid post-quantum cipher and curve constraints. ## Bad vs Good Implementations ### Configuring Secure HTTPS Agent with ML-KEM-768 Hybrid Invariant #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring TLS 1.2 or relying on default ecdhCurve allows classical-only key exchange (e.g., standard X25519 or secp256r1). Adversaries capturing ciphertext today can decrypt all transferred data using a cryptanalytically relevant quantum computer (CRQC) in the future. ```typescript import https from 'node:https'; import tls from 'node:tls'; // Flawed: Permits TLS 1.2 and uses default classical curves (Vulnerable to HNDL) export const egressAgent = new https.Agent({ minVersion: 'TLSv1.2', keepAlive: true, // ecdhCurve defaults to 'auto' (classical X25519 or P-256 only) rejectUnauthorized: true, }); export function dialEgress(url: string) { return https.request(url, { agent: egressAgent }); } ``` #### Production Standard (Correct) > **Standard**: Restricts negotiation strictly to TLS 1.3 with X25519MLKEM768 prioritized. Additionally inspects the ephemeral key metadata on secure connect, terminating the socket immediately if the peer fell back to a purely classical group. ```typescript import https from 'node:https'; import tls from 'node:tls'; // Mandatory hybrid curve group for TLS 1.3 (Draft/FIPS 203 standard: X25519MLKEM768) const PQC_ECDH_CURVES = 'X25519MLKEM768:SecP256r1MLKEM768:X25519'; export const egressAgent = new https.Agent({ minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', ecdhCurve: PQC_ECDH_CURVES, keepAlive: true, rejectUnauthorized: true, checkServerIdentity: (host, cert) => { return tls.checkServerIdentity(host, cert); }, }); export function dialEgressSecure(url: string, onEstablished?: (socket: tls.TLSSocket) => void) { const req = https.request(url, { agent: egressAgent }); req.on('socket', (rawSocket) => { rawSocket.on('secureConnect', () => { const tlsSocket = rawSocket as tls.TLSSocket; const keyInfo = tlsSocket.getEphemeralKeyInfo(); // Verify that post-quantum hybrid encapsulation was negotiated if (keyInfo && 'name' in keyInfo && !keyInfo.name.includes('MLKEM768')) { tlsSocket.destroy(new Error(`PQC Invariant Violation: Classical group negotiated (${keyInfo.name})`)); } onEstablished?.(tlsSocket); }); }); return req; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Handshake Enforcement

Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Handshake Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces post-quantum hybrid key encapsulation (X25519MLKEM768 / SecP256r1MLKEM768) as mandatory supported groups across all enterprise TLS 1.3 client agents and server termination listeners. Mitigates harvest-now-decrypt-later (HNDL) cryptographic attacks by rejecting classical-only ephemeral key exchanges on high-assurance zero-trust mesh ingress and egress paths. Mandates deterministic configuration of FIPS 203 ML-KEM-768 hybrid groups with strict fallback prevention. 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 Classical-Only Ephemeral Key Exchange in Zero-Trust TLS Handshakes 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 Classical-Only Ephemeral Key Exchange in Zero-Trust TLS Handshakes	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 enforce TLS 1.3 as the strict minimum and maximum protocol version (`minVersion

Engineers MUST ALWAYS enforce TLS 1.3 as the strict minimum and maximum protocol version (`minVersion: 'TLSv1.3'`) when configuring zero-trust transport contexts.

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.