Recording and displaying security requirements of APIs

[Elchi3]

There was a discussion about how to best record and display security requirements of APIs in mdn/content#20435. It should be a real discussion thread, so I'm moving it here. Recently, this came up again in mdn/content#22387 after mdn/content#22303 was filed.

Certain web platform APIs are only available behind certain security requirements, for example:

• HTTPS only
• Permission API permission
• User Activation
• Cross origin isolation (COI), see SharedArrayBuffer and others.

In mdn/content#20435, I created a "Security" section on API pages to mention these requirements. There are two problems with this, though: 1) It is not visible enough. 2) It is not structured enough.

In the PR we already discussed how this could be done in front-matter instead. A rough proposal:

security-requirements:
 - secure-context
 - cross-origin-isolation
 - user-activation: transient
 - permissions: 
   - clipboard-read

(Note that the "secure-context" requirement could also be queried from webidl directly).

This front matter information could then be used to create a banner (or similar) that talks about all security requirements. How and where to display it could then be experimented with to solve the visibility problem best.

[hamishwillee]

I like this proposal.

• Can all security things that we might want to include be boilerplated? Is there a need for some form of freetext? I'm thinking the Firefox WebMidi access via a secure permissions extension having to be installed.
• If we can't do it via metadata, one option is to have a macro "security" that replaces other security info, like securecontext, and just highlights that there are security issues, and that these are covered in the Security system. Think the SeeCompat macro linking to the Browser compatibility section.

[wbamberg]

I like the idea of using front matter for this.

(Note that the "secure-context" requirement could also be queried from webidl directly).

It would be just great if we could do this, and I experimented with it in mdn/yari#7227. I ran into a couple of problems:

• BCD doesn't reliably give me a set of specs I can use to fetch the relevant bit of webidl. Sometimes there isn't BCD, and sometimes there's an array of BCD queries. Sometimes spec_url is an array. For the formal syntax macro rework I ended up not using spec_url, for reasons like this, and just looked for specs that define the item in the page. I think there's some underlying work around us being more precise about how we define spec URLs which is needed to unlock this and similar work.

• the IDL doesn't always map to the places we want to indicate "secure context". For instance, look at Geolocation/getCurrentPosition(). We want to say this is secure context required. But the IDL does not mark it as SecureContext: https://w3c.github.io/geolocation-api/#geolocation_interface. Instead it marks the interface constructed by that function as SecureContext: https://w3c.github.io/geolocation-api/#position_interface. This is technically true but not so helpful for developers.

• we sometimes want to use secure context required more loosely still: for example, we call the whole Geolocation API "secure context required": https://developer.mozilla.org/en-US/docs/Web/API/Geolocation. But this page doesn't even map onto a single IDL interface, which is where SecureContext can attach. I think certainly in this case, we will often see this problem with other things we might want to derive from structure content, like "experimental".

[wbamberg]

Can all security things that we might want to include be boilerplated? Is there a need for some form of freetext? I'm thinking the Firefox WebMidi access via a secure permissions extension having to be installed.

This is a good question. I think it depends how common that situation is. I think if it's very rare, handling it outside the system would be OK - rather than adapting and complexifying the system to allow it.

[chrisdavidmills]

Can all security things that we might want to include be boilerplated? Is there a need for some form of freetext? I'm thinking the Firefox WebMidi access via a secure permissions extension having to be installed.

This is a good question. I think it depends how common that situation is. I think if it's very rare, handling it outside the system would be OK - rather than adapting and complexifying the system to allow it.

If it helps, I've just been going through and reviewing loads of API pages as part of my Permissions API work, and security variant stuff like this is very rare, so I think including a note in the body for such cases could be OK. After all, the whole point of efforts like Permissions APi is making web security requirements simpler and more consistent/standard.

[chrisdavidmills]

I also thought that this standard security information possibly only needs to be provided at an API or interface level — it is unlikely that an API or interface will be controlled via a specific permissions API directive, but a specific member won't.

And for cases where this does not hold true (there are always edge cases), you could do it in a way where you apply the data at an API level and it applies it to all interfaces and members below that, but then if you apply the data at a node lower in the chain, it overrides it.

Maybe also provide a flag that turns off the default recursive application, just in case?

[hamishwillee]

Maybe also provide a flag that turns off the default recursive application, just in case?

Not sure. Probably. It somewhat depends on the API. In many cases the secure context is applied to an accessor function in window or navigator or whatever that either gives you a promise that either resolves to an object you can work with or some kind of rejection. In this case you need the secure context on the API top level overview and on the method itself. But I'm not sure you need it everywhere - and I doubt the IDL would apply the secure context everywhere.

