DOM lib: Add support for Trusted Types API

[tosmolka]

This PR adds support for Trusted Types APIs and Sinks in dom and worker libraries. These APIs are so far only supported by Blink. In microsoft/TypeScript#30024 we seem to be getting an agreement to include this change anyway.

[github-actions]

Thanks for the PR!

This section of the codebase is owned by @saschanaz - if they write a comment saying "LGTM" then it will be merged.

[saschanaz]

This needs multiple implementor interest.

[shicks]

My understanding is that there are polyfill options for other browsers, making appropriate typings still pretty important.

[orta]

You're welcome to use DefinitelyTyped if you'd like to ship types which only work on a single engine 👍🏻 - though it might be quite difficult given how much existing code this affects.

[shicks]

Either way, this needs to take advantage of the new differently-typed getter/setter feature in order to be properly backwards-compatible. For example,

interface Element {
  get outerHTML(): string;
  set outerHTML(html: string|TrustedHTML);
}

[tosmolka]

@shicks , can you please take another look? Do you think this would be backwards-compatible? I ended up introducing setterType as I could not find a way to do what we wanted with current implementation of emitProperty. Happy to choose different approach if needed.

[shicks]

This looks much better. IIUC, the TypeScript team has a corpus of real world code that they can compile against - presumably they'd want to test this against that corpus to make sure it doesn't break anything significant.

The main breakage I anticipate at this point is if anybody is implementing the DOM API (i.e. like a NodeJS virtual DOM) - but at this point anybody who's just using the DOM should be fine.

[lgarron]

We're prototyping the use of TrustedHTML at GitHub, and would really love to see this land!

[DanielRosenwasser]

Can you give me some more insight into TrustedHTML nodes? Is it really this simple of an interface, or is there something "more" to them?

The reason I ask is that in a structural language like TypeScript, you could accidentally assign lots of stuff to TrustedHTML. Is there some internal runtime bit set, or is this really anything with a toJSON and a toString?

[lgarron]

TrustedHTML is interesting, in that it's both an interface and also the name of a global object.

So it's sort of like a class (you can do value instanceof TrustedHTML), but the main point of the API is that it can't be constructed without the Trusted Types API. Sort of like you have to do document.createElement("div") instead of new HTMLDivElement().

Each TrustedHTML instance is also associated with a specific string policy. So conceptually it might make sense to have something like TrustedHTML<"dompurify">. I don't know if it makes sense to include that in TypeScript, though. The "dompurify" policy in that case is something that would be enforced by CSP for e.g. innerHTML assignment, which seems a bit outside the scope of type checking.

https://developer.mozilla.org/en-US/docs/Web/API/TrustedHTML#methods

[weswigham]

Maybe consider emitting a class with a private constructor instead of an interface with only these very-widespread-methods (and the static pseudo-constructor)? That'd be allowable in instanceof and a private member should enable nominal checking (and thus forbid structural matches).

[lgarron]

How would that interact with something like DefinitelyTyped/DefinitelyTyped#60417 ?

Element classes like HTMLDivElement are declared using the same interface+var pattern as this PR. Is there a particular reason to diverge from that entirely?

For what it's worth, new HTMLDivElement() also doesn't error in TypeScript today.

[lgarron]

Is there any chance of moving this forward in the near future?

DefinitelyTyped/DefinitelyTyped#61160 was making some progress last month, but my understanding is that it will still be hard to use if the Element.innerHTML setter still only allows string assignment in lib.dom.d.ts. This makes it rather tricky to use trusted types in practice, without working around lots of errors. 😔

[saschanaz]

So far no implementer interest outside of Google, so a progress can happen when something happens there.

[lgarron]

So far no implementer interest outside of Google, so a progress can happen when something happens there.

🙋 We are actively working on exploring trusted types on the github.com site, and are specifically running into challenges with the concrete implementation due to this. 🤓

By implementer, I'm guessing you might mean just browsers, though?

Is there any way to make the innerHTML setter type at least compatible with TrustedHTML from @types/trusted-types? That would make a big difference.
(For example, one blunt possibility would be for .innerHTML to accept any string or any object with toString().)

[saschanaz]

By implementer, I'm guessing you might mean just browsers, though?

Yes.

Is there any way to make the innerHTML setter type at least compatible with TrustedHTML from @types/trusted-types? That would make a big difference.

That's really a thing that needs a Microsoft decision, but I think TS should support overloading the setter declaration to make it compatible.

[koto]

So far no implementer interest outside of Google, so a progress can happen when something happens there.

There is now multi implementor interest: mozilla/standards-positions#20 (comment), with a Gecko implementation progressing. Implementation in WebKit is also ongoing. What are the next best steps?

[saschanaz]

When the feature ships, MDN data will be updated and that will be automatically reflected here.

[koto]

When the feature ships, MDN data will be updated and that will be automatically reflected here.

Do you mean browser compat data on MDN? I think browser compat data on MDN is manually updated, at least that was the case when the Trusted Types shipped in Chrome. Once that happens (which, I guess, is after shipping in Gecko or WebKit), what is actually happening automatically in this repo? Trusted Types APIs are already largely integrated in HTML, DOM and other specs (e.g. https://dom.spec.whatwg.org/#parentnode).

Sorry for those basic questions, I'm just trying to figure out what needs manual work and when is it best to do that work. It seems like the 'when' part is after 2nd implementation part ships, but I don't know yet the 'what' part.

[HolgerJeromin]

Do you mean browser compat data on MDN? I think browser compat data on MDN is manually updated, at least that was the case when the Trusted Types shipped in Chrome.

Yes. After that a friendly bot will come along and create here a PR like this: #1726