How do you keep an authentication hook off a health-check endpoint without leaving other endpoints unprotected?

Almost every service needs one or two endpoints that answer without credentials — a liveness or readiness probe, a public metadata document, the endpoint that issues a token in the first place. The interview question is not whether you can make the probe return `200`; it is whether the mechanism you use to exempt it can exempt anything else by accident. ## Two ways to state the exemption **Structural (scope-based).** Split the route tree. One branch holds the handful of endpoints that are genuinely public; the other holds everything else and carries the authentication hook. The exemption is then a fact about where a route is registered, visible at the route declaration, and a new route is protected unless somebody deliberately puts it in the public branch. **Textual (exclusion list).** Keep one global hook and give it a list of paths to skip. The exemption is now a string comparison inside the hook, invisible from the route tree, and correct only to the extent that the comparison is correct. Both designs are deny-by-default in the sense that an unlisted new route is still protected, and that is why an exclusion list is far better than opting each route into authentication one at a time. The difference is the blast radius of a mistake: a structural mistake exposes the one route you misfiled, while a sloppy exclusion pattern can expose an entire subtree nobody was thinking about. ## How exclusion lists go wrong 1. **Prefix instead of exact match.** Skipping anything that *starts with* `/health` also skips `/health-admin`, `/healthz-internal` and `/healthcheck/debug/dump`. The rule looks like one endpoint and covers a family. 2. **Comparing the raw path before routing.** A hook attached before routing sees the request line as sent. The router may later normalise duplicate separators, resolve `..` segments, decode percent-encoding, strip a trailing slash or match case-insensitively. Any normalisation the router does and the hook does not is a gap: the two can disagree about which route this request is, and the hook's answer is the one that decides whether credentials are demanded. 3. **Query strings, matrix parameters and path parameters.** A comparison that forgets to strip everything after `?`, or that anchors on a path that contains a parameter segment, matches more or less than intended. 4. **Method blindness.** An exemption written for a read probe frequently exempts every method on that path, so a write to the same path arrives unauthenticated. 5. **Nobody audits the list.** It grows during incidents, entries outlive the endpoints they were added for, and the list is usually configuration rather than code, so no reviewer reads it. | Exclusion style | What it actually exempts | Failure mode | |---|---|---| | Prefix string, pre-routing | Every path sharing those leading characters | Silent over-exemption of a whole family | | Exact raw path, pre-routing | One spelling of one path | Normalisation and encoding mismatches with the router | | Matched route identity, post-routing | Exactly the route the router chose | Runs late, so unmatched paths never reach it | | Separate public branch | The routes deliberately registered there | Misfiling one route, visible in review | ## The safe recipe - Prefer **scope** to **string**: a public branch, a protected branch, authentication on the protected branch. - If a global hook must decide, decide **after routing**, on the route the router actually chose, so the hook and the router can never disagree about which endpoint this is. - **Anchor exactly** and include the method in the exemption, not just the path. - Keep the exempt set **small and enumerable**, and treat it as code subject to review, not as a configuration value. - Write the **test that enumerates it**: iterate the registered routes, call each without credentials, and assert that the set answering anything other than `401` is exactly the expected list. This is the control that actually catches regressions, because it fails when someone adds a route, not when someone remembers to check. - Remember the probe's own exposure: an unauthenticated endpoint should reveal nothing beyond liveness — no dependency details, no versions, no configuration. ## Why the opt-in alternative is worse It is tempting to conclude that since exclusion lists are risky, authentication should simply be attached per route. That inverts the default: every future endpoint is then public until someone remembers otherwise, and the failure is invisible because nothing in the code mentions the hook that is missing. Between an opt-out design with a carefully anchored exemption and an opt-in design with none, the opt-out design is the one whose accidents a test can enumerate.