fix(web): honor X-Forwarded-* so the real client IP reaches the pipeline

[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 (cfde65cd): 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 #1334. That PR was closed automatically on 2026-09-14, when the head fork
was deleted. It reopened at e7dbe6bc, and review has added commits on top since then (the
commit list above is the current one). The earlier review history stays on #1334.

---

Fixes audit finding API-02.

Problem

UseHeroPlatform never called UseForwardedHeaders, so behind the reverse proxy (Caddy / cloudflared) Connection.RemoteIpAddress was always the proxy's container IP. Consequences:

• Rate limiting collapses — the anonymous auth policy and the global IP limiter (RateLimiting/Extensions.cs) partition by ip:{RemoteIpAddress}, so every request shares one bucket. One anonymous spike throttles every tenant's login; per-origin brute-force protection is gone.
• Audit / session IPs are useless — RequestContextService.IpAddress (persisted on UserSession, audit trails) records the proxy IP for every request.

Fix

• New TrustedProxyOptions (config section TrustedProxyOptions): KnownProxies (IPs), KnownNetworks (CIDRs) and ForwardLimit, bound from configuration.
• Register ForwardedHeadersOptions — X-Forwarded-For + X-Forwarded-Proto. Trust is bound to the configured ingress proxies/networks; forwarded headers from any other source are ignored, so a client reaching the app directly cannot forge its IP/scheme. When nothing is configured, the loopback-only default is restated, not inherited: the trust list is cleared first and rebuilt every time, because a host started with ASPNETCORE_FORWARDEDHEADERS_ENABLED=true registers ForwardedHeadersOptionsSetup, which empties both lists before this runs. An empty list is not "trust nobody" in ForwardedHeadersMiddleware — it only validates the peer when at least one entry exists, so empty means the app would rewrite RemoteIpAddress from an X-Forwarded-For sent by any caller at all. ForwardLimit follows config so a multi-hop ingress (cloudflared → Caddy → app) unwinds the right number of hops.
• Call app.UseForwardedHeaders() first in UseHeroPlatform, before HTTPS redirect / rate limiting / auth / audit read the client IP or scheme.
• appsettings.json / appsettings.Production.json carry an empty TrustedProxyOptions section; prod sets the ingress CIDR(s) + hop count to activate real-client extraction (secure-by-default: no config ⇒ no trust).
• A malformed KnownProxies / KnownNetworks entry now fails with an InvalidOperationException naming the config path and the offending value, instead of a bare FormatException.

Tests

ForwardedHeadersIpTests (integration):

• happy path — a token-issue request arriving from the trusted proxy carrying X-Forwarded-For persists the real client IP on the UserSession.
• negative — the same header from an untrusted source is ignored; the persisted IP is the connection IP, never the attacker-supplied forwarded value. The test also sends the identical header from the trusted proxy and asserts that arm is honored, so the trust boundary is what it pins rather than an outcome that would hold with forwarded-header processing absent entirely.

TestServer has no socket, so the connection IP is stamped via a test-only startup filter (X-Test-Remote-Ip).

TrustedProxyOptionsBindingTests (unit) pins the TrustedProxyOptions → ForwardedHeadersOptions binding through AddHeroPlatform: the loopback-only default when the section is absent, KnownProxies + ForwardLimit binding, and both malformed-entry messages. The host builder runs with DisableDefaults so an ambient TrustedProxyOptions__* on the machine or CI runner can't change what "nothing configured" resolves to.

ForwardedHeadersHostDefaultsTests (unit) covers the one host shape the binding tests cannot reach: it builds through WebApplication.CreateBuilder with FORWARDEDHEADERS_ENABLED set, asserts ForwardedHeadersOptionsSetup is actually registered so the test cannot pass vacuously, and then asserts the resolved lists equal a fresh ForwardedHeadersOptions. Red with the Clear() and the restatement reverted, green with them in place.

Full suite green locally: 1773 passed / 1 skipped / 0 failed (Integration.Tests 735/1, Architecture.Tests 51). Re-run after the trust-list fix: solution build under TreatWarningsAsErrors exit 0, Framework.Tests 138/138, Integration.Tests (Security filter) 9/9, Integration.Middleware.Tests 5/5.

⚠️ Touches protected src/BuildingBlocks (Golden Rule #4)

This modifies src/BuildingBlocks/Web/Extensions.cs and adds src/BuildingBlocks/Web/TrustedProxy/TrustedProxyOptions.cs — the shared framework wiring, so it needs maintainer sign-off. The change is confined to forwarded-headers registration + the new options type; no existing behavior of other building blocks is altered. Sign-off granted in review on 2026-08-08.

Changed after the last review

75475d30 was what was approved. 85aa03b3 adds, and has not been reviewed by anyone:

• the TryParse + named-message change (the non-blocking nit from the approving review);
• TrustedProxyOptionsBindingTests;
• the extra assertion in the untrusted-source integration test.

No production behavior changes beyond the error message for malformed config.

The dependency bumps that restore needs

dotnet restore src/FSH.Starter.slnx fails on main under TreatWarningsAsErrors — not because of
this PR — so the branch carries the Testcontainers 4.14.0 and SourceLink bumps that clear it, in the
same shape as the PR that owns them.

It used to carry an explicit SSH.NET pin too, on the stated grounds that bumping Testcontainers
would not help. That was wrong: 4.14.0 declares SSH.NET >= 2026.0.0, and with the pin removed
dotnet restore --force reports zero NU1902/NU1903 and exits 0. The pin is gone.

Notes

Docs in fullstackhero/docs#237 (rebased, MERGEABLE): changelog entry + a new "Reverse proxy & forwarded headers" section (CORS & headers page) documenting TrustedProxyOptions, and a production-checklist note that honoring X-Forwarded-Proto requires configuring the trusted ingress.

Two things deliberately left out of this PR:

• ForwardLimit validation — it's a plain int where the framework's own option is int?. A negative value throws OverflowException inside ForwardedHeadersMiddleware on every request (500s across the board, since UseForwardedHeaders runs after UseExceptionHandler), and 0 silently disables processing. Measured against the real middleware; filed separately as TrustedProxyOptions.ForwardLimit is an unvalidated int: a negative value 500s every request, zero silently disables forwarded headers #1358 rather than widening this PR.
• X-Forwarded-Host — intentionally excluded from the flags list; the doc-comment note about why is the follow-up you called out in review.

---

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.

---

Two corrections in the tests themselves.

ForwardedHeadersIpTests read back "the newest session" - it ordered UserSessions by
CreatedAt and took the first row of the whole table. That is safe only because the collection
runs serially; any other test in it issuing a token leaves the assertion reading a row this request
did not create. Ordering is not what makes it correct either: CreatedAt comes from a single
TimeProvider.System read and two issues can land on the same tick, and Id is a random Guid,
so a tiebreak on it picks deterministically but not necessarily correctly. 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. 2/2 green; inverting the new filter to
before.Contains(s.Id) fails 2/2.

The factory comment overstated what these tests cover. Its
PostConfigure<ForwardedHeadersOptions> overwrites the flags, the forward limit and both trust
lists wholesale, so what runs against TestConstants.TrustedProxyIp is the real middleware and
the real placement of UseForwardedHeaders, not the TrustedProxyOptions binding that feeds them
in production. That binding has its own gate in
Framework.Tests/Web/TrustedProxyOptionsBindingTests, and the comment says so now rather than
reading as if this pinned production.

[marcelo-maciel]

Note for whoever merges this: the same forwarded-headers trust-list fix is carried, content-identical, on #1386. The two PRs touch the same block in AddHeroPlatform for different reasons (this one rebuilds the trust list, #1386 rejects a ForwardLimit below 1), so the commit is duplicated deliberately. Whichever merges first makes the other's copy drop as an empty cherry-pick; no manual reconciliation needed.

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.

[marcelo-maciel]

Pairing note, for whoever picks these up. #1386 is cut from this branch and is the only PR that depends on it. Measured rather than described: git diff a24f8d84 99e55145 --stat is 3 files, 35 insertions, 0 deletions, all of it ForwardLimit (the option, its binding in Extensions.cs, and TrustedProxyOptionsBindingTests).

Merge this one first and that PR collapses to exactly those 35 lines. Merge that one first and this one has nothing left to add. Either order works mechanically: both carry the same two infra carve-outs as identical hunks, so whichever lands second drops them as an empty cherry-pick.

[marcelo-maciel]

Pairing note, re-measured. The numbers in my earlier comment went stale: both branches have
moved since (ForwardLimit doc copy on #1386, and the session-read fix above, which is cherry-picked onto
that branch so the two stay content-identical where they overlap).

At the current heads, 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.

The recommendation is unchanged. Merge this one first and that PR collapses to exactly those 43
lines. Merge that one first and this one has nothing left to add. Either order works mechanically:
everything they share is carried as identical hunks, so whichever lands second drops them as an
empty cherry-pick.