Add note about Fetch Metadata headers on non-secure origins

[tim-we]

Description

Adds a note to the Fetch Metadata Request Headers page clarifying that Fetch Metadata headers are only sent for potentially trustworthy URLs. This helps explain why headers such as Sec-Fetch-Dest, Sec-Fetch-Mode, and Sec-Fetch-Site may be absent on non-secure http:// origins during development and testing.

Motivation

We have a project where we use the Sec-Fetch-Dest header to test whether the content is in an iframe or not and return different content based on that. Worked locally but our non-production deployments did not use https. So this caught us by surprise and I thought a note like this might be helpful to other devs.

Additional details

https://www.w3.org/TR/secure-contexts/#potentially-trustworthy-url

Related issues and pull requests

No related issues or PRs.

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Glossary/Fetch_metadata_request_header
• /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Dest
• /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Mode
• /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Site
• /en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-User
• /en-US/docs/Web/Security/Defenses/Secure_Contexts

(comment last updated: 2026-06-19 04:26:48)

[hamishwillee]

Thanks @tim-we - this was a good thing to note.

I see the lack of definition of potentially trustworthy URLs as making this less useful, so I added one. @chrisdavidmills Do you think you could give this an independent look - I've modified it enough that I shouldn't self-approve.

[chrisdavidmills]

Happy to help, @hamishwillee. This looks pretty decent to me, just a few small comments.

[wbamberg]

I do agree that there's a documentation gap here but have a few issues with this PR.

First I don't think that the glossary entry for Fetch metadata is the right place to put this. Glossary entries are supposed to be very short definitional things, for where we want to use a technical term in a page and let someone get a quick definition of it. They're not really first-order documentation for a feature. That is, if I want to learn about FM, I wouldn't expect to visit the glossary page to do so. I would go to the guide page, or the reference pages for the headers.

Yes, I am the glossary police.

Second, is this restriction only for FM headers or are there other headers with this restriction? For example I see that the client hints headers (https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-CH-UA-Model) have the standard "secure context" banner. What's the difference between that case and this? If they are the same, why not use the same mechanism for both?

Also I find the terminology we use a bit confusing tbh. We have a standard mechanism for talking about Web APIs, that uses the secure context banner macro, which gives the boilerplate text:

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

But actually the Secure Contexts page is strangely disjointed really. It starts by talking about a secure context, then talks about this spec term "potentially trustworthy origin", and now, as of this PR, also talks about "potentially trustworthy URLs". But it doesn't really explain the relationship between a "secure context" and these spec terms.

Meaning, if I see this banner, for, say, ServiceWorkerContainer, how am I supposed to use the Secure Contexts page to understand exactly when this feature will be available?

[hamishwillee]

@wbamberg AIUI (thanks to Claude and Gemini, so take that with a grain of salt)

• a secure origin is what you think - a resource delivered over a secure transport: HTTPS/WSS where the ancestor chain is also delivered in a secure context.
• A potentially secure origin is pretty much the same except that it adds local host and loopback URL to the set of origins we trust, and sometimes file:// (though that is browser dependent). I think practically speaking they are the same thing.

They are the same, and are used for the same thing - letting the browser know that the page is trusted to use certain APIs and recieve certain headers.

A potentially trustworthy URL seems to serve a different purpose in Fetch metadata. It indicates that the URL is safe to include metadata when sending it a request. We don't want to send our metadata for fingerprinting to an HTTPS URL.
So unlike Secure Context, which grants access to this site (say), the trustworthy URL says it is safe to send data to the other site.

This is also used in the Referrer-Policy algorithm https://w3c.github.io/webappsec-referrer-policy/#referrer-policy-no-referrer-when-downgrade to decide if Referer should be sent in a response.
Not checked, but AI says also in Cookie if Secure attribute is set and Sec-Fetch-Storage-Access

The reason it is where it is is explictly that its definition is so similar to the potentially secure origin. You're right that it doesn't belong there, which is why I added a note to that effect - it's just the closest place I can see.

So:

