Update Fetch Metadata positioning

[mkhanas]

As agreed in #1803 :

• Updated Fetch Metadata positioning

• Extended core guidance to mention Fetch Metadata request headers (Sec-Fetch-*) as an alternative to CSRF tokens for state-changing requests.

• Added clarification that developers can use CSRF tokens or Fetch Metadata depending on project needs and client compatibility.

• In case of a new Cheat Sheet, you have used the Cheat Sheet template.

• All the markdown files do not raise any validation policy violation, see the policy.

• All the markdown files follow these format rules.

• All your assets are stored in the assets folder.

• All the images used are in the PNG format.

• Any references to websites have been formatted as [TEXT](URL)

• You verified/tested the effectiveness of your contribution (e.g., the defensive code proposed is really an effective remediation? Please verify it works!).

• The CI build of your PR pass, see the build status here.

AI Tool Usage Disclosure (required for all PRs)

Please select one of the following options:

• I have NOT used any AI tool to generate the contents of this PR.
• I have used AI tools to generate the contents of this PR. I have verified
  the contents and I affirm the results. The LLM used is [llm name and version]
  and the prompt used is [your prompt here]. [Feel free to add more details if needed]

This PR fixes issue #1803.

[nickchomey]

Thanks for taking the lead on this! You'll definitely want a review by someone more knowledgeable (eg. @FiloSottile), but here's some feedback.

I believe it was agreed in #1803 that "Fetch metadata is a complete and robust fix for CSRF, not just defense in depth." However, this PR reads unnecessarily precautionary.

• First, i think it would be easier for people to review if you didn't move the Fetch Metadata headers section. The whole thing is a diff, rather than just specific wording. If it should be moved, that could be done before merging the PR, after approval of the language.
• Various places call it a "primary" protection, which still suggests it is defense in depth. Such language is not used with respect to the CSRF tokens sections
• The concerns about browser compatibility are vastly overstated. It has 97.6% coverage, which is practically 100%. Only some ancient Chrome, IE, and 2+ year old Safari (which surely will be updated soon enough) are unsupported. The real security risk is anyone using these browsers - you'd be doing them a favour by returning a message saying "update your browser if you want to use this site". Moreover, Origin headers - which are used by the Go implementation - have effectively 100% coverage
• non-browser (eg curl) request support is a non-issue
• It is referred to as "relatively new", "simple" etc - this undermines its robustness.
• Using Origin headers as the first fallback should be strongly/mandatorily recommended. In fact, it could link to the Go CrossOriginProtection source code as a model implementation.
• The limitations and gotchas section was not modified at all. Again, browser compatibility is not an issue. There's no substantiation of the concerns about blocking legitimate CORS or 3rd party flows - either these concerns should be listed, along with mitigations, or not mentioned at all. I dont see how it is a limitation that it needs to work with https - that's simply good practice. In fact, HSTS should be encouraged.

[mkhanas]

Hi, @nickchomey! Thanks a lot for the thorough review and for the pointers, here some thoughts

this PR reads unnecessarily precautionary

You’re right — that’s on me. The phrasing ended up sounding more precautionary than intended; it reflects my personal stance on the topic

First, i think it would be easier for people to review if you didn't move the Fetch Metadata headers section. The whole thing is a diff, rather than just specific wording. If it should be moved, that could be done before merging the PR, after approval of the language.

I moved the Fetch Metadata section because we’re proposing it be treated as one of the primary mitigations. If we leave it buried, readers may miss that change.

Various places call it a "primary" protection, which still suggests it is defense in depth. Such language is not used with respect to the CSRF tokens sections

I understand your point — my intent was to reflect the current state of adoption and confidence rather than to imply it’s inherently secondary.

As I mentioned in the issue discussion, Fetch Metadata is still relatively new compared to traditional CSRF mitigations. While it’s an elegant and highly effective mechanism for modern browsers, it hasn’t yet gone through the same long cycle of real-world testing, widespread deployment, and maturity that CSRF tokens have. In security, mechanisms often take time to earn broad trust — a good parallel might be the SameSite cookie attribute, which was proposed years before browsers began enforcing it by default and before most frameworks integrated it as a standard protection.

That said, I’m open to rephrasing. Which parts stand out to you most?

The concerns about browser compatibility are vastly overstated.

My point wasn’t to question the coverage but rather to acknowledge that, as a community, we can’t dictate every project’s goals or constraints.

If the software targets modern browsers, then Fetch Metadata is clearly the way to go. However, as we discussed, for environments where these headers aren’t yet supported, developers will still need to rely on CSRF tokens — even if that feels less practical.

non-browser (eg curl) request support is a non-issue

Agree

The limitations and gotchas section was not modified at all.

