Go Chi HTTP/3 0-RTT Replay Defense & Idempotency Enforcement

--- description: Go Chi HTTP/3 0-RTT Replay Defense & Idempotency Enforcement - HTTP/3 and TLS 1.3 0-RTT connection resumption permits early data transmission that is inherently vulnerable to network-level replay attacks. In Go Chi microservices executing financial transactions or state mutations, middleware must intercept non-safe requests containing the 'Early-Data: 1' header or QUIC early-data context and reject them with HTTP 425 (Too Early), forcing the client to retransmit after the full cryptographic handshake completes. globs: **/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/go-chi-http3-early-data-replay-defense" --- # Go Chi HTTP/3 0-RTT Replay Defense & Idempotency Enforcement > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Executing state-altering or financial handlers during HTTP/3 0-RTT early data without HTTP 425 rejection or distributed idempotency fencing. ## System Constraints You are a Principal Security and Distributed Systems Architect enforcing strict HTTP/3 0-RTT replay defenses and idempotency invariants in Go Chi services. You must enforce RFC 8470 compliance to prevent duplicated financial charges, account mutations, and duplicate inventory bookings caused by 0-RTT early data replays. ## Strict Guidelines - Engineers MUST ALWAYS reject state-modifying HTTP methods (POST, PUT, PATCH, DELETE) with HTTP status 425 (StatusTooEarly) whenever the 'Early-Data: 1' header is present or QUIC early data is detected without a cryptographic anti-replay token. - Engineers MUST NOT allow financial or state-altering routes to execute business logic inside 0-RTT early data under any circumstances. - Code MUST place the Early-Data defense middleware before route handlers, authentication verification, and application-level business logic in the Chi middleware pipeline. - Services MUST implement distributed, atomic idempotency storage (e.g., Redis via SET NX EX with fencing tokens) for non-0-RTT requests that supply an 'Idempotency-Key' header. - Middleware MUST populate the response header 'Retry-After: 0' and validate that upstream reverse proxies (e.g., Cloudflare, Envoy) preserve the 'Early-Data' header down to the Go application layer. - Handlers NEVER treat GET or HEAD requests as mutating operations; all read-only routes must remain safe and idempotent under RFC 7231. ## Bad vs Good Implementations ### Vulnerable mutating endpoint vs. RFC 8470 Compliant 0-RTT Defense Middleware #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler directly processes financial mutations without inspecting RFC 8470 'Early-Data' headers or QUIC 0-RTT state. An on-path attacker can duplicate client packets during 0-RTT resumption, replaying the exact transaction before TLS session validation finalizes. ```go package main import ( "encoding/json" "net/http" "github.com/go-chi/chi/v5" ) type PaymentRequest struct { AccountID string `json:"account_id"` Amount float64 `json:"amount"` } func RegisterRoutes(r *chi.Mux) { // CRITICAL FLAW: Blindly processes 0-RTT early data. // A passive network attacker can replay the TLS 1.3 / HTTP/3 0-RTT ClientHello // and request frame, resulting in duplicate charges. r.Post("/api/v1/payments", func(w http.ResponseWriter, r *http.Request) { var req PaymentRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } // ExecutePayment charges the card immediately without replay protection executePayment(r.Context(), req.AccountID, req.Amount) w.WriteHeader(http.StatusCreated) }) } ``` #### Production Standard (Correct) > **Standard**: The good implementation uses an early middleware check for RFC 8470 'Early-Data: 1'. Any mutating request sent during 0-RTT handshake resumption is aborted with HTTP 425 (StatusTooEarly) and 'Retry-After: 0', requiring the client to wait for 1-RTT completion. In addition, an atomic distributed idempotency lock guarantees safe processing once the connection is secure. ```go package main import ( "context" "encoding/json" "net/http" "strings" "time" "github.com/go-chi/chi/v5" ) // EarlyDataDefenseMiddleware enforces RFC 8470 replay protection. func EarlyDataDefenseMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { isEarly := strings.TrimSpace(r.Header.Get("Early-Data")) == "1" // Safe methods (GET, HEAD, OPTIONS) are permissible in 0-RTT if idempotent. // Unsafe/mutating methods MUST be rejected to force client replay post-handshake. if isEarly { switch r.Method { case http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete: w.Header().Set("Retry-After", "0") http.Error(w, "Too Early: 0-RTT replay rejected for non-safe method", http.StatusTooEarly) return } } next.ServeHTTP(w, r) }) } func RegisterRoutes(r *chi.Mux, idempotencyService IdempotencyManager) { r.Use(EarlyDataDefenseMiddleware) r.Post("/api/v1/payments", func(w http.ResponseWriter, r *http.Request) { idempotencyKey := strings.TrimSpace(r.Header.Get("Idempotency-Key")) if idempotencyKey == "" { http.Error(w, "Idempotency-Key header is mandatory", http.StatusBadRequest) return } // Lock key atomically to guarantee exactly-once execution acquired, release, err := idempotencyService.AcquireLock(r.Context(), idempotencyKey, 60*time.Second) if err != nil || !acquired { http.Error(w, "Concurrent or duplicate mutation in flight", http.StatusConflict) return } defer release() var req PaymentRequest if err := json.NewDecoder(r.Body).Decode(&req); err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } executePayment(r.Context(), req.AccountID, req.Amount) w.WriteHeader(http.StatusCreated) }) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Go Chi HTTP/3 0-RTT Replay Defense & Idempotency Enforcement

Go Chi HTTP/3 0-RTT Replay Defense & Idempotency Enforcement defines an industrial-grade behavioral standard for backend engineering. HTTP/3 and TLS 1.3 0-RTT connection resumption permits early data transmission that is inherently vulnerable to network-level replay attacks. In Go Chi microservices executing financial transactions or state mutations, middleware must intercept non-safe requests containing the 'Early-Data: 1' header or QUIC early-data context and reject them with HTTP 425 (Too Early), forcing the client to retransmit after the full cryptographic handshake completes. 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: Executing state-altering or financial handlers during HTTP/3 0-RTT early data without HTTP 425 rejection or distributed idempotency fencing. 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	Executing state-altering or financial handlers during HTTP/3 0-RTT early data without HTTP 425 rejection or distributed idempotency fencing.	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 reject state-modifying HTTP methods (POST, PUT, PATCH, DELETE) with HTTP status 425 (StatusTooEarly) whenever the 'Early-Data

Engineers MUST ALWAYS reject state-modifying HTTP methods (POST, PUT, PATCH, DELETE) with HTTP status 425 (StatusTooEarly) whenever the 'Early-Data: 1' header is present or QUIC early data is detected without a cryptographic anti-replay token.

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.