[hamishwillee]

Looking at openwebdocs/project#146 project I feel like we might need separate permission front matter for permission API and for permissions policy. The permissions for both mechanisms have the same names, but are different entities - i.e. the requirement to ask for user permission to use an API does not necessarily mean that there can be a permission policy, and visa versa.

 - user-permissions: 
   - clipboard-read
- policy-permissions
  - notifications

or

 - permissions: 
   - user-clipboard-read
   - policy-clipboard-read
   - user-notifications

Further, it might be useful to display the permission BCD or a link to it - so if you're documenting API X then in its security or compatibility section, also add https://developer.mozilla.org/en-US/docs/Web/API/Permissions#browser_support line

[wbamberg]

Yes, I agree that we would need separate items for permissions policy and permissions API. I like your first suggestion much better than your second. For names, I think I like permission-api and permission-policy better, partly because they map better to spec terms AFAIK: https://w3c.github.io/window-management/#api-permission-api-integration, partly because I like both of them starting with permission-.

In terms of features, does this cover everything we need at the moment (and everything we expect to need in the near future?)

[wbamberg]

I don't think I like this data structure very much though:

security-requirements:
 - secure-context
 - cross-origin-isolation
 - user-activation: transient
 - permission-api: 
   - clipboard-read
   - clipboard-write
 - permission-policy:
   - clipboard-read
   - clipboard-write

In JSON this translates to:

{
    "security-requirements": [
        "secure-context",
        "cross-origin-isolation",
        {
            "user-activation": "transient"
        },
        {
            "permission-api": [
                "clipboard-read",
                "clipboard-write"
            ]
        },
        {
            "permission-policy": [
                "clipboard-read",
                "clipboard-write"
            ]
        }
    ]
}

...which is really awkward to work with - if you want to find out the permissions policy for a feature, you have to iterate the items, looking for an item which is an object with a "permissions-policy" key. I would prefer something like:

security-requirements:
  flags:
    - secure-context
    - cross-origin-isolation
  user-activation: sticky
  permission-api:
    - clipboard-read
    - clipboard-write
  permission-policy:
    - clipboard-read
    - clipboard-write

...which would give us:

{
  "security-requirements": {
    "flags": ["secure-context", "cross-origin-isolation"],
    "user-activation": "sticky",
    "permission-api": ["clipboard-read", "clipboard-write"],
    "permission-policy": ["clipboard-read", "clipboard-write"]
  }
}

...so to find the permissions policy you just have to look for the "permissions-policy" field. The awkwardness there of course is having flags for on/off fields. It is tempting to have:

security-requirements:
  secure-context: true
  cross-origin-isolation: true
  user-activation: sticky
  permission-api:
    - clipboard-read
    - clipboard-write
  permission-policy:
    - clipboard-read
    - clipboard-write

...but that's redundant if on/off switches are only present if they are on. So I like flags better.

[hamishwillee]

We may need three options for user activation: "user-activation": "transient" | "sticky" | "required"

What I mean here is that often the user activation requirement is not in the spec, and is done differently in different browsers. I'm thinking of autoplay behaviour for audio/video with sound - in some browsers transient activation is required while in others sticky activation is sufficient.

[wbamberg]

Can you link to an example of that? What does the spec say in cases like this?

[hamishwillee]

autoplay is the example I am thinking of. The spec says that the "can autoplay" flag is true, but not how it might be made to be true. Or more generally "it can play if it is allowed to play".

So from https://html.spec.whatwg.org/multipage/media.html#playing-the-media-resource

A media element is said to be eligible for autoplay when all of the following conditions are met:

• Its can autoplay flag is true.
• Its paused attribute is true.
• It has an autoplay attribute specified.
• Its node document's active sandboxing flag set does not have the sandboxed automatic features browsing context flag set.
  -Its node document is allowed to use the "autoplay" feature.

A media element is said to be allowed to play if the user agent and the system allow media playback in the current context.

Then you see the example, is "could be transient activation":

For example, a user agent could allow playback only when the media element's Window object has transient activation, but an exception could be made to allow playback while muted.

All the browsers do it differently.

[wbamberg]

That's interesting, thank you! It looks to me like can play here is "can" in the sense of "can I run 100m in 10 seconds" not "can I have another slice of cake". The "slice of cake" part seems to be allowed to play, which as you say does not elaborate any specifics:

A media element is said to be allowed to play if the user agent and the system allow media playback in the current context.

