OWD project: Consistently document Web platform security requirements in MDN reference docs

[Elchi3]

Problem statement

Certain Web Platform APIs are only available behind certain security requirements, for example:

• Secure contexts
• Permission API permission
• User Activation
• Cross Origin Isolation (COI), see SharedArrayBuffer and others.

MDN documentation authors have no consistent way to record these security requirements and therefore these requirements aren't displayed nicely to MDN readers. New powerful Web Platform features come with security requirements very often. Web developers need to find security information at a consistent and reliable place in the documentation.

Proposed solutions

We could introduce a front-matter key on the authoring side. For example, something like this:

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

(Some information is also available in IDLs in webref, maybe we can programmatically add security requirements to the front-matter)

From this, we need to figure out how to render the information. Some pages already have a "Security requirements" section, like https://developer.mozilla.org/en-US/docs/Web/API/Performance/measureUserAgentSpecificMemory#security_requirements. It might be good to come up with boilerplate text or similar, so that security requirements are always talked about in the same way.

The https://developer.mozilla.org/en-US/docs/Web/Security section needs to be worked on. For each security concept of the web platform, we need docs that we can point to.

Task list

• Agree on a front-matter for security-requirements
• Investigate auto-populating front-matter items using webref
• Design a content section "Security requirements" that can be used in reference docs
• Decide what to do about banners (secure context has banners, maybe generalize or add even more banners? 🙀)
• Update MDN's Security docs section
• Update all the reference docs so their security requirements are consistent and clear
• ... Likely more

Priority assessment

• Effort: Large. Touches a lot of pages and requires agreeing on re-usable content structures.
• Dependencies: Might depend a bit on yari/infra as we can imagine to script some automation here.
• Community enablement: Once we agreed on structures, we can work with the community to roll it out to reference pages that are in need of such a security section.
• Momentum: More and more Web platform features will have to talk about how to enable them using these security mechanisms
• Enabling learners: Security requirements can be obstacles for learners. They need to know how to solve them.
• Enabling professionals: Professionals will appreciate having this information displayed consistently
• Underrepresented topics / Ethical web: n/a
• Operational necessities: no
• Addressing needs of the web industry: I think so? I have no surveys to quote but I assume that more and more people run into sec requirements that they will need education about.

More information

Related MDN discussion: mdn/mdn-community#288

Open Web Docs (OWD) is a non-profit collective funded by corporate and individual donations.

In order for this project to happen, please consider donating to OWD on https://opencollective.com/open-web-docs.
For more information on sponsorship and membership tiers, see https://openwebdocs.org/membership/

More information is available at https://openwebdocs.org.
For questions, please reach out to [email protected].