docs: warn about anchoring RegexpWhitelist patterns (#2187)

Author: lestrrat

MIGRATION.md

@@ -261,6 +261,8 @@ type Fetcher interface {
 >
 > `jwkfetch.Client` applies the whitelist to both the initial URL and every HTTP redirect target, so a hostile JWKS host cannot 302 into an off-allowlist URL. This redirect-hop enforcement only applies when the configured `HTTPClient` is a `*http.Client`; if you supply a custom transport, you are responsible for policing redirects yourself.
 >
+> If you migrate a `RegexpWhitelist`, **anchor your patterns** — they are **not** anchored for you. `example\.com` matches anywhere in the URL and also allows `https://example.com.attacker.com/evil`, reopening the SSRF / key-substitution hole. Write `^https://example\.com/` (anchor the start with `^`, escape the dots, terminate the host with `/`), or use `MapWhitelist` when the issuer URLs are known exactly.
+>
 > `jws.WithVerifyAuto(nil)` / `jwt.WithVerifyAuto(nil)` is no longer supported — both error at jku-verification time rather than silently using any default.
 
 **Default behavior is equivalent to v3 for trusted, hard-coded URLs.** Both v3's `jwk.Fetch()` and v4's `jwkfetch.NewClient().Fetch()` permit every URL by default — the right choice when the URL is a compile-time constant or comes from trusted configuration. You generally do not need to pass `WithWhitelist` to migrate a hard-coded-URL call site. The SSRF risk above is specific to `jku`-style verification, where the URL originates in the untrusted JWS header.

docs/02-jws.md

@@ -634,6 +634,8 @@ jwx does NOT wrap the fetcher in a default-deny — it has no way to inspect a `
 
 A `jwkfetch.Client` whitelist is applied to both the initial URL and every redirect target, so a hostile JWKS host cannot 302-bypass the allowlist. See the [jwkfetch README](https://github.com/jwx-go/jwkfetch) for `MapWhitelist` / `RegexpWhitelist` / `WhitelistFunc` patterns and the regex footguns to avoid.
 
+**If you reach for `RegexpWhitelist`, anchor your patterns.** They are **not** anchored for you, so `example\.com` matches anywhere in the URL and also allows `https://example.com.attacker.com/evil` — a whitelist bypass back into the SSRF / key-substitution territory the whitelist was meant to close. Write `^https://example\.com/` (anchor the start with `^`, escape the dots, terminate the host with `/`), or prefer `MapWhitelist` when the `jku` URLs are known up front.
+
 The URL in the `jku` field must have the `https` scheme and the key ID in the fetched JWK Set must match the key ID in the JWS header.
 
 Passing `nil` to `jws.WithVerifyAuto` is not supported: jku verification will error at use time rather than silently falling back to any default. This is intentional — there is no correct default fetcher for jku verification because the policy (which URLs to trust) is site-specific.

docs/04-jwk.md

@@ -621,11 +621,23 @@ Pass any implementation of `jwkfetch.Whitelist` to `jwkfetch.WithWhitelist`:
 - `jwkfetch.InsecureWhitelist{}` — allow every URL (the default when `WithWhitelist` isn't passed)
 - `jwkfetch.BlockAllWhitelist{}` — deny every URL (useful for tests, safety assertions)
 - `jwkfetch.NewMapWhitelist().Add(url1).Add(url2)` — fixed allow-list of exact URLs
-- `jwkfetch.NewRegexpWhitelist().Add(pattern)` — pattern-based allow-list
+- `jwkfetch.NewRegexpWhitelist().Add(regexp.MustCompile(pattern))` — pattern-based allow-list (**anchor your patterns — see the warning below**)
 - `jwkfetch.WhitelistFunc(func(string) bool)` — custom predicate
 
 All the restrictive types fail closed: a URL that doesn't match any listed entry / pattern / predicate is rejected with a `WhitelistError`, for both the initial URL and every redirect target. Whitelist rejections can be detected with `errors.Is(err, jwkfetch.WhitelistError())`.
 
+> **Anchor your `RegexpWhitelist` patterns.** Patterns are **not** anchored for you, so a naive pattern matches anywhere in the URL and can allow far more than you intend. `example\.com` also matches `https://example.com.attacker.com/evil` and `https://attacker.com/?redirect=https://example.com` — a whitelist bypass that hands an attacker SSRF or key substitution. Anchor the start with `^`, escape the dots (`\.`), and terminate the host with `/`:
+>
+> ```go
+> // BAD — matches "example.com" anywhere in the URL
+> jwkfetch.NewRegexpWhitelist().Add(regexp.MustCompile(`example\.com`))
+>
+> // GOOD — anchored to scheme + host
+> jwkfetch.NewRegexpWhitelist().Add(regexp.MustCompile(`^https://example\.com/`))
+> ```
+>
+> Use `^https://example\.com$` to allow the bare origin with no path, and `^https://example\.com(:\d+)?/` to also allow an explicit port. Prefer `MapWhitelist` whenever the set of URLs is known up front.
+
 The `Whitelist` concept applies to `Client` only. `Cache` has no `Whitelist` field — it's a cache, and the set of URLs it will ever contact is exactly the set you passed to `Register`. Trying to pass `WithWhitelist` to `NewCache` is a compile-time error.
 
 See the [`jwkfetch` section of the extensions doc](./10-extensions.md#http-jwk-set-retrieval-jwkfetch) and the [module README](https://github.com/jwx-go/jwkfetch) for the full API reference, including allowlist patterns and the regex footguns to avoid.

docs/10-extensions.md

@@ -808,6 +808,8 @@ Policy options (`WithHTTPClient`, `WithMaxBodySize`, `WithParseOptions`) work fo
 
 See the [module README](https://github.com/jwx-go/jwkfetch) for the full API reference and whitelist types (`InsecureWhitelist`, `BlockAllWhitelist`, `MapWhitelist`, `RegexpWhitelist`, `WhitelistFunc`).
 
+`RegexpWhitelist` patterns are **not** anchored for you. A naive pattern like `example\.com` matches anywhere in the URL, so it also allows `https://example.com.attacker.com/evil` and `https://attacker.com/?redirect=https://example.com` — a whitelist bypass that reopens the SSRF / key-substitution hole the whitelist was meant to close. Anchor the start with `^`, escape the dots (`\.`), and terminate the host with `/` — e.g. `^https://example\.com/`, or `^https://example\.com$` for the bare origin. Prefer `MapWhitelist` when the URL set is known up front.
+
 ---
 
 # Filters and Introspection (jwxfilter)