Regarding the note on blocking legitimate CORS or third-party flows — I intentionally kept it, just to highlight that these areas need extra care, since enabling Fetch Metadata protections without considering such flows could break them. The relevant mitigations are already covered in section 3.2 (“How to treat Fetch Metadata headers on the server-side”) section.

In fact, HSTS should be encouraged.

Good catch! I hadn’t considered mentioning it explicitly, but that’s a great recommendation and would indeed address the “potentially trustworthy” issue as well. I’ll incorporate that.

[nickchomey]

I can't help but think that your response was written almost completely by AI... It makes me wary of collaborating any further on this as its not clear to me that a thoughtful human is actually on the other side...

Perhaps incorporate my suggestions into a new commit and we can see where we're at then

[mkhanas]

I don’t like where this is headed, especially with things starting to feel a bit personal.

It feels like the focus is mainly on getting Fetch Metadata headers recognized as the primary CSRF protection and moving away from CSRF tokens entirely, which doesn’t sit well with me. That’s just my personal view, but I worry it could lead to CSRF tokens falling out of use altogether, since most developers would naturally choose the simpler Fetch Metadata approach.

I get your point though, and as I mentioned in my previous comment, this section reflects my own perspective. It’s admittedly an awkward position — I don’t have solid evidence that Fetch Metadata isn’t as robust as you’d like to present it, but at the same time, “lack of evidence doesn’t mean lack of existence” isn’t a strong argument either. I’m just not sure how to balance both sides — treating Fetch Metadata as “the best” while still keeping CSRF tokens relevant.

[mkhanas]

Feel free to open your own PR — I’m not comfortable positioning Fetch Metadata as THE MAIN CSRF defense.

[nickchomey]

These last 2 comments, and those from the previous issue, have no hint of AI.

I don't think anyone was ever advocating for fetch metadata being THE primary csrf protection. Just that it is suitable as A Primary/standalone protection, if a few niche caveats and associated mitigation are presented.

 I worry it could lead to CSRF tokens falling out of use altogether, since most developers would naturally choose the simpler Fetch Metadata approach.

Though, this is precisely what people are ultimately advocating for - CSRF tokens are a headache (and therefore much more likely to implemented poorly due to human error). They also make caching extremely difficult.

I see no conflict or even issue with effectively saying "these are two worthy options. Take your pick". Most would, indeed, eventually pick fetch metadata, and tokens would eventually be forgotten. What's wrong with that? That's just another example of good technical progress for the web platform.

[mkhanas]

These last 2 comments, and those from the previous issue, have no hint of AI.

I’m not a native speaker, so in the first comment I was just trying to politely make my point. When I saw you didn’t like my style, I just dropped it :)

I see no conflict or even issue with effectively saying "these are two worthy options. Take your pick". Most would, indeed, eventually pick fetch metadata, and tokens would eventually be forgotten.

I know, and that makes perfect sense. I was just trying to play it safe and leave room for discussion, something like:
“If your app is intended to be used only on newer versions (provide versions that support Fetch Metadata headers), go with Fetch Metadata. If for some reason you still need to support older versions (shame on you), use CSRF tokens.”

Let’s do it this way: I’ll fix the language according to the suggestions in your first message, add the missing bits about HSTS, keep the Metadata section at the beginning (so we don’t have to open another PR to move it later), and then ask for a review from the rest — especially the Go folks, where this all started.

[mkhanas]

Hi, @nickchomey
Tried to incorporate most of your suggestions. Most changes are clarifications, wording improvements, and notes about compatibility and HSTS. Feel free to take a look when you have a chance

[jmanico]

I’m not comfortable positioning Fetch Metadata as THE MAIN CSRF defense

As the founder of the cheatsheet series and project lead, I agree 100%.

Fetch Metadata s a very useful first line defense against CSRF, but it is not safe to rely on it alone for all production workloads. Use it as part of defense-in-depth. Combine it with SameSite cookies, origin checks, and per-request CSRF tokens.

The spec’s notion of “user-initiated” navigation and some navigation flows (top-level navigations, prerender/prefetch, PaymentRequest-like flows) can result in values that permit requests you’d expect to be blocked; attackers can sometimes craft flows to exploit those behaviors. There is research showing odd corner cases.

So let's revisit this in a year, but for now, Fetch Metadata is one defense with limitations and is not the only be-all defense for CSRF.

Anywhere we say this, I want it softened. And again, we can revisit this in a year.

[artis3n]

First time commenter, but I am very motivated by making security simple and I like the Sec-Fetch-Site pattern very much. Added some recommendations about structuring this page.

[artis3n]

