Extract 'SecureContext' status in json files

[OnkarRuikar]

Consider subtle property of Crypto interface: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/subtle

It requires secure context. WebCryptoAPI.idl:

[Exposed=(Window,Worker)]
interface Crypto {
  [SecureContext] readonly attribute SubtleCrypto subtle;
  ArrayBufferView getRandomValues(ArrayBufferView array);
  [SecureContext] DOMString randomUUID();
};

It would be really great if it is extracted in json files as well.
/ed/dfns/WebCryptoAPI.json:

{
      "id": "dfn-Crypto-attribute-subtle",
      "href": "https://w3c.github.io/webcrypto/#dfn-Crypto-attribute-subtle",
++    "requiresSecureContext": true,
      "linkingText": [
        "subtle"
      ],
      "localLinkingText": [
        "Crypto.subtle"
      ],
      "type": "attribute",
      "for": [
        "Crypto"
      ],
      "access": "public",
      "informative": false,
      "heading": {
        "id": "Crypto-attribute-subtle",
        "href": "https://w3c.github.io/webcrypto/#Crypto-attribute-subtle",
        "title": "The subtle attribute",
        "number": "10.2.1"
      },
      "definedIn": "prose"
    },

We want to automate adding these secure context headers to mdn/content repo. It will be really easy to extract the info from .json files rather than processing .idl files.

[tidoust]

Depending on what your exact needs are, I'd say that this information already exists in JSON files in Webref... or indeed that it does not ;)

Parsed versions of (curated) IDL extracts are available as JSON files in the curated branch (roughly described in the README):
https://github.com/w3c/webref/tree/curated/ed/idlparsed

The idlparsed.json JSON schema in Reffy describes the outline of these extracts. The items of interest are going to be under idlNames and idlExtendedNames. The values there are the result of running the webidl2.js parser on the underlying IDL fragments.

Taking the example of the Crypto interface, the file lists the extended attributes of the subtle attribute, which include SecureContext.

Now, while these JSON extracts are more directly processable than the IDL files, they are not enough to answer the question "Is this particular attribute or method only available in secure contexts?" because answering that question in the generic case requires resolving mixins and partials, as done by @wbamberg in the SecureContext checker. Is that the question that you'd like to answer?

If so, then there's indeed no direct way to gather that information from Webref. The idlparsed extracts could perhaps be extended to add some sort of requiresSecureContext property to note the practical outcome. But then whether a mixin member is SecureContext or not can change depending on the interfaces that include the mixin, as discussed with @wbamberg in the #writing-docs channel of the Open Web Docs Slack a few weeks ago, and illustrated by the following example:

interface mixin M {
  undefined mixinMember();
};

/* Interface I is only exposed to secure contexts. */
/* So mixinMember() can only exist in secure contexts for I. */
[Exposed=*, SecureContext]
interface I {};
I includes M;

/* For mixins, evaluation depends on the underlying interface. */
/* Here, the same mixinMember() member is defined in non secure contexts for K. */
interface K {};
K includes M;

... and the idlparsed extracts (same for dfns extracts) only contain one entry per mixin.

The idlnamesparsed extracts, which collect all IDL fragments per interface, might be a better place to store the info, especially since I think they would provide a more natural hook to find the right information in an MDN context (where I suppose the interface name is a good starting point), as I don't know how you'd find the right idlparsed to look at otherwise. The idlnamesparsed extracts don't detail anything on top of the IDL fragment and don't directly map to idlparsed extracts either. But we can probably improve that!