So I think user-activation: required would be wrong here, the spec doesn't require any user activation, and AFAICT a browser would be compliant if allowed to play was just always true. I'm not sure what if anything the security-requirements should express here.

Maybe for browser-specific requirements we could use properties in BCD, and when a "Security requirements" section of the page is rendered it could peek at those and use it to elaborate them?

Security requirements

This feature is only available in secure contexts. // document the specced requirements

• This feature requires sticky activation in Chrome. // document browser-specific requirements
• This feature requires transient activation in Firefox.

[hamishwillee]

I guess it isn't really a security requirement in the same way as others. It's designed to stop autoplay of sound in contexts that the user might find it inappropriate - such as a library.

If this proves necessary to address, compatibility data would be a good place for it. Generally BCD is resistant to adding metadata that isn't strictly indicating a compatibility difference though, so this would only exist if it was defined in the spec and some browser did something different.

[wbamberg]

Splitting a concrete proposal for security requirements metadata out of https://github.com/orgs/mdn/discussions/288#discussioncomment-7452307.

The proposal is to have a structure like:

security-requirements:
  flags:
    - secure-context
    - cross-origin-isolation
  user-activation: sticky
  permission-api:
    - clipboard-read
    - clipboard-write
  permission-policy:
    - clipboard-read
    - clipboard-write

or in JSON:

{
  "security-requirements": {
    "flags": ["secure-context", "cross-origin-isolation"],
    "user-activation": "sticky",
    "permission-api": ["clipboard-read", "clipboard-write"],
    "permission-policy": ["clipboard-read", "clipboard-write"]
  }
}

The security-requirements key is an object with four properties, all optional:

• flags: present of any flags apply. An array of strings, each of which represents a condition that has to be met for the API to be callable. Strings may be one of: "secure-context" and "cross-origin-isolation".
• user-activation: present if the API needs sticky or transient user activation. If present, must have exactly one of the values "sticky" or "transient".
• permission-api: present if the API needs any Permission API permissions. An array of strings, each of which represents a permission.
• permission-policy: present if the API needs any Permissions policy permissions. An array of strings, each of which represents a permission.

We might think of this proposal as independent from discussions about where this might live (for example in MDN page front matter). For now, is this a sensible structure and does it properly capture the security requirements we want it to capture?

[tidoust]

For now, is this a sensible structure and does it properly capture the security requirements we want it to capture?

What about security requirements that affect APIs calls in iframes? Typically, sandbox restrictions such as allow-orientation-lock, allow-popups or allow-same-origin? Most of them are feature specific, I don't know if there's a lot of value to be gained from capturing them as metadata. The allow-same-origin flag seems broader in scope though.

As a side note, some of the metadata could perhaps be extracted from specs directly and exposed in webref data. It may be hard to have the information at the right granularity though. For instance:

• "secure-context" should already be derivable from IDL extracts, but with the caveats mentioned by @wbamberg in a previous comment.
• The list of permissions defined by a spec should already appear in its dfns extract (well, provided the spec uses the right definition type for them...), but it will also not going to be straightforward to associate them with specific API functions.
• Same issue for the use of user-activation, which should be relatively easy to detect in a spec (the spec will link to relevant algorithms in HTML), but hard to associate with a specific API function.

[wbamberg]

I looked into what the implications, benefits, and drawbacks of using WebIDL to provide values for "secure context required": https://github.com/wbamberg/securecontext-checker/blob/main/secure-context-analysis.md.

Summary:

• it would fix hundreds of MDN pages that currently show incorrect information here, either way (i.e. indicating SC when a feature isn't, or not-SC when a feature is).
• there are a few wrinkles: globals, nonstandard features, and maplike/setlike/iterable are all places where MDN and WebIDL won't correspond, as well as editorial choices like Geolocation/getCurrentPosition(). But altogether there aren't very many pages affected by these issues

[teoli2003]

Great analysis!
About the wrinkles:

• Globals: Representing them like proposed in the linked discussion will make the wrinkle naturally go away.
• Nonstandard features: They would be initially ignored (= not changed), so they wouldn't have a negative impact. To have automated BCD for non-standard features, we are already building extra WebIDL files. These could likely be used in the future to expand the tool. This is non blocking.
• maplike/setlike/iterable: these WebIDL template types map to a fixed set of properties and methods. We also want to uniformize how we document them. As you said, it is a wrinkle, adding a bit of complexity but standardized.

Using tools to ensure coherence (like tagging Non-standard, Experimental, … pages from a unique source-of-trust, BCD) is a success, this is very similar.

TL;DR: This would be a valuable tool, ensuring coherence and correctness to user, transparent for authors (and it will simplify their life).