docs(config): record the hop-count residual, and pin it with a test #35

Merged

jlxq0 merged 1 commit from docs-hops-residual into main

2026-08-27 04:30:38 +00:00

jlxq0 commented

2026-08-27 04:28:31 +00:00

Owner

Found by Codex against carddav-mcp's diff. Applies identically there, to jmap-mcp and to webmail, because the residual is in the topology rather than in any implementation.

The residual

A caller reaching the Cilium gateway directly, bypassing the edge, supplies its own X-Forwarded-For. Envoy appends the caller's address, so the chain is two long, len < hops never fires, and two hops selects the string the caller wrote.

No single hop count is correct for both paths. The edge path wants 2, the direct path wants 1, so choosing either forges one of them. The mitigation is that only one path is supposed to exist, which is a fact about the cluster that nothing in this repository can assert, and the constant now says that rather than implying the value is safe on its own merits.

The 109-request measurement could not see it. It measured the path a real client takes, which is the only path a real client takes. The residual is the one it cannot reach, and that belongs beside the number rather than leaving the number to read as complete.

What I measured, and it does not settle the mitigation

cilium-gateway-web   LoadBalancer   203.24.209.5, 2001:df7:2b40:1::102
listeners            http HTTP:80 hostname=*     no TLS listener
203.24.209.5:80      no answer from this machine (curl exit, no HTTP status)
caldav-mcp.kampong.social -> 203.24.209.8         the edge, not the gateway

One vantage, one moment. A single failure cannot separate filtered from unrouted from not-listening-on-this-path, and an HTTPS-upgrading fetcher cannot probe it from off-net at all, because there is no TLS listener to reach. The addresses being public shifts the burden; it does not discharge it. The measurement Clark was asked for is still the one that answers this.

The test

a_direct_caller_bypassing_the_edge_can_forge_the_recorded_address pins the forged selection so the residual is visible in the code rather than only in a comment, and asserts the same chain resolving differently at one hop, which is what makes "no single value is right" concrete rather than a claim.

Gates green: fmt, clippy -D warnings, 123 + 9 tests. No behaviour change and no release needed.

Found by Codex against `carddav-mcp`'s diff. Applies identically there, to `jmap-mcp` and to `webmail`, because the residual is in the topology rather than in any implementation. ## The residual A caller reaching the Cilium gateway directly, bypassing the edge, supplies its own `X-Forwarded-For`. Envoy appends the caller's address, so the chain is two long, `len < hops` never fires, and two hops selects the string the caller wrote. **No single hop count is correct for both paths.** The edge path wants 2, the direct path wants 1, so choosing either forges one of them. The mitigation is that only one path is supposed to exist, which is a fact about the cluster that nothing in this repository can assert, and the constant now says that rather than implying the value is safe on its own merits. **The 109-request measurement could not see it.** It measured the path a real client takes, which is the only path a real client takes. The residual is the one it cannot reach, and that belongs beside the number rather than leaving the number to read as complete. ## What I measured, and it does not settle the mitigation cilium-gateway-web LoadBalancer 203.24.209.5, 2001:df7:2b40:1::102 listeners http HTTP:80 hostname=* no TLS listener 203.24.209.5:80 no answer from this machine (curl exit, no HTTP status) caldav-mcp.kampong.social -> 203.24.209.8 the edge, not the gateway **One vantage, one moment.** A single failure cannot separate filtered from unrouted from not-listening-on-this-path, and an HTTPS-upgrading fetcher cannot probe it from off-net at all, because there is no TLS listener to reach. **The addresses being public shifts the burden; it does not discharge it.** The measurement Clark was asked for is still the one that answers this. ## The test `a_direct_caller_bypassing_the_edge_can_forge_the_recorded_address` pins the forged selection so the residual is visible in the code rather than only in a comment, and asserts the same chain resolving differently at one hop, which is what makes "no single value is right" concrete rather than a claim. Gates green: fmt, clippy `-D warnings`, 123 + 9 tests. No behaviour change and no release needed.

jlxq0 added 1 commit

2026-08-27 04:28:31 +00:00

docs(config): record the hop-count residual, and pin it with a test

CI / cargo (pull_request) Successful in 1m2s

Details

CI / docker (pull_request) Successful in 49s

Details

88db14369f

A caller reaching the Cilium gateway directly, bypassing the edge, supplies its
own X-Forwarded-For; Envoy appends the caller's address, so the chain is two
long, len < hops never fires, and two hops selects the string the caller wrote.

No single hop count is correct for both paths: the edge path wants 2 and the
direct path wants 1, so choosing either forges one of them. The mitigation is
that only one path is supposed to exist, which is a fact about the cluster that
nothing here can assert, and the constant now says so rather than implying the
value is safe on its own merits.

The 109-request measurement could not see this. It measured the path a real
client takes, which is the only path a real client takes, and the residual is
the one it cannot reach.

Measured from here and recorded as not conclusive: cilium-gateway-web holds
public addresses with a single HTTP:80 listener and no TLS, and that address did
not answer from this machine. One vantage and one moment cannot separate
filtered from unrouted, and the absent TLS listener means an HTTPS-upgrading
fetcher cannot probe it from off-net either. Public addresses shift the burden
without settling it.

The test pins the forged selection so the residual is visible in the code rather
than only in a comment, and shows the same chain resolving differently at one
hop, which is what makes "no single value is right" concrete.

Found by Codex against carddav-mcp's diff. Applies identically there, to
jmap-mcp and to webmail.

jlxq0 merged commit a6ae4bdae9 into main

2026-08-27 04:30:38 +00:00

jlxq0 deleted branch docs-hops-residual

2026-08-27 04:30:38 +00:00

jlxq0 referenced this pull request from a commit

2026-08-27 04:30:38 +00:00

Merge pull request 'docs(config): record the hop-count residual, and pin it with a test' (#35) from docs-hops-residual into main