• I think we can reasonably still include potentially secure origin in the secure context page - it really is the same thing.
• We could move potentially trustworthy URL to the fetch metadata guide and link from other things that need the definition?
• Yes, happy to keep the glossary lean

[hamishwillee]

Note, this is PR 44444. Apparently in some cultures 4 is unlucky, so this must be a very unlucky PR indeed.

[wbamberg]

@wbamberg AIUI (thanks to Claude and Gemini, so take that with a grain of salt)

I don't know which bits of this are Hamish and which are LLM, but there seem to be some errors here. "secure context", "potentially trustworthy url", and "potentially trustworthy origin" are all spec terms with precise definitions. "secure origin" and "potentially secure origin" are not spec terms, they are invented. It would be very confusing to start to use these terms.

Also "a secure origin is ... a resource" - how can an origin be a resource?

In the spec, it looks as if secure context is defined in terms of potentially trustworthy URLs, and then potentially trustworthy URLs are defined in terms of potentially trustworthy origins, so the relationship doesn't seem to be the one described in the comment.

What I would suggest is, look at this from the point of view of a developer reading these docs.

• in which concrete circumstances will specific APIs be available to JS running in the page? Do we communicate this clearly and consistently at the moment?
• in which concrete circumstances will specific HTTP headers be sent? Do we communicate this clearly and consistently at the moment?

So for instance, if a developer wants to know whether Sec-CH-UA-Arch will be sent, what they see at the moment is the standard secure contexts banner. If they see that, and maybe try to follow the link, what will they understand about when/whether Sec-CH-UA-Arch gets sent? Will their understanding be clear, and will it be correct? Same for the fetch metadata headers (and for that matter the web APIs).

Actually, it looks as if the rules for client hints headers do not use the "secure contexts" definition, despite MDN suggesting that they do. Which is odd, because the underlying reasoning seems to be the same as for fetch metadata (not leaking information in plaintext channels).

[tim-we]

Oh boy, what did I start :D

I think this info would be most helpful on the individual header documentation pages, like https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Fetch-Dest

Maybe it could be part of this properties table (above the syntax section)?

[hamishwillee]

Thanks @wbamberg. Yes - I've been very sloppy in my comments (more so than claude) randomly using terms such as secure origin as synonums for "who knows what". This should certainly be done in terms of the spec expressions: secure context, potentially trustworthy url, potentially trustworthy origin.

Actually, it looks as if the rules for client hints headers do not use the "secure contexts" definition, despite MDN suggesting that they do. Which is odd, because the underlying reasoning seems to be the same as for fetch metadata (not leaking information in plaintext channels).

Yes, they don't explicitly. If you follow the trail of specs it is very much not delivered over non-secure transport. The client hint opt-in is like this :

"The opt-in MUST be ignored if delivered over non-secure transport (using a scheme different from HTTPS).

If you take the "using a scheme different from HTTPS" literally it is more secure that potentially trustworthy origin or URL/Secure context. I suspect that is more "by way of example" and the "non-secure transport" might not matter to local host URLs. I.e. its a synonym for secure origin context (curses, did it again).

in which concrete circumstances will specific HTTP headers be sent? Do we communicate this clearly and consistently at the moment?

No, but its messier than just the secure context stuff. In the case of user hints there's all this guidance around being allowed to send things that are already exposed (don't increase fingerprinting surface).

@tim-we Yes this is useful to include in the headers but whether we do it in a table or like I did in https://github.com/mdn/content/pull/44444/changes#diff-7bba0076eb1bcc1687af182382f5e2de7c89943c534e9226206dce8dc23684cfR14 , we still need that link to potentially trustworth URLs. Based on those links you provided it should be possible to update that glossary more clearly to link secure context, potentially trustworthy url, potentially trustworthy origin definitions.

I'm clearly not doing a great job at that so far. I'm sure I could, but I don't want to while I have the pile of FF release tasks on me. So if you want to drive this @wbamberg to support @tim-we feel free. Otherwise, sorry, but I will need to defer this a little.