Should this section be focused on the subset of Sec-Fetch-* headers that are used to protect against CSRF? (Just Sec-Fetch-Site and Origin/Host header validation, and link off to MDN or something "if you'd like to learn more about what other Sec-Fetch-* headers are available for other purposes, see..."

[mkhanas]

Hi @artis3n, sorry for the wait on the review

If I understood your comment correctly, you’re suggesting narrowing this section down to just Sec-Fetch-Site and Origin/Host header validation. I agree this would simplify things, but my thinking was that it’s important to keep the broader context of Fetch Metadata headers, since they work as a family and the spec encourages using them together.

and link off to MDN or something

we already link out to the W3C spec for readers who want deeper detail.

Maybe you can draft a short suggestion of what you’d like this section to look like?

[mkhanas]

Also, there are examples of Sec-Fetch-Mode, Sec-Fetch-Dest, and Sec-Fetch-User further down in the section.

Because of that, I think it makes sense to keep the broader description here, so all the related information stays in one place and developers don’t need to jump between different resources to understand how the full set of headers works together.

[artis3n]

That makes sense if we want to keep them co-located. I do think we should distinguish between the headers you need to use for CSRF protection vs. the ones you can use for additional checks. E.g. mode, dest, and user.

[mkhanas]

mode, dest, and user are still part of the overall Fetch Metadata–based CSRF protection strategy, the Sec-Fetch-Site header is just the primary signal we rely on. But I get your point, I’ll try to update the wording to make that distinction clearer.

[nickchomey]

I agree that making it clear that sec-fetch-site is the primary signal would be important, so as to not overcomplicate/overwhelm people. The others can be included for reference/deep dive.

[mkhanas]

Updated

[artis3n]

How about a section for Requirements / Pre-Conditions/ etc. to indicate what must already be present in order to rely on this method? (Must enforce HTTPS only or be using localhost, must not use GET requests for state-changing requests, recommended to set HSTS).

[mkhanas]

Agree, this originally started as a “things to consider” section, but during the PR review we already narrowed it down to notes about trustworthy URLs and HSTS. We can definitely rephrase it as requirements rather than optional considerations.

Regarding “must not use GET requests for state-changing requests,” there’s already a dedicated section for that, but we can briefly mention it here as well.

[mkhanas]

Updated, feel free to resolve the conversation

[artis3n]

I'd recommend we update this section. Maintaining language agnosticity, I'd like to see the pattern outlined in https://words.filippo.io/csrf/#protecting-against-csrf-in-2025 personally.

1. Validate Origin header against an allowlist (for the JS example, recommend configuring as a new Set([domains]) for an easy set.has(Origin) as this validation step
2. Check if Sec-Fetch-Site header is present
   a. If present, allow request if value is same-origin or none, else deny
3. If Sec-Fetch-Site and Origin headers are both missing, pass request through
4. Validate Origin header against Host header and pass request if they match, else reject (do this at the end and not with initial Origin validation due to step 3 support of significantly legacy browsers pre-2020)

Also the pattern described, basically, in https://web.dev/articles/fetch-metadata#how_to_use_fetch_metadata_to_protect_against_cross-origin_attacks .

[artis3n]

And I'm partial since it is the language I am usually in but would be nice to note with the examples that Go developers can follow the above pattern by just using https://pkg.go.dev/net/[email protected]#CrossOriginProtection in the standard library as of Go 1.25.

Perhaps similar to https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#javascript-automatically-including-csrf-tokens-as-an-ajax-request-header , a section for Go: Use net/http CrossOriginProtection middleware with a link out to those docs.

[mkhanas]

This PR's aproach was actually based primarily on the approach outlined in https://web.dev/articles/fetch-metadata#how_to_use_fetch_metadata_to_protect_against_cross-origin_attacks, however, I intentionally changed the flow to make it deny-by-default, rather than the more allow-by-default used in both that article and Filippo’s blog.

Both external sources propose flows that can short-circuit early and allow requests without evaluating Fetch Metadata. For example:

If the Origin header matches an allow-list of trusted origins, allow the request.

In this example, the request never reaches any Fetch Metadata checks. That effectively makes the Origin header the primary defense.

These requests are not from (post-2020) browsers, and can’t be affected by CSRF.

I’m not fully comfortable relying on that assumption. My interpretation is that it’s based on the earlier point that older (pre-2020) browsers sometimes omitted the Origin header on POST. The wording could also be misread as “pre-2020 browsers can’t be affected by CSRF,” which I’m sure isn’t the intended meaning.

if as a community we agree that Fetch Metadata is the stronger and more reliable signal in modern browsers, then it seems logical to evaluate Sec-Fetch-Site first and use standard headers (Origin/Referer/Host) only as a fallback for legacy or non-compliant clients.

[mkhanas]

a section for Go: Use net/http CrossOriginProtection middleware with a link out to those docs.

Regarding your second suggestion, that’s a great idea. We should definitely add a Go section to the “CSRF Prevention in Modern Frameworks” area. I can write a short part for it and include a reference to the CrossOriginProtection middleware along with a link to the documentation.

[nickchomey]

While the blog post uses Origin first, the actual Go source code checks sec-fetch-site first:

I have to assume this concern was raised while implementing the feature, and thus appropriately uses origin as a fallback.

[mkhanas]

Thanks for bringing this up, I went straight for the blog.

As we discussed, we’ll definitely add a reference to the Go implementation in the Frameworks section at the end of the document. Do you feel the current “### How to treat Fetch Metadata headers on the server-side” section needs any updates? @nickchomey

[mkhanas]

Added this as part of "### Use Built-In Or Existing CSRF Implementations for CSRF Protection"

[nickchomey]

Seems OK to me.

[nickchomey]

sorry i couldnt look at this til now. I'm generally happy with how this is taking shape, and have no qualms with making a qualified recommendation for fetch metadata.

I made a few small suggestions.

I also wonder if @jmanico's remaining concerns should be enumerated somewhere, along with possible mitigations?

• The concern about “user-initiated” navigation and prefetch/prerender flows isn’t theoretical. There are ongoing W3C TAG and WHATWG discussions about how speculative browsing contexts propagate fetch metadata. For example, prerendered pages sometimes emit Sec-Fetch-Site: same-origin even when the final navigation resolves cross-site. Chrome’s prerender2 work (tracked in Chromium #1170321 and #1261932) notes inconsistencies in how speculative requests report fetch metadata headers. PaymentRequest and similar APIs also create browser-initiated POSTs that don’t always surface Sec-Fetch-* in predictable ways. None of these are critical exploits, but they show that interpretation and propagation aren’t yet frozen.
• Regarding proxies: you’re totally right in that stripping Origin or Sec-* headers is a misconfiguration or vulnerability, but in large enterprise networks (and some healthcare/ICS environments) those conditions unfortunately frequently exist. From a standards perspective, we try to write guidance that remains safe even in sub-optimal deployments. And CSRF tokens and SameSite cookies both work well in these realistic environments.

[mkhanas]

@nickchomey Another great idea, we should definitely add that, otherwise it’ll get lost. My first thought was to put it under the “Things to consider” subsection, but we already discussed converting that into Requirements.

Now I’m thinking that at the end of the Fetch Metadata section we should have three subsections: Concerns (including @jmanico’s remaining points), Requirements (trusted URLs, localhost, HSTS), and the existing “Rollout & testing recommendations”

[nickchomey]

That sounds fine to me

[nickchomey]

I don't think the 2nd half of the first bullet should have been added. It is completely redundant with the 2nd bullet (and also has a lot of repetitive wording with the rest of the 1st bullet.

Suggested change

	- **If the framework does not have built-in CSRF protection, add [CSRF tokens](#token-based-mitigation) to all state changing requests (requests that cause actions on the site) and validate them on the backend, or validate [Fetch Metadata headers](#fetch-metadata-headers) on the backend for all state-changing requests.**
	- **If your software is intended to be used only on modern browsers, you may rely on [Fetch Metadata headers](#fetch-metadata-headers) to block cross-site state-changing requests, so long as you use the fallback options detailed below.**
	- **If the framework does not have built-in CSRF protection, add [CSRF tokens](#token-based-mitigation) to all state-changing requests (requests that cause actions on the site) and validate them on the backend.**
	- **If your software is intended to be used only on modern browsers, you may rely on [Fetch Metadata headers](#fetch-metadata-headers) to block cross-site state-changing requests, so long as you use the fallback options detailed below.**

[nickchomey]

Is referer actually necessary, or even a good idea? I've seen it mentioned in various places that it has some issues. And origin is essentially 100% browser coverage. Hence that's all Go 1.25 uses. I don't think we mention referer elsehwre, either.

[nickchomey]

is navigate mode defined anywhere?

[nickchomey]

This isn't really a comment about the doc, but a related question.

In wordpress, Ajax requests are often made with GET to make mutations. This is, of course, wrong in many ways, but does happen.

Though, wp encourages the use of their nonce mechanism for Ajax, and doesn't use fetch metadata at all. Still, I will likely put in some effort to see if sec fetch can replace the wp nonces in a drop-in manner (just turn off/ignore nonces if they're there and use sec fetch)

So, I wonder what can be done to handle state-changing GET requests?

Should anything be mentioned here for the benefit of other frameworks or sites that use GET incorrectly?

[nickchomey]

Can we add any info on what the issue is here that is being addressed? It isn't obvious to me, and surely most others.

[nickchomey]

Seems OK to me.