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

[marcelo-maciel]

Carries two infrastructure fixes that are not this PR's topic. Without them CI cannot even reach this PR's code.

• Dependency bump: Microsoft.SourceLink.GitHub to 10.0.401 and Testcontainers to 4.14.0, clearing NU1902/NU1903 so restore succeeds. Those are the versions #1375 (SourceLink) and #1369 (Testcontainers) carry: this hunk is the union of the two, plus one comment per pin naming the advisory it answers.
• MinIO (6816b7d7): minio/minio is gone from Docker Hub, so every Testcontainers-backed integration test dies on the image pull. Pulls from quay.io on a pinned tag instead. Same fix as #1388.

The MinIO hunk is byte-identical to #1388. The dependency hunk is not byte-identical to #1375 or #1369, which each carry half of it without the comments, but it is identical across all twelve PRs in this series: src/Directory.Packages.props resolves to the same blob (854deb95) at every head. Either way they merge in any order, and these copies can be dropped once the PRs that own them land.

Reopened from #1365. That PR was closed automatically on 2026-09-14, when the head fork
was deleted. It reopened at cb62b102, and review has added commits on top since then (the
commit list above is the current one). The earlier review history stays on #1365.

---

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).
• Also carries the trust-list rebuild from #1379, content-identical, because both change the same delegate and either merge order would otherwise conflict. Whichever merges first makes the duplicate drop as an empty cherry-pick.

Framework.Tests is 140/140 green with everything 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 #1379, 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. (#1334 was the closed original; #1379 is the live one, reopened after the fork was deleted.) Raised separately so a follow-up doesn't widen an approved security PR. Merge #1379 first: this PR then collapses to its own delta, and merging it first instead leaves #1379 with nothing to add. Measured rather than described, at the current heads (d7fb51af and 00ec8e8a): git diff d7fb51af 00ec8e8a --stat is 3 files, 43 insertions, 0 deletions, all of it ForwardLimit - the option, its binding in Extensions.cs, and TrustedProxyOptionsBindingTests.

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.

---

Infra carve-outs, corrected after review. Two things in the out-of-topic hunks were wrong and
are fixed on the branch:

• The MinIO carve-out only moved minio/minio to quay.io. minio/mc is gone from Docker Hub too
  (hub.docker.com/v2/repositories/minio/mc/ answers 404) and it is what minio-init runs, so both
  dotnet run --project src/Host/FSH.Starter.AppHost and docker compose up died on the pull and the
  fsh bucket was never created. Now pinned to the same quay tag #1388 uses.
• The SSH.NET pin is gone: it pinned nothing. Its own comment claimed bumping Testcontainers
  does not help, but 4.14.0 — which this branch also carries — declares SSH.NET >= 2026.0.0.
  Measured rather than argued: with the pin removed, dotnet restore src/FSH.Starter.slnx --force
  reports zero NU1902/NU1903 and exits 0. (The MessagePack pin next to it stays; removing that one
  does bring its advisory straight back.)

With both applied, deploy/docker/docker-compose.yml and src/Directory.Packages.props are now
genuinely byte-identical to #1388 (git diff --exit-code, checked today), which the earlier claim
was not.

---

One more from review: the doc covered the wrong mistake. It explained what setting ForwardLimit
too low costs and rejects the two invalid values, but said nothing about the direction an operator
actually drifts in, rounding it up "to be safe". The middleware trusts one entry per hop counting
from the right and only ever checks the immediate peer, so a limit of 2 behind a single proxy
discards what the proxy appended in favour of what the client sent: the caller picks its own
RemoteIpAddress, and every IP-based rate limit and audit entry follows it. That is now on the
option itself, where someone changing the number will read it.

Carried from #1379, so the two do not drift. ForwardedHeadersIpTests read back "the newest
session" - it ordered UserSessions by CreatedAt and took the first row of the whole table,
which is safe only because the collection runs serially. It now snapshots the session ids before
the request and takes the one that was not there, with ShouldHaveSingleItem asserting the
correlation instead of assuming it. The factory comment that read as if the test pinned the
TrustedProxyOptions binding says what it actually covers. Same change, cherry-picked from that branch and
byte-identical here: git diff d7fb51af 00ec8e8a --stat lists only the three ForwardLimit
files, so whichever merges second drops it as an empty cherry-pick. 2/2 green here; inverting the new filter
to before.Contains(s.Id) fails 2/2.

[marcelo-maciel]

Note for whoever merges this: this branch also carries the forwarded-headers trust-list fix from #1379, content-identical, because both change the same block in AddHeroPlatform and either merge order would otherwise leave the other conflicting. Whichever merges first makes the duplicate drop as an empty cherry-pick.

Verified by content rather than by SHA: the added and removed lines of both commits are identical, differing only in blob index and hunk offset (the ForwardLimit guard above shifts the hunk by ten lines).