TLS 1.3 Encrypted Client Hello (ECH) Split-Mode Ingress Enforcement

--- description: TLS 1.3 Encrypted Client Hello (ECH) Split-Mode Ingress Enforcement - Enforces strict TLS 1.3 Encrypted Client Hello (ECH) ingress policies to prevent plaintext Server Name Indication (SNI) leakage across transit networks. Mandates split-mode client-facing termination with DNS-over-HTTPS (DoH) HTTPS RR (RFC 9460) validation, rejecting insecure unencrypted SNI fallback. globs: src/gateway/**/*.{ts,js}, src/edge/**/*.{ts,js}, infra/edge/**/*.{ts,json} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tls-1-3-ech-ingress-guardrail" --- # TLS 1.3 Encrypted Client Hello (ECH) Split-Mode Ingress Enforcement > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Permitting Plaintext Outer SNI Fallback and Missing ECHConfig DoH Record Validation ## System Constraints You are a Principal Security Architect enforcing RFC 9460 and RFC 9180 TLS 1.3 Encrypted Client Hello (ECH) ingress standards. Mandate split-mode edge termination, validate DoH HTTPS resource records, prohibit outer SNI routing fallback, and verify zero metadata leakage at the ingress perimeter. ## Strict Guidelines - Edge gateways MUST enforce TLS 1.3 minimum protocol version with valid ECH extension decapsulation before dispatching requests to internal mesh routing. - Ingress controllers MUST NOT fall back to routing traffic via outer public SNI if the inner client hello decapsulation fails; they MUST either terminate on the public decoy origin or return an ECH retry configuration via `retry_configs`. - DNS orchestrators MUST generate and validate DNS-over-HTTPS (DoH) HTTPS Resource Records (RR type 65) carrying active HPKE ECHConfigList parameters synchronized with front-end decapsulation keys. - Services MUST isolate the public-facing outer SNI (`public_name`) strictly as an unprivileged generic decoy domain and NEVER as a valid backend API endpoint. - Edge middleware MUST verify that client requests negotiated via TLS 1.3 include ECH decapsulation confirmation headers injected only by trusted split-mode ingress proxies. ## Bad vs Good Implementations ### Edge Ingress TLS 1.3 ECH Validation Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Inspects cleartext host headers and outer SNI without verifying that ECH decapsulation occurred. Permits passive network observers to intercept target API domains via plaintext SNI metadata. ```typescript import { Request, Response, NextFunction } from 'express'; // ANTI-PATTERN: Reliant on unencrypted outer SNI and lacks validation for ECH decapsulation. export function validateTlsMetadata(req: Request, res: Response, next: NextFunction) { const sni = req.headers['x-forwarded-sni'] || req.hostname; // Permitting cleartext SNI routing fallback if (!sni) { return res.status(400).json({ error: 'Missing Host or SNI header' }); } // Direct routing without checking if outer SNI was decrypted via inner ECH req.routingTarget = sni.toString(); return next(); } ``` #### Production Standard (Correct) > **Standard**: Validates that the connection is negotiated strictly over TLS 1.3 with ECH decapsulation verified (`echStatus === 'accepted'`), enforces a decoupled public outer SNI decoy, and prevents routing based on plaintext metadata. ```typescript import { Request, Response, NextFunction } from 'express'; interface EdgeTlsSecurityContext { tlsVersion: string; echAccepted: boolean; innerSni: string; outerSni: string; } // PRODUCTION INVARIANT: Split-mode ECH validation rejecting plaintext outer SNI fallback export function validateTlsMetadata(req: Request, res: Response, next: NextFunction) { const tlsVersion = req.header('x-edge-tls-version'); const echStatus = req.header('x-edge-ech-status'); // Set by ingress decapsulator (e.g., 'accepted', 'bypassed', 'failed') const innerSni = req.header('x-edge-inner-sni'); const outerSni = req.header('x-edge-outer-sni'); if (tlsVersion !== 'TLSv1.3') { return res.status(426).json({ error: 'Upgrade Required', message: 'Ingress mandates TLS 1.3 with Encrypted Client Hello (RFC 9180/RFC 9460)' }); } // Mandate ECH inner negotiation; reject plaintext outer SNI leakage if (echStatus !== 'accepted' || !innerSni) { res.setHeader('Cache-Control', 'no-store'); // Direct client to fetch authoritative DoH HTTPS RR for updated ECHConfig return res.status(421).json({ error: 'Misdirected Request', message: 'ECH decapsulation required. Fetch authoritative HTTPS RR via DoH for active ECHConfig.' }); } // Enforce decoy isolation: outer SNI MUST NOT match sensitive internal routing domains const AUTHORIZED_PUBLIC_DECOY = 'public.ingress.api.gateway'; if (outerSni && outerSni !== AUTHORIZED_PUBLIC_DECOY) { return res.status(403).json({ error: 'Forbidden', message: 'Outer SNI decoy mismatch' }); } req.routingTarget = innerSni; return next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TLS 1.3 Encrypted Client Hello (ECH) Split-Mode Ingress Enforcement

TLS 1.3 Encrypted Client Hello (ECH) Split-Mode Ingress Enforcement defines an industrial-grade behavioral standard for security engineering. Enforces strict TLS 1.3 Encrypted Client Hello (ECH) ingress policies to prevent plaintext Server Name Indication (SNI) leakage across transit networks. Mandates split-mode client-facing termination with DNS-over-HTTPS (DoH) HTTPS RR (RFC 9460) validation, rejecting insecure unencrypted SNI fallback. 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 Plaintext Outer SNI Fallback and Missing ECHConfig DoH Record Validation 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 Plaintext Outer SNI Fallback and Missing ECHConfig DoH Record Validation	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:

Edge gateways MUST enforce TLS 1.3 minimum protocol version with valid ECH extension decapsulation before dispatching requests to internal mesh routing.

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.