Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
7 tasks
Elchi3 opened this issue Jan 10, 2023 · 0 comments
Assignees
Labels
proposal (actionable) Enough information is provided and the work is scoped well. Actionable but not prioritized right now

Comments

@Elchi3
Copy link
Member

Elchi3 commented Jan 10, 2023

Problem statement

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

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].

@Elchi3 Elchi3 added proposal (actionable) Enough information is provided and the work is scoped well. Actionable but not prioritized right now H2 2023 Projects for July-December 2023 and removed not ready labels Jun 27, 2023
@Elchi3 Elchi3 mentioned this issue Jul 3, 2023
6 tasks
@Elchi3 Elchi3 removed the H2 2023 Projects for July-December 2023 label Jan 19, 2024
@Elchi3 Elchi3 mentioned this issue Feb 1, 2024
@Elchi3 Elchi3 added the H1 2024 Projects for the first half of 2024 label Feb 1, 2024
@Elchi3 Elchi3 removed the H1 2024 Projects for the first half of 2024 label May 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
proposal (actionable) Enough information is provided and the work is scoped well. Actionable but not prioritized right now
Projects
None yet
Development

No branches or pull requests

1 participant