Hybrid Post-Quantum TLS 1.3 Key Exchange (X25519MLKEM768) and Strict Downgrade Defense

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Accepting Classical-Only Key Exchange or Allowing Pre-TLS 1.3 Downgrades on External Ingress) 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.

Hybrid Post-Quantum TLS 1.3 Key Exchange (X25519MLKEM768) and Strict Downgrade Defense

--- description: Hybrid Post-Quantum TLS 1.3 Key Exchange (X25519MLKEM768) and Strict Downgrade Defense - Mandates quantum-resilient hybrid key encapsulation mechanisms (X25519MLKEM768 / X25519Kyber768Draft00) across all ingress reverse proxies, load balancers, and external service runtimes to thwart 'harvest-now-decrypt-later' (HNDL) vectors. Explicitly disallows fallback to classical-only key exchanges (pure ECDHE/DHE) or legacy TLS versions (< TLS 1.3) on external trust boundaries. Enforces runtime verification of negotiated cipher suites and group allocations. globs: infra/**/*.ts, src/config/**/*.{ts,js}, src/network/**/*.{ts,js}, deploy/**/*.{ts,json,yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/hybrid-pq-tls-mlkem-downgrade-defense" --- # Hybrid Post-Quantum TLS 1.3 Key Exchange (X25519MLKEM768) and Strict Downgrade Defense > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Classical-Only Key Exchange or Allowing Pre-TLS 1.3 Downgrades on External Ingress ## System Constraints You are a Principal Security Architect enforcing Post-Quantum Cryptography (PQC) standards across infrastructure and runtime configurations. Your core invariant is: All external ingress endpoints MUST enforce TLS 1.3 with hybrid post-quantum key encapsulation (specifically X25519MLKEM768 or X25519Kyber768Draft00) prioritized, and MUST fail-closed when clients attempt to negotiate classical-only algorithms, preventing downgrade attacks by state-level adversaries. ## Strict Guidelines - Engineers MUST ALWAYS set `minVersion: 'TLSv1.3'` and `maxVersion: 'TLSv1.3'` on external client-facing TLS options. - Engineers MUST prioritize hybrid quantum-safe key exchange groups (e.g., `X25519MLKEM768:x25519_kyber768:X25519:P-256`) via the `ecdhCurve` or named groups parameter. - Engineers MUST NOT configure legacy TLS versions (TLSv1.0, TLSv1.1, TLSv1.2) on ingress termination proxies exposing sensitive data subject to HNDL threats. - Services MUST log telemetry and emit immediate alerts when non-PQC ciphers or classical-only exchanges are negotiated during any transition grace period. - Components NEVER accept insecure fallback renegotiation or bypass TLS certificate verification and strict group order validation. ## Bad vs Good Implementations ### Secure Node.js HTTPS / Ingress Server TLS Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring minVersion to TLSv1.2 permits classical ECDHE without post-quantum protection, exposing traffic to long-term retrospective decryption if quantum computers break discrete logarithms. ```typescript import * as tls from 'node:tls'; import * as https from 'node:https'; import * as fs from 'node:fs'; // Flaw: Allows TLS 1.2 fallback and relies exclusively on classical elliptic curves const server = https.createServer({ key: fs.readFileSync('/etc/ssl/privkey.pem'), cert: fs.readFileSync('/etc/ssl/fullchain.pem'), minVersion: 'TLSv1.2', ciphers: 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384', honorCipherOrder: true }, (req, res) => { res.writeHead(200); res.end('Vulnerable to Harvest-Now-Decrypt-Later'); }); ``` #### Production Standard (Correct) > **Standard**: Pins TLS 1.3 exclusively, prioritizes X25519MLKEM768 hybrid key exchange, and performs dynamic connection-level verification to terminate any connection failing the hybrid quantum-safe invariant. ```typescript import * as tls from 'node:tls'; import * as https from 'node:https'; import * as fs from 'node:fs'; // Production Invariant: Strict TLS 1.3 with Hybrid ML-KEM Key Exchange const server = https.createServer({ key: fs.readFileSync('/etc/ssl/privkey.pem'), cert: fs.readFileSync('/etc/ssl/fullchain.pem'), minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', // Enforce X25519MLKEM768 (standardized FIPS 203) with fallback to Kyber draft and classical X25519 ecdhCurve: 'X25519MLKEM768:x25519_kyber768:X25519', honorCipherOrder: true, ciphers: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256' }, (req, res) => { const socket = req.socket as tls.TLSSocket; const ephemeralGroup = socket.getEphemeralKeyInfo(); // Defense-in-depth: Assert negotiated group matches hybrid quantum-safe scheme if (!ephemeralGroup?.name || !['X25519MLKEM768', 'x25519_kyber768'].includes(ephemeralGroup.name)) { req.destroy(new Error('PQC Invariant Violation: Classical key exchange rejected')); return; } res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ status: 'PQC_PROTECTED', group: ephemeralGroup.name })); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Hybrid Post-Quantum TLS 1.3 Key Exchange (X25519MLKEM768) and Strict Downgrade Defense

Hybrid Post-Quantum TLS 1.3 Key Exchange (X25519MLKEM768) and Strict Downgrade Defense defines an industrial-grade behavioral standard for security engineering. Mandates quantum-resilient hybrid key encapsulation mechanisms (X25519MLKEM768 / X25519Kyber768Draft00) across all ingress reverse proxies, load balancers, and external service runtimes to thwart 'harvest-now-decrypt-later' (HNDL) vectors. Explicitly disallows fallback to classical-only key exchanges (pure ECDHE/DHE) or legacy TLS versions (< TLS 1.3) on external trust boundaries. Enforces runtime verification of negotiated cipher suites and group allocations. 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: Accepting Classical-Only Key Exchange or Allowing Pre-TLS 1.3 Downgrades on External Ingress 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	Accepting Classical-Only Key Exchange or Allowing Pre-TLS 1.3 Downgrades on External Ingress	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 set `minVersion

Engineers MUST ALWAYS set `minVersion: 'TLSv1.3'` and `maxVersion: 'TLSv1.3'` on external client-facing TLS options.

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.