Side note: We would prefer dfns extraction to remain fully orthogonal to any kind of IDL curation and processing, so storing the information in dfns extracts does not seem like the right approach for this (and wouldn't be a good match with the mixin issue mentioned above).

[OnkarRuikar]

@tidoust Thanks for the detailed info!

Side note: We would prefer dfns extraction to remain fully orthogonal to any kind of IDL curation and processing, so storing the information in dfns extracts does not seem like the right approach for this

I see and agree. I've found some cases where spec docs simply put blank statement saying all the feature here require secure context but they don't use [SecureContext] in syntax sections. Consider following cases:

1. Web Periodic Background Synchronization doc mentions "As this API relies on service workers, functionality provided by this API is only available in a secure context." But it doesn't use the [SecureContext] tag in any syntax.
2. ExtendableCookieChangeEvent: the interface in the section before mentions secure context but the event doesn't.

I mean, if we fix the source (spec docs) itself then we may not have to worry about so many inconsistencies. If you wish, I can send PR(s) to fix the docs.

[tidoust]

I mean, if we fix the source (spec docs) itself then we may not have to worry about so many inconsistencies. If you wish, I can send PR(s) to fix the docs.

Yes, that's the process we try to follow in Webref: never create a patch unless there's a related issue/PR raised against the spec, and always link back to that issue/PR from the patch.

Now, the IDL patches that we have in Webref are not even meant to fix the problem that you raise here: from a Webref perspective, we only want to make sure that the IDL can be parsed and is consistent with the IDL defined in other specs. The goal is to stay as close as possible to what the spec defines because the spec should be the single source of truth, and not to improve the IDL fragments ourselves. In other words, by all means, go ahead and report these issues in the repos of the specs!

[OnkarRuikar]

The goal is to stay as close as possible to what the spec defines because the spec should be the single source of truth, and not to improve the IDL fragments ourselves. In other words, by all means, go ahead and report these issues in the repos of the specs!

@tidoust I have submitted some pull requests to the repos. But they do not want redundancy in the spec docs.

Inviting @annevk to the conversation.

[annevk]

1. Something only exposed to service workers is by definition limited to secure contexts because service workers are limited to secure contexts. An IDL tool can presumably know this, though it's somewhat of an advanced question I suppose. We should not add [SecureContext] redundantly to such interfaces.
2. There are some interfaces that are exposed everywhere, but their functionality is guarded by a secure context check (or a permission check that is guarded by a secure context check). Example: Notifications API. This will require some kind of custom handling.

I very much doubt any of the PRs opened above is correct as the features are likely either 1 or 2.

[tidoust]

1. Something only exposed to service workers is by definition limited to secure contexts because service workers are limited to secure contexts. An IDL tool can presumably know this, though it's somewhat of an advanced question I suppose. We should not add [SecureContext] redundantly to such interfaces.

I see. The interface is defined with an [Exposed=ServiceWorker] attribute, Service workers are secure context only, so the interface de facto has [SecureContext] as well, no need to repeat that. That seems fine and means that the globals need to be taken into account when computing whether an interface is exposed to secure contexts only.

Now I'm wondering whether there's a way to infer that "Service Workers are secure context only" through IDL only. Typically, the [Exposed=ServiceWorker] targets the global name ServiceWorker, which is attached to the interface ServiceWorkerGlobalScope. That interface is not defined as [SecureContext] (although most other Service Workers interfaces are).

Should ServiceWorkerGlobalScope have a [SecureContext] extended attribute? Or do tools need to maintain a list of globals that are secure context only? Or am I misreading the IDL?

2. There are some interfaces that are exposed everywhere, but their functionality is guarded by a secure context check (or a permission check that is guarded by a secure context check). Example: Notifications API. This will require some kind of custom handling.

OK, if they are exposed everywhere, it seems wrong to flag them as secure context only in any case. @OnkarRuikar I'll let you figure out a way to document these cases in BCD/MDN, I don't think there's much we can do at the Webref level.

[annevk]

It's a good question if ServiceWorkerGlobalScope should have [SecureContext]. It ends up being redundant with other requirements, so probably not, but I suppose a case could be made.

[tidoust]

Looking into globals known to Webref, the only globals that are secure context but that are not flagged as such in the IDL seem to be ServiceWorkerGlobalScope and the 3 globals defined in Turtledove:

• ServiceWorkerGlobalScope
• InterestGroupBiddingScriptRunnerGlobalScope
• InterestGroupScoringScriptRunnerGlobalScope
• InterestGroupReportingScriptRunnerGlobalScope

Other globals are either not secure context only, I believe:

• Window
• DedicatedWorkerGlobalScope
• SharedWorkerGlobalScope
• RTCIdentityProviderGlobalScope

... or they inherit from WorkletGlobalScope, which is explicitly defined with a [SecureContext] attribute:

• AnimationWorkletGlobalScope
• LayoutWorkletGlobalScope
• PaintWorkletGlobalScope
• SharedStorageWorkletGlobalScope
• AudioWorkletGlobalScope

I don't know whether that makes a case for adding [SecureContext] to ServiceWorkerGlobalScope. It's at least interesting to note that WorkletGlobalScope has the attribute ;)

[tidoust]

Also of interest: @wbamberg's blog post on Using Web IDL for better web docs.

One concrete outcome of this discussion is that [SecureContext] was added to ServiceWorkerGlobalScope, which seems good and improves the ability to derive the secure context only status automatically.

Looking at it from a Webref perspective, @dontcallmedom and I would prefer to continue to restrict Webref extracts to the raw IDL (and raw result of parsing that IDL) and leave computations and analyses on the IDL to Webref consumers for now, especially since we don't see a fantastic place where we could store the result of these computations (idlparsed extracts do not seem like a good place given the need to consider mixins, idlnamesparsed extracts do not contain the right level of details, and we're not clear that many people rely on these extracts in any case). I'm closing this issue accordingly but we're happy to revisit if the need proves to be a common one.