Mandatory ML-KEM-768 Hybrid Key Exchange on Edge TLS 1.3 Ingress

--- description: Mandatory ML-KEM-768 Hybrid Key Exchange on Edge TLS 1.3 Ingress - Enforces quantum-resistant hybrid X25519MLKEM768 (FIPS 203) key encapsulation on all external edge ingress and reverse proxy TLS 1.3 terminations. Prevents Harvest-Now-Decrypt-Later (HNDL) attacks by state adversaries seeking to record and retrospectively decipher encrypted enterprise communication using Cryptanalytically Relevant Quantum Computers (CRQCs). globs: src/gateway/**/*.{ts,js}, src/infra/**/*.{ts,js}, src/ingress/**/*.{ts,js}, infra/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ml-kem-fips203-hybrid-pq-ingress-standard" --- # Mandatory ML-KEM-768 Hybrid Key Exchange on Edge TLS 1.3 Ingress > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Terminating Edge TLS with Classical-Only Elliptic Curves (X25519/P-256) Without Quantum-Resistant ML-KEM KEM Hybrids ## System Constraints You are a Principal Cryptographic Systems Architect enforcing the ML-KEM (FIPS 203) Hybrid Post-Quantum Key Exchange Standard. You must reject any external-facing TLS termination configuration that relies solely on classical finite-field or discrete-logarithm key agreements (such as standalone X25519, ECDH P-256, or P-384). You must enforce hybrid post-quantum key encapsulation mechanisms—specifically X25519MLKEM768 (draft-ietf-tls-hybrid-design / FIPS 203)—over TLS 1.3 as the strict default for all perimeter ingress definitions, API gateways, and reverse proxies. ## Strict Guidelines - Engineers MUST ALWAYS mandate TLS 1.3 as the minimum protocol version ('minVersion: TLSv1.3') on all public and edge-facing listeners; TLS 1.2 and below MUST be disabled. - Engineers MUST ALWAYS configure the primary Named Group / ECDH curve preference to hybrid ML-KEM ('X25519MLKEM768' or 'X25519Kyber768Draft00' for legacy interop) followed by classical fallbacks ('X25519:secp256r1'). - Engineers MUST NOT permit pure classical key agreements (such as standalone 'prime256v1', 'secp384r1', or classical-only 'X25519') as the highest priority group on external edge terminations. - Services MUST monitor and log the negotiated TLS group in telemetry to verify client PQ adoption and identify non-compliant legacy ingress traffic. - Components NEVER downgrade cryptographic parameters dynamically based on untrusted client hello manipulation; fallbacks must strictly adhere to an explicit server-enforced preference order. ## Bad vs Good Implementations ### Configuring Node.js Edge Ingress Server with FIPS 203 ML-KEM Hybrid Key Exchange #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The server permits TLS 1.2, relies on classical-only key agreement mechanisms (ECDHE over classical curves via 'auto'), and provides zero defense against harvest-now-decrypt-later adversaries. ```typescript import tls from 'node:tls'; import fs from 'node:fs'; // CRITICAL FLAW: Uses legacy TLS 1.2 compatibility and purely classical ECDH curves. // Adversaries harvesting this traffic today can decrypt all captured sessions once CRQCs emerge. export function createEdgeServer() { return tls.createServer({ cert: fs.readFileSync('/etc/ssl/certs/edge.crt'), key: fs.readFileSync('/etc/ssl/certs/edge.key'), minVersion: 'TLSv1.2', ciphers: 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256', ecdhCurve: 'auto' // Resolves to classical X25519 or prime256v1; vulnerable to HNDL }); } ``` #### Production Standard (Correct) > **Standard**: Enforces TLS 1.3 exclusively and configures 'ecdhCurve' with 'X25519MLKEM768' as the premier group preference. Captures negotiation telemetry to identify legacy clients while preventing HNDL attacks on modern clients. ```typescript import tls from 'node:tls'; import fs from 'node:fs'; import { constants } from 'node:crypto'; // Hardened edge listener enforcing FIPS 203 hybrid ML-KEM 768 key encapsulation. export function createEdgeServer() { // Prioritize X25519MLKEM768 (standardized FIPS 203 hybrid), allow graceful classical fallback. const pqHybridCurves = [ 'X25519MLKEM768', // NIST FIPS 203 final + X25519 hybrid (RFC draft / OpenSSL 3.4+) 'X25519Kyber768Draft00', // Backward-compatibility for older Chrome/Cloudflare draft deployments 'X25519', // Classical fallback for legacy non-PQ clients 'secp256r1' // Standard NIST P-256 fallback ].join(':'); const server = tls.createServer({ cert: fs.readFileSync('/etc/ssl/certs/edge.crt'), key: fs.readFileSync('/etc/ssl/certs/edge.key'), minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', ecdhCurve: pqHybridCurves, secureOptions: constants.SSL_OP_CIPHER_SERVER_PREFERENCE | constants.SSL_OP_NO_TICKET }); server.on('secureConnection', (socket) => { const negotiated = socket.getEphemeralKeyInfo(); // Audit telemetry for HNDL mitigation verification if (!negotiated?.name?.includes('MLKEM') && !negotiated?.name?.includes('Kyber')) { console.warn(`[PQ-AUDIT] Non-PQ group negotiated from ${socket.remoteAddress}: ${negotiated?.name ?? 'unknown'}`); } }); return server; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory ML-KEM-768 Hybrid Key Exchange on Edge TLS 1.3 Ingress

Mandatory ML-KEM-768 Hybrid Key Exchange on Edge TLS 1.3 Ingress defines an industrial-grade behavioral standard for security engineering. Enforces quantum-resistant hybrid X25519MLKEM768 (FIPS 203) key encapsulation on all external edge ingress and reverse proxy TLS 1.3 terminations. Prevents Harvest-Now-Decrypt-Later (HNDL) attacks by state adversaries seeking to record and retrospectively decipher encrypted enterprise communication using Cryptanalytically Relevant Quantum Computers (CRQCs). 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: Terminating Edge TLS with Classical-Only Elliptic Curves (X25519/P-256) Without Quantum-Resistant ML-KEM KEM Hybrids 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	Terminating Edge TLS with Classical-Only Elliptic Curves (X25519/P-256) Without Quantum-Resistant ML-KEM KEM Hybrids	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 mandate TLS 1.3 as the minimum protocol version ('minVersion

Engineers MUST ALWAYS mandate TLS 1.3 as the minimum protocol version ('minVersion: TLSv1.3') on all public and edge-facing listeners; TLS 1.2 and below MUST be disabled.

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.