test(api): verify HSTS and HTTPS redirection over real TLS, or record what is unverifiable (follow-up to #340) #344

Activity

1. mforce

   added this to the Phase 1.5 — Hardening milestone on Aug 1, 2026
2. mforce

   added

   enhancementNew feature or requestNew feature or request

   area:apiAPI/endpoint layerAPI/endpoint layer

   sliceThin vertical work itemThin vertical work item

   epic-15

   epic-1.5

   and removed

   epic-15

   on Aug 1, 2026
3. mforce

   added

   priority:tier1Gates first real usersGates first real users

   on Aug 31, 2026
4. mforce commented on Sep 13, 2026

   

   mforce

   on Sep 13, 2026

   Last edited by mforce

   OwnerAuthor

   More actions

   Some transport-level evidence on the HSTS half, from a deployed instance running behind a reverse proxy. It does not close this, but it narrows it.

   What was measured

   Requests sent directly to the app process, bypassing the proxy, so that only the app's own middleware could be responsible for the response:

   Request	Strict-Transport-Security
   GET /login, correct Host, no proto hint	absent
   GET /login, correct Host, X-Forwarded-Proto: https	present — max-age=31536000; includeSubDomains

   Both returned 200.

   What that settles

   app.UseHsts() is live in production, not inert:

   • the header is emitted, with exactly the value in CluckworkEdgeSecurityServiceCollectionExtensions.cs:23-27;
   • it is gated on scheme — absent when the request does not look like HTTPS, present when it does;
   • the forwarded-headers path feeding that decision works end to end against a real connection.

   That last point is the one worth recording, because it is the coupling #260's boot guard asserts and this issue notes has never been observed over a real connection: HSTS being inert behind an untrusted proxy. It is not inert here. The guard's premise holds in at least one real deployment.

   What it does not settle

   The wrong-host direction is untested. These probes sent the correct Host. The failure mode this issue names second — the header emitted for a host that should not receive a year-long client commitment — is exactly the ExcludedHosts behaviour, and nothing above touches it. That is the half where the one-way-door argument bites.

   This is an observation, not a test. It proves the behaviour today; it does nothing about the regression this issue exists to prevent. Change ExcludedHosts, or the forwarded-headers configuration, and SecurityHeadersTests still goes green. The gap described at SecurityHeadersTests.cs:139 is unchanged.

   UseHttpsRedirection was not exercised, and may not be reachable in a proxied deployment. Where the reverse proxy answers plaintext requests itself, the app never sees an HTTP request to redirect, so Program.cs:191 never runs in production. Worth deciding deliberately: if that middleware is unreachable wherever the app is deployed behind a terminating proxy, then testing its port-resolution path is lower value than this issue currently implies, and saying so is better than leaving it as untested-and-assumed-important.

   Why this raises the stakes rather than lowering them

   The obvious reading of the evidence above is reassuring: it works, so the risk is smaller. The opposite is true, and it took checking to find out.

   The deployment this was measured on has no second emitter. The edge in front of the app does not add Strict-Transport-Security of its own — the header reaching clients is the one produced by app.UseHsts(), forwarded unchanged. So the year-long client commitment rests entirely on this middleware and on the forwarded-headers path that decides whether a request counts as HTTPS.

   That makes both failure directions in the original description live rather than theoretical:

   • a regression in ExcludedHosts, the forwarded-headers configuration, or the trusted-proxy list removes HSTS completely, with nothing behind it and no signal that anything changed;
   • the coupling Deploy: production proxy-trust chain unsolved — silently disables #144 HSTS and the #143 per-IP login limiter #260's boot guard asserts is not defence in depth here, it is the only defence.

   I had assumed an edge-level fallback existed before checking. It did not. Worth stating plainly because anyone reading a green production response would make the same assumption.

   Suggestion

   Option 1 for the wrong-host case specifically. That assertion needs a Host header rather than a certificate, so it avoids the self-signed-certificate machinery entirely, and it covers the direction with the irreversible consequence.

   Option 2 for what genuinely cannot be reached in-process, recorded explicitly at SecurityHeadersTests.cs:139 rather than left as the current comment.

   UseHttpsRedirection is worth a separate decision. Where a terminating proxy answers plaintext itself, Program.cs:191 never runs, so its port-resolution path may be untestable and unreachable. If that holds wherever this is deployed, descoping it from here is more honest than carrying it as an untested requirement.

   Happy to re-run the probes against any specific header or host combination if that would help the decision.
5. mforce commented on Sep 13, 2026

   

   mforce

   on Sep 13, 2026

   OwnerAuthor

   More actions

   Reviewed in the 2026-09-13 issue cleanup. Decision: keep at priority:tier1 and build the real-TLS harness — the escape hatch this issue's own title allows ("or record what is unverifiable") is explicitly not being taken.

   Rationale: HSTS is a one-way door for clients. Once a browser caches max-age=31536000; includeSubDomains it refuses plaintext for a year, and both failure directions — not emitted when it should be, emitted on the wrong host or scheme — are currently unobservable at the transport. Writing that down is not the same as knowing which way it fails.

   This is now the only open priority:tier1 issue in the repo. #244 closed (audit complete, findings dispositioned), #268 deferred to #793, #272 closed as an accepted risk. So this is the next production-readiness build.

   Scope is unchanged from the body above — option 1: ConfigureKestrel with a runtime-generated self-signed certificate (never committed, same rule as TestJwtKeys), an HttpClientHandler trusting exactly that certificate, a hand-fixed base address, and HstsOptions.ExcludedHosts.Clear() in the test factory so loopback is not skipped. Assert the header present on HTTPS, absent on plain HTTP, and that UseHttpsRedirection issues the 307.

   Note the boundary while building it: this verifies the application emits the header correctly. Whether the production edge terminates TLS and forwards a scheme the app trusts is a deploy concern, tracked in cluckwork-deploy#8 and coupled to RateLimiting:TrustedProxies via the #260 boot guard.
6. mforce

   removed

   epic-1.5

   on Sep 13, 2026
7. mforce

   closed this as completedin #821on Sep 13, 2026