This is a security question, not a documentation gap. Issue #9 flagged it as such and asked that it stay open rather than be closed from the implementation, because neither this specification nor any implementation constrains the subset today. #13 kept it and named the three undecided cases.
specifications/listing/v1/spec.md §4:
TODO — The permitted Markdown subset for description. This one is a security question rather than an undocumented behaviour: neither this specification nor any implementation constrains the subset today, and a storefront rendering untrusted Markdown from a third-party listing is an injection surface. Raw embedded HTML, javascript: URLs, and remote image references are the three that need deciding.
Why it matters
A listing is authored by a third party and rendered by the storefront. description is Markdown, bounded only at 20 000 characters, and CommonMark permits raw HTML blocks. Every consumer therefore has to make its own sanitisation decision, and any consumer that gets it wrong has stored XSS in a first-party origin.
§4 already took the neighbouring decision explicitly — summary "MUST NOT be rendered as Markdown" — so the asymmetry is visible: the field that cannot hurt anyone is constrained and the field that can is not.
The specification does not have to sanitise anything. It has to say what an author may write, so that consumers converge on one answer instead of each inventing one.
The three that need deciding
- Raw embedded HTML. The direct XSS vector. Forbidding it is the obvious answer and the one most likely to break an existing listing.
javascript: URLs in links. A subset that permits links but not schemes is the usual shape.- Remote image references. Not script execution, but it leaks every storefront viewer's IP and user agent to a third-party host of the author's choosing, and gives the author a per-view beacon.
Worth deciding alongside: whether the answer is "a named profile" (CommonMark minus raw HTML, with an allowed-scheme list) rather than a bespoke list, so implementations can point at something rather than re-derive it.
What deciding it costs
Constraining the subset rejects listings that validate today. That makes it a major version after the first tag — and release PRs #1/#2/#3 are open right now, so it is free until they merge. Of every open TODO this is the one where the deadline has teeth, because the alternative to deciding it early is either a v2 or a permanent injection surface.
Related
This is a security question, not a documentation gap. Issue #9 flagged it as such and asked that it stay open rather than be closed from the implementation, because neither this specification nor any implementation constrains the subset today. #13 kept it and named the three undecided cases.
specifications/listing/v1/spec.md§4:Why it matters
A listing is authored by a third party and rendered by the storefront.
descriptionis Markdown, bounded only at 20 000 characters, and CommonMark permits raw HTML blocks. Every consumer therefore has to make its own sanitisation decision, and any consumer that gets it wrong has stored XSS in a first-party origin.§4 already took the neighbouring decision explicitly —
summary"MUST NOT be rendered as Markdown" — so the asymmetry is visible: the field that cannot hurt anyone is constrained and the field that can is not.The specification does not have to sanitise anything. It has to say what an author may write, so that consumers converge on one answer instead of each inventing one.
The three that need deciding
javascript:URLs in links. A subset that permits links but not schemes is the usual shape.Worth deciding alongside: whether the answer is "a named profile" (CommonMark minus raw HTML, with an allowed-scheme list) rather than a bespoke list, so implementations can point at something rather than re-derive it.
What deciding it costs
Constraining the subset rejects listings that validate today. That makes it a major version after the first tag — and release PRs #1/#2/#3 are open right now, so it is free until they merge. Of every open TODO this is the one where the deadline has teeth, because the alternative to deciding it early is either a v2 or a permanent injection surface.
Related