Bun 1.2 Strict TLS ALPN Service Mesh Downgrade Defense

--- description: Bun 1.2 Strict TLS ALPN Service Mesh Downgrade Defense - Enforces deterministic Application-Layer Protocol Negotiation (ALPN) and post-handshake protocol verification across all internal microservice mTLS sockets in Bun 1.2. Eliminates silent protocol downgrades, TLS stripping, and cross-protocol smuggling by enforcing TLS 1.3, strict mTLS client certificate validation, and zero-tolerance ALPN matching. globs: src/**/*.ts, services/**/*.ts, infra/**/*.ts, mesh/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/bun-strict-tls-alpn-service-mesh-downgrade-defense" --- # Bun 1.2 Strict TLS ALPN Service Mesh Downgrade Defense > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Permissive mTLS listeners omitting ALPN validation or allowing implicit protocol downgrades in mesh traffic. ## System Constraints You are a Principal Security Architect enforcing strict ALPN (Application-Layer Protocol Negotiation) and mTLS invariants across all Bun 1.2 microservice transport boundaries. You must reject any socket implementation that allows protocol negotiation ambiguity, unauthenticated peer certificates, or missing post-handshake ALPN verification. ## Strict Guidelines - Engineers MUST ALWAYS declare an explicit, immutable array of supported protocols via `ALPNProtocols` in both `Bun.listen({ tls })` and client `Bun.connect({ tls })` configurations. - Engineers MUST ALWAYS verify negotiated protocol state post-handshake and immediately call `socket.end()` or `socket.destroy()` if `socket.alpnProtocol` is falsy or not in the authorized whitelist. - Services MUST enforce strict mutual TLS by setting `requestCert: true`, `rejectUnauthorized: true`, and validating peer certificates against internal mesh Root CAs. - Services MUST enforce `minVersion: 'TLSv1.3'` across all mesh socket endpoints to mitigate protocol transition attacks and cipher suite downgrades. - Components NEVER permit implicit fallbacks or empty protocol lists, preventing cross-protocol smuggling between HTTP/1.1, HTTP/2, and raw TCP streams. ## Bad vs Good Implementations ### Mesh Socket Listener with Strict ALPN Negotiation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting ALPNProtocols allows attackers to bypass protocol-level defenses, while rejectUnauthorized: false completely invalidates mTLS trust. The handler processes arbitrary frames without verifying that the negotiated ALPN protocol matches internal service expectations. ```typescript import { listen } from "bun"; // INSECURE: Omits ALPN enforcement, accepts TLS 1.2 fallbacks, // and does not assert post-handshake ALPN resolution. export function startMeshListener(port: number) { return listen({ hostname: "0.0.0.0", port, tls: { cert: Bun.file("/etc/certs/mesh.crt"), key: Bun.file("/etc/certs/mesh.key"), ca: Bun.file("/etc/certs/mesh-ca.crt"), requestCert: true, rejectUnauthorized: false // FATAL: Permits unauthenticated connections }, socket: { data(socket, data) { // Sockets can ingest arbitrary protocol payloads without ALPN verification handlePayload(data); } } }); } ``` #### Production Standard (Correct) > **Standard**: Configures strict TLSv1.3, mandates mutual TLS authentication (`rejectUnauthorized: true`), explicitly advertises accepted ALPN protocols, and aborts any connection during the `open` lifecycle event if the negotiated protocol does not match the strict internal whitelist. ```typescript import { listen, type Socket } from "bun"; const PERMITTED_ALPN_PROTOCOLS = Object.freeze(["mesh-rpc/v1", "h2"] as const); type PermittedProtocol = (typeof PERMITTED_ALPN_PROTOCOLS)[number]; interface MeshSocketData { negotiatedProtocol: PermittedProtocol; } export function startMeshListener(port: number) { return listen<MeshSocketData>({ hostname: "127.0.0.1", port, tls: { cert: Bun.file("/etc/certs/mesh.crt"), key: Bun.file("/etc/certs/mesh.key"), ca: Bun.file("/etc/certs/mesh-ca.crt"), requestCert: true, rejectUnauthorized: true, minVersion: "TLSv1.3", ALPNProtocols: [...PERMITTED_ALPN_PROTOCOLS] }, socket: { open(socket: Socket<MeshSocketData>) { const negotiated = socket.alpnProtocol; if (!negotiated || !PERMITTED_ALPN_PROTOCOLS.includes(negotiated as PermittedProtocol)) { // Immediately terminate on ALPN negotiation failure or unverified downgrade socket.end(); return; } socket.data = { negotiatedProtocol: negotiated as PermittedProtocol }; }, data(socket: Socket<MeshSocketData>, data: Buffer) { if (!socket.data?.negotiatedProtocol) { socket.end(); return; } routeVerifiedMeshFrame(socket.data.negotiatedProtocol, data); } } }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Bun 1.2 Strict TLS ALPN Service Mesh Downgrade Defense

Bun 1.2 Strict TLS ALPN Service Mesh Downgrade Defense defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic Application-Layer Protocol Negotiation (ALPN) and post-handshake protocol verification across all internal microservice mTLS sockets in Bun 1.2. Eliminates silent protocol downgrades, TLS stripping, and cross-protocol smuggling by enforcing TLS 1.3, strict mTLS client certificate validation, and zero-tolerance ALPN matching. 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: Permissive mTLS listeners omitting ALPN validation or allowing implicit protocol downgrades in mesh traffic. 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	Permissive mTLS listeners omitting ALPN validation or allowing implicit protocol downgrades in mesh traffic.	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 declare an explicit, immutable array of supported protocols via `ALPNProtocols` in both `Bun.listen({ tls })` and client `Bun.connect({ tls })` configurations.

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.