Update secure contexts guide

[wbamberg]

Fixes #45467.

I have drawn pretty heavily on https://w3c.github.io/webappsec-secure-contexts/#intro which gives a nice easy overview of the situation for different environments.

I had some questions though.

• As I read it, documents are SC if they have a "potentially trustworthy URL" (https://html.spec.whatwg.org/multipage/webappapis.html#secure-context). But the intro says that iframed documents are SC if they have a "potentially trustworthy origin" (https://w3c.github.io/webappsec-secure-contexts/#examples-framed). Why is there a difference? I think it would make the explanations simpler if we could fold the "potentially trustworthy origin" section into "potentially trustworthy URL" but we can't really do that if things want to refer to "potentially trustworthy origin" specifically.

• I quite like the diagrams in the intro but elected not to copy them partly because I think it will be hard to make them accessible. So I just used a couple of tables.

• There is some horrible stuff about how to derive an origin from a URL (https://url.spec.whatwg.org/#concept-url-origin) that I have glossed over.

• I think the rationale in "Why should some features be restricted?" is still a bit weak. There an interesting bit in the threat model for the spec (https://w3c.github.io/webappsec-secure-contexts/#threat-models) that says "Granting permissions to unauthenticated origins is, in the presence of a network attacker, equivalent to granting the permissions to any origin" - that is, because a network attacker can take over an unauthenticated connection, then they could get access to any powerful APIs that have been granted to that connection. If you like I could try to unpack this.

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/Security/Defenses/Secure_Contexts

External URLs (1)

URL: /en-US/docs/Web/Security/Defenses/Secure_Contexts
Title: Secure contexts

• https://w3c.github.io/webappsec-secure-contexts/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-09-11 03:38:23)

[hamishwillee]

• As I read it, documents are SC if they have a "potentially trustworthy URL" (https://html.spec.whatwg.org/multipage/webappapis.html#secure-context). But the intro says that iframed documents are SC if they have a "potentially trustworthy origin" (https://w3c.github.io/webappsec-secure-contexts/#examples-framed). Why is there a difference? I think it would make the explanations simpler if we could fold the "potentially trustworthy origin" section into "potentially trustworthy URL" but we can't really do that if things want to refer to "potentially trustworthy origin" specifically.

Every SC has a potentially trustworthy URL, but not every trustworthy URL is a trustworthy origin.
The reason the distinction exists is the trustworthy URLs that have opaque origins and would fail a trustworthy check on the basis of their (opaque) origin check: about:blank, about:srcdoc, data.
We essentially say that as long as these also come from a secure context they are OK.

I've noted that I think we can use potentially trustworthy URL in all cases (or not mention at all). You can fold in the sections, but you should certainly continue to keep the term for the origin.

• I quite like the diagrams in the intro but elected not to copy them partly because I think it will be hard to make them accessible. So I just used a couple of tables.

It works, but I have suggested lists and perhaps icons. Mostly because the text in the table for secure does not "pop".

• There is some horrible stuff about how to derive an origin from a URL (https://url.spec.whatwg.org/#concept-url-origin) that I have glossed over.

Good.

• I think the rationale in "Why should some features be restricted?" is still a bit weak. There an interesting bit in the threat model for the spec (https://w3c.github.io/webappsec-secure-contexts/#threat-models) that says "Granting permissions to unauthenticated origins is, in the presence of a network attacker, equivalent to granting the permissions to any origin" - that is, because a network attacker can take over an unauthenticated connection, then they could get access to any powerful APIs that have been granted to that connection. If you like I could try to unpack this.

It does look a bit weak. I think the main point of HTTPS is that you get a guaranteed identity - the user can then make informed choices about who to grant access to. Also worth perhaps saying a few more words about the powerful APIs - such as bluetooth or whatever, and some examples of the bad case.

I'd be tempted to leave it, mostly because I don't have anything better. Perhaps if you unpacked it I might be able to comment better.

[wbamberg]

• As I read it, documents are SC if they have a "potentially trustworthy URL" (https://html.spec.whatwg.org/multipage/webappapis.html#secure-context). But the intro says that iframed documents are SC if they have a "potentially trustworthy origin" (https://w3c.github.io/webappsec-secure-contexts/#examples-framed). Why is there a difference? I think it would make the explanations simpler if we could fold the "potentially trustworthy origin" section into "potentially trustworthy URL" but we can't really do that if things want to refer to "potentially trustworthy origin" specifically.

Every SC has a potentially trustworthy URL, but not every trustworthy URL is a trustworthy origin. The reason the distinction exists is the trustworthy URLs that have opaque origins and would fail a trustworthy check on the basis of their (opaque) origin check: about:blank, about:srcdoc, data. We essentially say that as long as these also come from a secure context they are OK.

I understand that they are not the same thing, but I'm saying we don't need to reify "potentially trustworthy origin", unless, somewhere, something must refer only to that definition. We could instead say:

A URL is potentially trustworthy if any of the following apply:

• Its value is about:blank or about:srcdoc
• Its scheme is data
• Its origin has one of the following:
  • A scheme of https, wss, or file.
  • A host value of 127.0.0.0/8 or ::1/128
  • A host value of localhost or localhost.
  • A host value ending with .localhost or .localhost.
  • A scheme that the browser considers to be authenticated

It's very spec-y, to make lots of separate definitions, and cross reference them in terms of each other. But it doesn't make things easier to understand.

Currently I can't do this apparently, because in the spec intro, iframe SC is defined specifically in terms of "potentially trustworthy origins", as noted above ("Framed documents can be secure contexts if they are delivered from potentially trustworthy origins"). But if we don't think this is correct, then I can do this.

[wbamberg]

• As I read it, documents are SC if they have a "potentially trustworthy URL" (https://html.spec.whatwg.org/multipage/webappapis.html#secure-context). But the intro says that iframed documents are SC if they have a "potentially trustworthy origin" (https://w3c.github.io/webappsec-secure-contexts/#examples-framed). Why is there a difference? I think it would make the explanations simpler if we could fold the "potentially trustworthy origin" section into "potentially trustworthy URL" but we can't really do that if things want to refer to "potentially trustworthy origin" specifically.

Every SC has a potentially trustworthy URL, but not every trustworthy URL is a trustworthy origin. The reason the distinction exists is the trustworthy URLs that have opaque origins and would fail a trustworthy check on the basis of their (opaque) origin check: about:blank, about:srcdoc, data. We essentially say that as long as these also come from a secure context they are OK.

I understand that they are not the same thing, but I'm saying we don't need to reify "potentially trustworthy origin", unless, somewhere, something must refer only to that definition. We could instead say:

A URL is potentially trustworthy if any of the following apply:

• Its value is about:blank or about:srcdoc

• Its scheme is data

• Its origin has one of the following:

  • A scheme of https, wss, or file.
  • A host value of 127.0.0.0/8 or ::1/128
  • A host value of localhost or localhost.
  • A host value ending with .localhost or .localhost.
  • A scheme that the browser considers to be authenticated

It's very spec-y, to make lots of separate definitions, and cross reference them in terms of each other. But it doesn't make things easier to understand.

Currently I can't do this apparently, because in the spec intro, iframe SC is defined specifically in terms of "potentially trustworthy origins", as noted above ("Framed documents can be secure contexts if they are delivered from potentially trustworthy origins"). But if we don't think this is correct, then I can do this.

OK, it looks like I can't do this because at least IdentityCredential.disconnect() needs to refer to this concept :(. Never mind.

[hamishwillee]

This is just a suggestion. We need the origin, but it isn't the important thing. It would be nice to do it something like his.

Suggested change

	## Potentially trustworthy URLs
	A URL is potentially trustworthy if any of the following apply:
	- Its value is `about:blank` or `about:srcdoc`
	- Its scheme is `data`
	- Its {{glossary("origin")}} is a [potentially trustworthy origin](#potentially_trustworthy_origins).
	## Potentially trustworthy origins
	An origin is potentially trustworthy if has:
	- A scheme of `https`, `wss`, or `file`.
	- A host value of `127.0.0.0/8` or `::1/128`
	- A host value of `localhost` or `localhost.`
	- A host value ending with `.localhost` or `.localhost.`
	- A scheme that the browser considers to be authenticated
	This is essentially intended to capture:
	- Origins that use a secure transport across the network
	- Origins that are local
	- Origins that the browser considers authenticated for some other reason (for example, those used by browser extensions).
	## Potentially trustworthy URLs
	A URL is potentially trustworthy if any of the following apply:
	- Its value is `about:blank` or `about:srcdoc`
	- Its scheme is `data`
	- Its {{glossary("origin")}} is a [potentially trustworthy origin](#potentially_trustworthy_origins):
	- A scheme of `https`, `wss`, or `file`.
	- A host value of `127.0.0.0/8` or `::1/128`
	- A host value of `localhost` or `localhost.`
	- A host value ending with `.localhost` or `.localhost.`
	- A scheme that the browser considers to be authenticated
	## Potentially trustworthy origins
	A potentially trusted origin is one that uses a secure transport accross the network, a local origin, or an origin that the browser considers authenticated for some other reason (for example, those used by browser extensions).
	The precise criteria are covered in the "origin" part of the previous section.

[wbamberg]

I think I see the reason you made this suggestion but I am -1 on it, for a couple of reasons.

First I like the gloss of trustworthy origin in lines 92-96, and moving it makes it inaccessible to people who come to the "Potentially trustworthy URLs" section (which as you say is most of them). I would be happy to de-bullet it though.

Second I think "The precise criteria are covered in the "origin" part of the previous section." is a bit awkward.

[hamishwillee]

Fair enough!

[hamishwillee]

@wbamberg I like the fixes and agree with the comprises. This is pretty good, and also a lot better than it was.

One suggestion in https://github.com/mdn/content/pull/45518/changes#r3985106094 but I am approving this so you can merge after thinking about it.

Thanks so much for taking this on. I didn't want to :-)

[Josh-Cena]

Congrats on being the 30000th commit!