[Docs] Fix documentation of onclick to make it clear 1) the data is not HTML escaped 2) there is also a href option alternative

[mousetail]

This should really just be fixed but that would probably break things. For now this updates the documentation to make it clear you need to be super careful using this API.

[hunvreus]

Can you give me a specific example to help me understand what issue may come out of this?

[mousetail]

Suppose I have this example:

  const name = prompt("Enter your name");

  document.dispatchEvent(
    new CustomEvent("basecoat:toast", {
      detail: {
        config: {
          category: 'info',
          title: `Your name is ${name}`,
          description: 'lorem ipsum',
          cancel: {
            label: "Dismiss",
          },
        },
      },
    })
  );

It's not obvious that this code is bugged. It's going to cause invalid output for a whole range of valid inputs. For example, if I enter </div> the result is this:

Which is a bug but not dangerous. However, I can also enter this:

<img src onerror="alert(window.location.origin)">

which is an XSS attack

This is a huge footgun and a security issue. In this case, I can only XSS myself but imagine if you could control the toast title or description of a message sent to another user. The security issue might not be immediately caught by developers since it only triggers if you use certain characters in your string.

Most other libraries mark APIs that directly assign HTML as dangerous. For example, React has dangerouslySetInnerHTML. Here, not only is the dangerous API the only version but the documentation doesn't even state that these are incredibly dangerous methods.

Most template engines automatically escape any strings inserted in HTML by default.

Injection attacks are the #5 most common kind of security vulnerability acoring to OWASP

Owasp recomends:

The preferred option is to use a safe API, which avoids using the interpreter entirely, provides a parameterized interface, or migrates to Object Relational Mapping Tools (ORMs). Note: Even when parameterized, stored procedures can still introduce SQL injection if PL/SQL or T-SQL concatenates queries and data or executes hostile data with EXECUTE IMMEDIATE or exec().

I would recommend offering a safe API, at least by default. You could potential offer a mechanic for manually setting the HTML for specialized use cases but in my opinion the default API should be safe and the dangers of any alternative APIs should be well described.