Security Policy
Supported Versions
Only the latest release receives security fixes. Older versions are not maintained.
Reporting a Vulnerability
Do not open a public GitHub issue for security vulnerabilities.
Report security issues to flaviocfo@gmail.com with:
- A description of the vulnerability and its potential impact
- Steps to reproduce or a minimal proof-of-concept
- Any suggested mitigations you are aware of
You will receive an acknowledgement within 72 hours. We aim to release a fix within 14 days for critical issues and 30 days for others. We will credit you in the release notes unless you prefer to remain anonymous.
Current security behaviour
The router and its middleware behave as follows. Each statement describes MuxMaster v1.3.0.
- Route parameters survive wrapped contexts.
ParamsFromContext()returns the route parameters even when middleware registered withUse()wraps the request context (for exampleTimeout,WithValue, orRealIP). When the context is not the router's own, a fallback walks the wrapped context chain to find the parameters. - Redirect targets never carry a request-supplied host. The router's own
trailing-slash and fixed-path redirects build the
Locationheader from the path and the raw query only. A request line in absolute form (for exampleGET http://example.com/x HTTP/1.1) cannot place its scheme or host in theLocationheader. - Redirect
Locationencoding. The same redirects percent-encode every ASCII control byte (0x00–0x1F, 0x7F) per RFC 9110 §5.5 and every backslash (\→%5C). The backslash encoding prevents the WHATWG "special authority slashes" shape, in which a browser resolves aLocationsuch as/\example.com/to another origin. This is a deliberate divergence fromnet/http.Redirect, which encodes neither; themuxmaster.Redirecthelper delegates tonet/http.Redirectand therefore does not apply it.%5Cdecodes back to\on the follow-up request, so a registered backslash route is still reached on the same origin. A backslash can reach a redirect target only through a route the operator registered. - Root
HandleFastrefusesUse()middleware.Mux.HandleFastpanics when middleware registered withUse()is present, asGroup.HandleFastdoes, so a fast route is never registered without the middleware the operator expects to wrap it. See "Pre vs Use security boundary" below. ServeFilesraw-path guard.Mux.ServeFilesandGroup.ServeFilespanic at registration when the Mux has bothUseRawPathandUnescapePathValuesenabled, because the captured path could contain decoded/characters thathttp.FileServertreats as separators. Both variants share one check and the same panic message.CORSsendsVary: Originon every response. It adds the header withHeader.Add, keeping otherVaryvalues, to every response it produces or forwards, including requests withoutOriginand its own 400 and 403 responses. A shared cache therefore never serves a response fetched without CORS relevance to a CORS-relevant origin.BasicAuthcompares credentials in constant time across all users. Every request scans all registered users withcrypto/subtle, and both the supplied and the stored password are hashed with SHA-256 before the comparison, so the comparison always runs on two 32-byte digests regardless of the supplied password's length. Because every user is scanned, the cost of a request grows with the number of registered users; the measured cost is published on /benchmarks.OAuth2Introspectredacts credentials. The construction-timeslog.Warnandslog.Infolines log the endpoint's host and scheme only, never the full URL. The construction-time panics for a malformedEndpoint, anEndpointwithout a host, and anEndpointwith userinfo redact credentials embedded in the URL.OAuth2Introspectdefault client bounds its connections. With noHTTPClientconfigured, the default client uses its own transport, copied once fromhttp.DefaultTransportwithout initialising it, and allows at most 100 connections per introspection host (exact for HTTP/1.1). Concurrent cache misses therefore reuse connections instead of opening one per call. Construct the middleware at startup.Recovererdoes not corrupt a started response. It writes its 500 response only if the handler has not yet sent a status or body bytes.- Header values are allocated per request.
CORS,NoCache,SetHeader, theJSON,XML, andTextresponse helpers, and the router's automatic 405 andOPTIONSresponses allocate each header-value slice per request. Code that mutates a header slice in place (for examplew.Header()[k][0] = ...) affects only the current response. CompressandLoggerhonour 1xx informational responses. When a handler sends a 1xx status (for example 103 Early Hints) followed by a final status,Compressforwards the final status andLoggerrecords the final status, using the same predicate asnet/http.
Operator-facing defaults requiring opt-in
Three middleware components ship with backwards-compatible defaults
that are unsafe in production. Each emits a slog.Warn at construction
time when the unsafe default is in effect; search startup logs for these
warnings.
| Middleware | Unsafe default | Safe production setting |
|---|---|---|
JWTAuth |
RequireExpiry: false (no exp ⇒ replayable) |
RequireExpiry: true (RFC 8725 §4.4) |
RealIP() |
called with no CIDRs | RealIP(&proxyCIDR) with explicit trusted CIDR list |
OAuth2Introspect |
AllowInsecureEndpoint: true |
leave false — HTTPS endpoint only |
The upstream README "Security defaults" section reproduces this matrix and the recommended stack shown in "Composite token-handling stack" below.
Thread-Safety Contract
All public Mux fields (PanicHandler, NotFound, MethodNotAllowed,
GlobalOPTIONS, ErrorHandler, RedirectTrailingSlash, RedirectFixedPath,
CaseInsensitive, UseRawPath, UnescapePathValues, RedirectCode,
HandleMethodNotAllowed, HandleOPTIONS, PoolFastParams,
PoolRequestBundle) must be set before the first call to ServeHTTP. On the first request these values are atomically
captured into a frozen muxConfig snapshot and every subsequent dispatch
reads from that snapshot — direct field mutation after serving begins is
ignored by the dispatch path and races with the snapshot's first read.
To reconfigure handlers after serving starts, mutate the field and then call
Mux.Rebuild(). Rebuild() atomically resets the snapshot and the lazy
NotFound/405/OPTIONS/redirect handler caches so the next request re-reads
every field. Rebuild() is safe to call concurrently with ServeHTTP.
Use() and Pre() are safe to call concurrently with Handle() during
route registration (before serving), but must not be called concurrently with
active requests.
HTTP/2 Cleartext (h2c) Upgrade Handling
MuxMaster does not implement h2c-specific code. A request carrying
Upgrade: h2c and Connection: Upgrade headers is routed and dispatched
identically to any other request. By default, net/http does not perform
the h2c upgrade (RFC 7540 §3.4); the server responds with 200 OK and the
upgrade is silently ignored. To enable HTTP/2 over unencrypted TCP, operators must
explicitly configure the server (Go 1.27+: http.Server.Protocols with
UnencryptedHTTP2; earlier versions: use golang.org/x/net/http2/h2c);
MuxMaster's dispatcher operates identically in both cases. Routing and
middleware behaviour is unaffected by the Upgrade headers; treat h2c like
any other client request.
Timeout Middleware
middleware.Timeout cancels the request context after the configured
duration but does not preempt the handler goroutine. Go has no preemption
primitive for blocked syscalls. Handlers must actively check ctx.Done()
(or use context-aware I/O) to be preempted. Handlers that ignore the context
continue running until they return, regardless of the timeout; under load
this accumulates goroutines and can exhaust memory or upstream connections.
Handlers MUST observe ctx.Done() on every blocking call (database, network,
file I/O). Use the *Context variants of standard-library APIs
(sql.DB.QueryContext, HTTP request bodies via r.Context(), and so on).
Example of a cooperative handler:
func myHandler(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
select {
case result := <-doWork(ctx):
w.Write(result)
case <-ctx.Done():
http.Error(w, "request timeout", http.StatusGatewayTimeout)
}
}
Slowloris / Server Timeouts
MuxMaster is an http.Handler and does not configure the underlying
http.Server. To mitigate Slowloris and similar attacks, always set timeouts
on your server:
srv := &http.Server{
Handler: mux,
ReadHeaderTimeout: 30 * time.Second,
ReadTimeout: 60 * time.Second,
WriteTimeout: 60 * time.Second,
IdleTimeout: 120 * time.Second,
MaxHeaderBytes: 1 << 20, // 1 MiB
}
Accepted Known Limitations
Route-existence timing
Dispatch to a registered route (200) and dispatch to an unregistered path (404) at the same depth take measurably different time. The difference is intrinsic to radix-tree lookup: httprouter, chi, and bunrouter show a difference of the same order under the same measurement. If this is a concern, use a WAF or add uniform response delays via middleware.
Path normalisation accepted behaviour
The following routing behaviours are intentional and documented as operator responsibilities:
%61dminmatches/adminwhenUseRawPath=false(the default).net/httpdecodes%61toaduring URL parsing per RFC 3986 §6.2.2.2, so the router sees/admin. To enforce byte-exact path matching setmux.UseRawPath = true— patterns then match againstr.URL.RawPath, which preserves the percent-encoded form.
UseRawPath traversal
When BOTH UseRawPath = true AND UnescapePathValues = true, %2f
inside a single path segment is matched as one segment by the radix tree
(because / is preserved as the path separator only via a literal
slash) and is then DECODED in the captured param value. A request such
as /files/..%2fetc%2fpasswd against the route /files/:filepath
binds :filepath to the literal string ..\x2fetc\x2fpasswd — i.e. the
captured value contains a real slash.
Handlers that pass ParamsFromContext(...).Get("filepath") to
os.Open, http.FileServer, or any URL/file API WITHOUT calling
path.Clean (and rejecting values that contain ..) allow directory
traversal. The CleanPath middleware does NOT normalise post-decode
values; it only canonicalises the request path before dispatch.
Mitigation. Choose one of:
- Leave
UnescapePathValues = false(default) and let the handler callurl.PathUnescapeonly afterpath.Cleanand a..check. - Use
http.FileServer(as inexamples/static-site/), which appliespath.Cleaninternally and prevents escaped traversal sequences from escaping the configured root.
When UseRawPath and UnescapePathValues are both set, MuxMaster
emits a one-time slog.Warn at the first Handle/HandleFast call
to make the misconfiguration visible in startup logs. Additionally,
Mux.ServeFiles and Group.ServeFiles PANIC at registration when both
flags are set, since http.FileServer would treat decoded slashes as path
separators inside the static-file root.
UseRawPath + CleanPath interaction: When UseRawPath = true, the router
matches against r.URL.RawPath (the percent-encoded form, which net/http
sets only when it differs from the decoded r.URL.Path). If CleanPath is
registered (as a Pre-gate), it cleans the decoded path via path.Clean, then
compares the result against a cleaned RawPath: if they diverge (e.g. for
/a/%2e%2e/b, Path is /a/../b, which cleans to /b, while path.Clean
does not treat the encoded %2e%2e in RawPath as ..), CleanPath zeroes
RawPath to prevent an encoded traversal bypass. CleanPath therefore
protects against encoded traversal even with UseRawPath = true. Handlers
still must not pass RawPath values directly to file I/O; always decode and
validate.
-
Catch-all
*filepathparameters carry raw bytes, including any..traversal sequences. The router does NOT sanitise catch-all values — that is the boundary between router and storage backend. Handlers serving files MUST callpath.Cleanand must reject paths that escape their root (e.g. viafilepath.IsLocalor by checkingfilepath.Rel(root, joined)).Mux.ServeFilesalready delegates tohttp.FileServer, which performs path cleaning. -
Path parameters may contain any byte, including CR/LF. When
UseRawPath=false(the default),net/httpdecodes percent-encoded sequences before routing. A request like/users/%0D%0ASet-Cookie:%20hackedbecomes/users/\r\nSet-Cookie: hackedinr.URL.Path, and captured parameters carry the literal CR/LF bytes. Handlers must NOT echo parameters directly into headers or logs without escaping (useurl.PathEscapefor header injection mitigation,html.EscapeStringfor logs). The router itself does not strip or reject CR/LF; that is the handler's responsibility. -
Order-independent static and parameter routes. Routes can be registered in any order:
r.GET("/users/:id", h)followed byr.GET("/users/active", h)succeeds without panic. Static routes are never shadowed by param routes at the same depth. -
RedirectFixedPath=truediscloses route existence via the redirect status. The default isfalseprecisely because path cleaning before dispatch can convert non-existent paths into observable hits. Leave the default unless you understand the disclosure trade-off. -
middleware.CleanPath(registered viaPre) normalises dot segments before dispatch. It does NOT bypass authentication — middleware registered viaUsestill wraps the dispatched handler — but it can cause requests to land on a different handler than the raw path suggests. CleanPath is intended for clients that emit/foo/../barand similar; do not use it on endpoints where the literal path is semantically meaningful. Ordering: When composing CleanPath with path-inspecting Pre-gates (e.g. authorization checks that reject/admin/*), register CleanPath FIRST — a gate registered before CleanPath sees the raw path and can be bypassed by/admin/../public,//admin, or%2e%2e-encoded variants. Query fragment in parameters: Path parameters may contain?and#if percent-encoded in the request URL (%3Fand%23). When handlers construct URLs with captured parameters, useurl.QueryEscape(for query-string values) orurl.PathEscape(for path segments) to prevent accidental query/fragment boundary shifts.
Mount inner handler path sanitisation
Mux.Mount and Group.Mount forward requests to an inner handler with the
mount prefix stripped. The router does NOT clean the request path before
passing it to the inner handler. When the inner handler is another *Mux,
its routing receives the uncleaned path; if a request like /mount/../secret
reaches the mount (e.g. via CleanPath after the Mount prefix is consumed),
the inner handler receives /../secret and may dispatch it differently than
the outer router did. This is expected behaviour: inner handlers are responsible
for their own path validation and cleanup (e.g. calling CleanPath or validating
input). The inner Mux must register its own CleanPath Pre-gate.
OAuth2 introspection cache and token revocation
The OAuth2Introspect middleware caches the introspection response
(keyed by sha256 of the bearer token) for CacheTTL seconds. If the IDP
revokes a token mid-cache-window, MuxMaster continues to honour the
cached active=true response until the cache entry expires — a window
of up to CacheTTL. For high-security endpoints, set
OAuth2Options.CacheTTL = -1 to disable caching entirely; every request
will hit the introspection endpoint, but the singleflight group
coalesces concurrent calls for the same token, so the IDP load growth is
bounded by distinct-token concurrency rather than total request rate.
OAuth2 singleflight leader cancellation
When OAuth2Introspect has concurrent requests for the same token, the
first request (the "leader") performs the introspection call while others
(the "followers") wait for its result via an in-process singleflight group
keyed by sha256(token) (MuxMaster has no external dependencies).
The leader performs introspection with a detached
context.WithTimeout(context.WithoutCancel(r.Context()), 30s): the
leader's request-scoped context values are kept, but its cancellation and
deadline are not, so a leader cancelled by a Timeout middleware or a
client disconnect does not fail its followers. The 30s timeout is a fixed
upper bound on introspection latency; it is not configurable and is
separate from CacheTTL (which controls cache expiry, not introspection
timeout).
Compress sniff-buffer per-connection memory
middleware.Compress buffers up to 8 KiB per stalled connection while
sniffing whether the response body is large enough to be compressed.
Total memory is N × 8 KiB for N concurrent stalled connections. The
middleware does not enforce a per-connection timeout; operators MUST set
http.Server.ReadHeaderTimeout, http.Server.WriteTimeout and a
connection cap on the listener to bound this exposure.
Reflect-based ctx field offset
The tiered reqBundle optimisation (1 alloc per request with parameters)
relies on unsafe.Add over the offset of the private ctx field of
*http.Request, derived once via reflection at init(). If a future Go
version removes or renames the field, the offset cannot be resolved and
MuxMaster automatically falls back to r.WithContext (2 allocs per
request) without crashing. CI should cross-build against gotip
periodically to surface drift before a stable Go release.
RealIP misconfiguration
middleware.RealIP() called with no trusted-proxy CIDR list trusts every
peer — any client can spoof X-Forwarded-For / X-Real-IP and the router
will accept it as the real client IP. This is only safe behind a single
trusted proxy that strips inbound XFF; in any other deployment it lets
clients spoof their address and defeats ThrottlePerIP and IP-based
access controls. Always pass the proxy CIDR list explicitly:
proxyCIDR := netip.MustParsePrefix("10.0.0.0/8")
mux.Use(middleware.RealIP(&proxyCIDR))
A slog.Warn is emitted at construction time when RealIP() is called
without CIDRs.
RealIP + ThrottlePerIP ordering
middleware.ThrottlePerIP with a nil keyFn keys on r.RemoteAddr. If
RealIP is not registered (or is registered AFTER ThrottlePerIP), every
request behind a reverse proxy carries the LB's own address as
RemoteAddr and the per-IP limit collapses to a global rate limit. Always
register RealIP first so r.RemoteAddr reflects the true client IP
before throttling decisions are made:
mux.Use(middleware.RealIP(&proxyCIDR)) // first
mux.Use(middleware.ThrottlePerIP(50, ts, nil)) // then
A slog.Warn is emitted at construction time when ThrottlePerIP is
called with a nil keyFn.
Startup-time route registration cost
Registering routes with Handle, GET, POST, and related methods incurs
a one-time cost at application startup. The router's radix tree uses
copy-on-write semantics to guarantee rollback safety (see "Registration
Panics Rollback Guarantee" below), and this cost grows linearly with the
route count, not quadratically.
Registration is performed only at application startup from the application's own code; it is not reachable from HTTP requests, and dynamic route registration after serving begins is unsupported. Applications that construct their route table from untrusted configuration (e.g. a remote endpoint, a database, or user-supplied YAML) should bound the maximum route count, because whoever controls that configuration controls the startup time.
Timing differences in authentication and throttling
Several code paths take measurably different time depending on their input. The following are accepted as architectural or derived from the standard library; removing them would require either Go runtime changes (outside MuxMaster's scope) or padding that would add latency to every valid request. Operators concerned about statistical timing measurements from an adjacent network should rate-limit aggressively and monitor for prefix-scan probes.
BasicAuthvalid versus invalid password. The two outcomes run different code after authentication (next.ServeHTTPversushttp.ErrorwithWWW-Authenticate), so they differ in time by design. The credential comparison itself is constant time over all users.BasicAuthuser exists versus does not exist. The lookup scans all registered users in constant time; the remaining difference comes from other code paths (handler dispatch, middleware chain).BasicAuthpassword length. Both passwords are hashed to 32-byte digests before the comparison, so the comparison time does not depend on the length of the supplied password.APIKeyhit versus miss. Themap[[32]byte]stringlookup reveals whether a key exists.APIKeykeeps the map-based lookup because a constant-time alternative would compare every registered key withsubtle.ConstantTimeCompareon every request (O(n) per request), which is only worthwhile for very small key sets.ThrottleBacklogfill level. The fast-path acquisition is a single atomic load and compare-and-swap, so its time does not depend on how close the in-use count is to the configured limit.- Route existence. See "Route-existence timing" above.
JWTAuthHS256 versus ES256. The two verification paths differ by a negligible amount.JWTAuthalg=noneversus HS256.JWTAuthnever accepts the unsignedalg=noneformat:"none"is not a supported algorithm, and listing it inAlgorithmspanics at construction. A token whose header declaresalg=none, sent to an HS256-configuredJWTAuth, is rejected with 401 at the algorithm allow-list check. That rejection path takes a different time from HMAC verification, which reveals only that the token was rejected.- ECDSA zero signature versus random signature. The standard library's
ecdsa.Verifyreturns at slightly different times depending on signature shape. The signature is rejected either way; the difference only reveals that the signature is zero, which is publicly observable in the request. OAuth2Introspectcache hit, active versus inactive. The 401 and 200 response paths differ in execution length by design. The difference reveals nothing beyond what the HTTP status code already exposes.
Composition of timing differences
Three independent timing differences can combine to enable user-correlation in multi-tenant deployments or reconnaissance of IdP infrastructure:
- JWT algorithm-path timing: Configuring both HMAC (HS256) and RSA (RS256) algorithms reveals, through response latency, which algorithm family the server accepted the token with (see "JWT Mixed-Family Algorithms" below).
- OAuth2 introspection cache timing: The local token cache hits or misses depending on whether a token was previously seen by any client, so the response time reveals whether a token was recently active on the service.
- Route existence timing: Dispatch to a registered route and to an unregistered path at the same depth take different time (see "Route-existence timing" above).
Composite vector: A client can submit multiple tokens and measure response latencies to infer: (a) which algorithm family is configured, (b) which tokens have been recently used by other clients, and (c) which API paths are registered. Combined, this enables correlation of tokens across different clients if they are retried by multiple users, or reconnaissance of the internal endpoint topology.
Recommended deployment posture:
-
Option 1 (strict): Configure a single algorithm family per endpoint (HS256 or RS256, not both). This removes the algorithm-path timing difference entirely.
-
Option 2 (layered): If mixed algorithms are required, apply uniform response-time padding at the edge (reverse proxy, WAF, or a
Pre-registered middleware that adds fixed or random delays). This compresses the observable latency deltas below the statistical threshold reachable in a few hundred requests. -
Option 3 (rate-limit): Use
middleware.ThrottlePerIPto rate-limit token validation attempts to tens of requests per minute per client. This makes collecting sufficient samples for statistical analysis infeasible in practice. -
Option 4 (combination): Deploy a reverse proxy or WAF with DDoS scrubbing and request rate limiting, plus strict algorithm configuration at the IdP level (do not mix families).
The OAuth2 cache-hit/miss difference is inherent to token caching: set
OAuth2Options.CacheTTL = -1 to disable caching if this exposure is
unacceptable. The route-existence difference is intrinsic to any radix-tree
router; httprouter, chi, and bunrouter exhibit similar timing.
JWT Subject Claim Validation
JWTAuth does NOT validate the sub (subject) claim — it performs only
signature verification and (optionally) expiry checking. When a JWT is
verified as authentic, the sub claim value is not authoritative for
identifying the token's bearer; anyone with access to a single valid
signing key can mint tokens with arbitrary sub values. Authorization
logic must bind the token to the (issuer, subject) pair: do not authorise
a request based on sub alone, and do not assume that two tokens with the
same sub but different iss (issuer) claims belong to the same principal.
Extract both iss and sub, verify they match your expected issuer and
subject registry, and enforce additional checks (e.g. IP, user-agent, request
time) if needed.
JWT Expiry Claim Handling
JWTAuth treats exp: null (the JSON null value) and exp: 0 as if the
exp claim is absent — the token is never expired by the JWT expiry check.
When RequireExpiry: true (the recommended production setting), a token
without an exp claim or with exp null/0 fails validation. When
RequireExpiry: false (the default, kept for backward compatibility), such
tokens pass expiry validation (though they may fail on other checks like issuer or
signature). Tokens created by non-standard JWT libraries or hand-crafted
edge cases must carry a numeric, positive Unix timestamp in the exp claim
for expiry validation to work correctly.
JWT Mixed-Family Algorithms
JWTAuth configured with HS* and RS*/ES* algorithms in the same
Algorithms list reveals the algorithm code path through response latency:
HMAC and RSA verification take measurably different time. A client
submitting tokens labelled with different alg values can determine which
path the server runs from the response time alone, which narrows the search
space for algorithm-confusion attacks (RFC 8725 §3.1). Configure each
endpoint with a single algorithm family. Mixed-family configuration emits a
slog.Warn at construction time.
Recoverer Middleware Panic Logging
middleware.Recoverer and middleware.RecovererWithLogger catch panics
and log, at Error level (via the slog default logger or the supplied
logger), the raw panic value and the full stack trace. A panic that
includes sensitive data (e.g. panic("user_id=%d, api_key=%s", userID, key))
will be logged verbatim. Log sinks (files, centralized logging services,
SIEM systems) must be protected with appropriate access controls and
sanitisation rules. Do not use Recoverer as the sole defense against
information leakage in panic messages — validate and sanitise panic
recovery output at the log ingestion layer.
SIEM Re-interpretation of Log Fields
MuxMaster's Logger middleware writes one plain-text line per request
(<time> <method> <path> <status> <duration>) containing user-controlled
data: the request method and path. When either contains a control byte, a
non-ASCII byte, " or \, it is written with Go string-literal escaping
(strconv.QuoteToASCII, without the surrounding quotes), so a CR/LF in the
path appears as the literal two-character sequences \r and \n, never as
raw bytes. No raw CR, LF, or TAB byte reaches the log. A SIEM or log parser
that later unescapes these sequences may re-interpret them as control
characters. This is a log-consumer concern. Operators must configure their
log aggregation layer to treat these escapes as text.
BasicAuth Brute-Force
middleware.BasicAuth does not rate-limit authentication attempts. Compose it
with middleware.ThrottlePerIP to mitigate online brute-force:
mux.Use(
middleware.ThrottlePerIP(10, time.Second, nil),
middleware.BasicAuth("realm", creds),
)
BREACH and response compression
middleware.Compress does not mitigate the BREACH attack. When a response
compressed with gzip echoes one URL or query parameter that the client
controls alongside a secret, the client can recover the secret one
character at a time by observing the compressed response size.
Mitigations, in decreasing order of safety:
-
Do not compress endpoints that echo user-controlled input near secrets. The simplest fix: register
middleware.Compressonly on routes that do not echo client-controlled data into the body, or build a separate middleware chain for sensitive endpoints. -
Move secrets out of the response body. Put OAuth2 scopes, CSRF tokens, session IDs and JWTs in headers, cookies, or dedicated endpoints that are never reachable via client-controlled input.
-
Variable-length random padding. If 1 and 2 are not feasible, append a random-length (>= 256 bytes, length randomised per request) random payload to the response body. Fixed-length padding is not sufficient — the random content compresses to similar sizes per request.
Example mitigation pattern (variable-length random padding):
func tokenInfo(w http.ResponseWriter, r *http.Request) {
q := r.URL.Query().Get("q")
padN := 256 + rand.Intn(256) // length itself is randomised
pad := make([]byte, padN)
_, _ = rand.Read(pad)
body := fmt.Sprintf(`{"scope":"%s","query":"%s","pad":"%x"}`,
oauthScope, q, pad)
_, _ = io.WriteString(w, body)
}
MuxMaster cannot apply these mitigations on the operator's behalf because they require domain knowledge of which response fields are secret vs user-controlled.
Registration Panics Rollback Guarantee
If Handle (or any route registration method) panics — for example due to a
route conflict — the radix tree is guaranteed to remain unchanged. The two-phase copy-on-write implementation (path copying instead of full tree cloning) ensures that any mutation panicking mid-insertion rolls back atomically. Do not catch and ignore registration panics. Let them crash main() during development — the tree's consistency is protected, but the error is a sign of a bug (route conflict, invalid pattern, etc.). The rollback guarantee is enforced by test TestRegistrationRollback_PanicMidInsert_LiveTreeUntouched in the test suite.
Recoverer Must Be Outermost
middleware.Recoverer (or RecovererWithLogger) only catches panics in
middleware and handlers registered inside it. Register it as the outermost
middleware — or use r.Pre(middleware.RecovererWithLogger(logger)) — to
ensure it wraps the full dispatch chain.
Composite token-handling stack
A bearer-token endpoint that combines OAuth2 introspection (or JWT) with
per-IP throttling and reverse-proxy IP forwarding depends on FOUR distinct
settings. Leaving any one of them off weakens the whole stack: a passive
observer can capture a bearer token over plaintext HTTP, replay it
indefinitely (no exp), and forge X-Forwarded-For to bypass the per-IP
throttle. The recommended stack turns ALL of the following invariants ON:
| # | Invariant | Mechanism | Default |
|---|---|---|---|
| 1 | Introspection endpoint MUST be HTTPS | OAuth2Options.Endpoint panics on non-HTTPS |
enforced |
| 2 | JWT tokens MUST carry exp |
JWTOptions.RequireExpiry = true |
OFF (opt-in) |
| 3 | XFF must be parsed RIGHTMOST past trusted CIDRs | RealIP(trustedCIDRs...) walks rightmost-leftward |
enforced when len(trustedCIDRs)>0 |
| 4 | Per-IP table size must be CAPPED | ThrottlePerIPCapped (default 100_000) |
enforced via ThrottlePerIP wrapper |
A configuration that leaves any of these OFF (e.g. opens
AllowInsecureEndpoint "for testing", omits RequireExpiry, calls
RealIP() with no CIDRs, or builds a custom throttle without a cap)
is unsafe. The recommended pattern is:
trusted, _ := netip.ParsePrefix("10.0.0.0/8")
mux.Pre(
middleware.RealIP(&trusted), // (3) rightmost XFF
)
mux.Use(
middleware.ThrottlePerIP(100, 5*time.Second, nil), // (4) capped per-IP
middleware.JWTAuth(middleware.JWTOptions{
Secret: secret,
Algorithms: []string{"HS256"},
RequireExpiry: true, // (2) reject no-exp
}),
// OR use OAuth2Introspect with HTTPS endpoint:
// middleware.OAuth2Introspect(middleware.OAuth2Options{
// Endpoint: "https://idp.example/introspect", // (1) HTTPS only
// ...
// }),
)
The JWT and OAuth2 examples demonstrate the full pattern.
Layered panic recovery
Up to four layers may catch a panic. From outermost to innermost:
| Layer | Frame | Catches |
|---|---|---|
net/http per-connection recover |
around the whole handler | anything that escapes every layer below; logs "http: panic serving ..." and closes the connection |
Mux.PanicHandler (when set) |
deferred in Mux.ServeHTTP |
panics from Pre middleware and from dispatch (Use / UseFast middleware, handlers of both route types), unless an inner layer catches them first |
RecovererWithLogger registered with Pre |
around every Pre middleware registered after it and the dispatch |
panics from those Pre middleware, from dispatch and from both route types |
RecovererWithLogger registered with Use |
around the Handle routes registered after it |
panics from the Use middleware registered after it and from those handlers |
A panic is caught by the innermost recovering frame that encloses it.
Consequently, with a Pre-registered RecovererWithLogger, a panic in a
handler is handled by the Recoverer (plain 500) and PanicHandler never
sees it; PanicHandler then only receives panics raised by Pre
middleware registered before the Recoverer.
Boundary rules.
Mux.PanicHandlerMUST NOT panic. Its frame is outside every MuxMaster-owned recovery, including aPre-registered Recoverer, so a secondary panic propagates tonet/http, which closes the connection mid-response. There is no goroutine leak and no process crash, but the client sees a reset stream — confusing for HTTP/2 multiplexing and reverse-proxy retries.- For uniform recovery across stdlib and FastHandler routes, either set
Mux.PanicHandler(it covers both route types andPremiddleware) or registerRecovererWithLoggeras the firstr.Pre(...)middleware. AUse-registered Recoverer cannot coverHandleFastroutes (see "Pre vs Use security boundary" below). - Choose one primary mechanism. If you configure both, decide which one owns the 500 response: the innermost wins.
Pre vs Use security boundary
Mux.Pre() and Mux.Use() register middleware in different positions
of the dispatch pipeline. Mistaking one for the other has direct
authentication/authorisation consequences when HandleFast routes are
also in play.
| Middleware family | Wraps Handle (stdlib)? |
Wraps HandleFast? |
Mode |
|---|---|---|---|
r.Pre(...) |
YES | YES | Outside dispatch — http.Handler. |
r.Use(...) |
YES | NO — panics at register. | Inside dispatch — http.Handler. |
r.UseFast(...) |
NO | YES | Inside dispatch — FastMiddleware. |
Implications.
- An auth gate (e.g.
JWTAuth) registered viar.Use(...)does NOT coverHandleFastroutes — MuxMaster panics atHandleFastregistration to expose this immediately. Either (a) register the auth viar.Pre(...)so it covers BOTH route types, or (b) duplicate the auth as aFastMiddlewareand register it viar.UseFast(...). - Because
Preruns OUTSIDE the dispatch (inMux.ServeHTTPbefore the radix-tree lookup), it sees the path BEFORE any route-specific handler decision — useful forCleanPath,RealIP,RecovererWithLogger, request ID assignment, or any policy that must be uniform across the router. Useruns INSIDE the dispatch (after the route is matched) and is baked into the wrapped handler at registration time. Its only path to a fast route is viaUseFast.
Operators reviewing an auth/CORS/rate-limit policy by reading Use(...)
calls SHOULD also inspect HandleFast(...) registrations and
UseFast(...) calls; otherwise a fast-route bypass is invisible.
Exception — Asterisk-form OPTIONS * HTTP/1.1: Auth gates registered
in Pre() do not see asterisk-form OPTIONS requests by default, because
net/http intercepts and answers them before Mux.ServeHTTP is called
(under the default server configuration DisableGeneralOptionsHandler == false). This does not expose any route: net/http's response is fixed
(200 OK, Content-Length: 0, no Allow header) and route-independent. To
route these requests through MuxMaster and apply Pre() middleware to them,
set http.Server.DisableGeneralOptionsHandler = true.
HTTP/1.1 Request Smuggling
Request smuggling (CL.TE / TE.CL / TE.TE) is handled by Go's net/http
package at the framing layer. No action is required at the MuxMaster level.
Differential Error Responses
Differential error responses (404 vs 405 vs 301) are intentional HTTP
semantics and are present in all HTTP routers. If normalising error responses
is required for your threat model, use a WAF or a custom NotFound /
MethodNotAllowed handler.
ThrottlePerIPCapped saturation
When the per-IP throttle table reaches maxTableSize and every slot is
in active use (refs > 0), new client IPs receive HTTP 503 immediately.
A client controlling at least maxTableSize distinct IPs (default
100 000) and keeping their requests open can sustain this lockout for
as long as the connections remain. A request that times out releases its
slot, so the table drains when those connections end.
Required operator mitigations:
- Deploy upstream DDoS scrubbing (Cloudflare, AWS Shield, GCP Cloud Armor).
- Configure
http.Server{ReadHeaderTimeout, IdleTimeout, ReadTimeout}so slow-handler connections cannot hold throttle slots indefinitely. - Reduce
maxTableSizefor high-sensitivity endpoints — the cap intentionally trades fairness for memory safety.
This is accepted behaviour: the cap exists precisely to prevent unbounded memory growth when the set of client IPs keeps changing.
Upstream source
The security-sensitive behaviours on this page (the Pre versus Use boundary, redirect encoding, the ServeFiles raw-path guard, panic recovery) are implemented in mux.go, group.go, and tree.go at the v1.3.0 tag; the middleware behaviours are in the middleware package.