fix(web): reject a trusted-proxy ForwardLimit below 1 at startup

[marcelo-maciel]

Closes #1358.

TrustedProxyOptions.ForwardLimit was passed straight through to ForwardedHeadersOptions with no validation, so two values that nobody means are accepted in silence.

What the two bad values actually do

Measured on .NET 10 by starting a real host with UseExceptionHandler + UseForwardedHeaders in the same order UseHeroPlatform mounts them, and issuing one request:

config	request	result
ForwardLimit = -1	no forwarded headers at all	HTTP 500
ForwardLimit = 0	X-Forwarded-For from a trusted proxy	HTTP 200, but RemoteIpAddress and scheme unchanged

Negative is the sharp edge. In ApplyForwarders, entryCount starts at 0, and there is no early return when no forwarded headers are present. 0 > -1 is true, so entryCount is clamped to -1 and new SetOfForwarders[entryCount] throws OverflowException. Because UseForwardedHeaders() sits after UseExceptionHandler(), that is a 500 on 100% of traffic rather than a startup failure a deploy smoke test would catch. -1 is a plausible thing for an operator to write when reaching for "unlimited hops", precisely because the underlying framework option expresses exactly that via null.

Zero is the quiet one. entryCount > 0 truncates to 0, the consume loop runs zero iterations, and forwarded headers stop being processed with no error and no log, reinstating the original symptom (proxy IP in rate-limit partitions and audit trails) while the config still reads as configured.

The fix

Reject anything below 1 where the malformed KnownProxies / KnownNetworks entries are already rejected, with a message naming the setting and the offending value. Verified by execution that a throw from inside that Configure<ForwardedHeadersOptions> delegate surfaces during startup (StartAsync fails, the host never serves), so a bad hop count fails the deploy instead of the traffic.

Scope

• Extensions.cs: the guard, at the top of the delegate so it also covers the case where no proxies or networks are configured.
• TrustedProxyOptions.cs: the XML doc records the minimum.
• TrustedProxyOptionsBindingTests.cs: a theory over -1 and 0, mirroring the two existing "name the setting" tests. Both go red with the guard reverted (checked), and Framework.Tests is 139/139 green with it in place.
• Docs: docs(security): forwarded-headers trusted-proxy config (TrustedProxyOptions) docs#237 carries the matching wording (reverse-proxy section, production checklist, changelog).

A second commit answers the other note you left for the follow-up on this same type: the class doc now records that only X-Forwarded-For and X-Forwarded-Proto are honoured, that leaving X-Forwarded-Host out is deliberate (rewriting Request.Host from a header is a host-header injection primitive, and the three Identity endpoints that build a public URL from the request would mail links pointing wherever the header said), and that the trade-off is Request.Host keeping the internal host behind a proxy. Doc comment only, no behaviour change; docs#237 carries the same note.

Nothing in deploy/, the AppHost or either appsettings sets a value below 1 (both ship 1), so this changes nothing for a correct deployment. It does turn an existing 0 into a hard startup failure, which is the intent.

Two notes

This is stacked on #1334, which introduces TrustedProxyOptions: the branch is cut from fix/web-forwarded-headers, so the diff against main shows that PR's commits until it merges. Raised separately so a follow-up doesn't widen an approved security PR.

This keeps ForwardLimit an int, so "unlimited" stays inexpressible. The larger shape from #1358, making it int? to mirror the framework's null-means-unlimited while still rejecting <= 0, changes the options contract and is still on the table if you prefer it. Say the word and I will send that instead.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.