docs: warn about underscore header spoofing in NewRequestWithContext (#2460)

## What

Document that `NewRequestWithContext` does not strip request headers
whose name contains an underscore.

## Why

CGI maps dashes to underscores (`Foo-Bar` becomes `HTTP_FOO_BAR`), so a
client-supplied `Foo_Bar` header is indistinguishable from a legitimate
`Foo-Bar` in `$_SERVER` and can spoof it. This affects any such header
an application or upstream proxy trusts (forwarded-for, auth, etc.).

The Caddy-based server and reverse proxies like nginx
(`underscores_in_headers off`) already drop these. Callers using the Go
API directly must do it themselves unless they explicitly whitelist
them.

## Changes

- Doc comment on `NewRequestWithContext` explaining the risk and
mitigation.
- `ExampleServeHTTP` now drops underscore headers before building the
request.

Author: dunglas

context.go

@@ -61,6 +61,15 @@ func newFrankenPHPContext() *frankenPHPContext {
 }
 
 // NewRequestWithContext creates a new FrankenPHP request context.
+//
+// FrankenPHP does not strip request headers whose name contains an underscore.
+// Because CGI maps dashes to underscores ("Foo-Bar" becomes the HTTP_FOO_BAR
+// variable), a client-supplied "Foo_Bar" header is indistinguishable from the
+// legitimate "Foo-Bar" in $_SERVER and can spoof it. This affects any such
+// header an application or upstream proxy trusts (forwarded-for, auth, etc.).
+// Drop headers containing an underscore before calling this function, unless
+// you explicitly need (and whitelist) them. The Caddy-based server and reverse
+// proxies such as nginx (underscores_in_headers off) already do this.
 func NewRequestWithContext(r *http.Request, opts ...RequestOption) (*http.Request, error) {
 	fc := newFrankenPHPContext()
 	fc.request = r

frankenphp_test.go

@@ -810,6 +810,16 @@ func ExampleServeHTTP() {
 	defer frankenphp.Shutdown()
 
 	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		// Drop headers whose name contains an underscore: CGI maps dashes to
+		// underscores, so "Foo_Bar" would be indistinguishable from "Foo-Bar"
+		// in $_SERVER and could spoof any header an app or proxy trusts.
+		// Whitelist any you genuinely need.
+		for name := range r.Header {
+			if strings.ContainsRune(name, '_') {
+				delete(r.Header, name)
+			}
+		}
+
 		req, err := frankenphp.NewRequestWithContext(r, frankenphp.WithRequestDocumentRoot("/path/to/document/root", false))
 		if err != nil {
 			panic(err)