[jonchurch]

This PR introduces the trust proxy spoke page for the security hub.

Suffice to say, I learned just how much I did not understand trust proxy while writing this!

Unrelated to this PR, but I do feel pretty strongly that we should rework this setting slightly in v6, specifically dropping the trust proxy: true option as I am convinced now that it is a footgun. We should also push users to setting an address range and not a hop count for this setting, which I realized very late into the process of writing this documentation, and these docs now reflect that better advice.

This PR also tweaks the two hub items I had previously for trust proxy, in order to better reflect what I have learned developers should ask themselves to determine if they are correctly using this setting, and if they are using it w/ a correctly configured proxy.

The structure I went for here is what I expect to do for the rest of the spokes:

1. Introduce what Express does, and what goes wrong by default.
2. One section per hub item, opening with the concrete problem and then the fix, under an anchorable heading
3. What the setting or API can't do, and what the reader has to do elsewhere.
4. Related links to the reference material, so the spoke explains the risk and the existing guide stays the reference.

Feedback on structure is highly relevant here!

[netlify]

✅ Deploy Preview for expressjscom-preview ready!

Name	Link
🔨 Latest commit	89e2ba5
🔍 Latest deploy log	https://app.netlify.com/projects/expressjscom-preview/deploys/6aea4a37aba126cba4ba51a0
😎 Deploy Preview	https://deploy-preview-2535--expressjscom-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 96 (🔴 down 1 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[crandmck]

For reviewers' convenience, here are the rendered pages, which aren't actually linked from anywhere in the deploy preview site:

• Security checklist
• Proxies and client identity

[bjohansebas]

just a few minor comments; I’m not an expert on proxies.

[crandmck]

There's a fair amount to unpack here, and I'm going to have to come back to this with more detailed comments.

At a high level, I think we need to review and update the two other places that document trust proxy, linked in the "Related" section:

• API ref doc at https://github.com/expressjs/expressjs.com/blob/security-docs/src/content/api/5x/api/application/index.mdx#options-for-trust-proxy-setting
• "Express behind proxies": https://github.com/expressjs/expressjs.com/blob/security-docs/src/content/docs/en/5x/guide/behind-proxies.mdx

There is some duplication between these three docs, which is OK... IF there is a good reason for it:

• The API reference doc should have exhaustive detail of the trust proxy options (does it?), and let's make sure all the examples illustrate good practices as outlined in this doc. Also add a link FROM the API ref section to this new "spoke" page.
• What is the distinct purpose of "Express behind proxies"? Does it even make sense to keep that page, and if so, why? Let's just be very clear on its goal and then make sure its content speaks to that.

All three of these docs use CIDR notation in examples, with no explanation or references. While many developers may be familiar with it, we should at least say something like "We're assuming you're familiar with CIDR notation used for trust proxy option values" (with xref link). Also the API ref confusingly mixes IPv4 and IPv6 CIDR notation in the explanation of loopback, linklocal, and uniquelocal. This can easily be improved.

Finally, since the trust proxy setting is implemented using the proxy-addr package, for the sake of completeness, I think we should separately review https://github.com/jshttp/proxy-addr#readme to ensure there are no discrepancies with these docs. It's probably fine, but while we're here and this topic is fresh on our minds, it's worth at least a quick review IMO.

[crandmck]

Some clarifications and copy edits