DOM lib: Add support for Trusted Types API

[koto]

Search Terms

Trusted Types, DOM

Suggestion

Trusted Types (spec, introductory article) is a new experimental DOM API implemented within the WICG , with a working Chrome implementation.

The API creates a few new objects available on the global object in the browser, like most other web APIs (impl in TS and in Closure compiler).

Under certain conditions, controlled by a HTTP header (analogous to Content-Security-Policy behavior), the API can enable the enforcement - then it changes the signature of several DOM API functions and property setters, such that they accept specific object types, and reject strings. Colloquially, DOM API becomes strongly typed.

For example, with Trusted Types Element.innerHTML property setter accepts a TrustedHTML object.

Trusted Type objects stringify to their inner value. This API shape is a deliberate choice that enables existing web applications and libraries to gradually migrate from strings to Trusted Types without breaking functionality. In our example, it makes it possible to write the following:

const policy = TrustedTypes.createPolicy('foo', { 
  createHTML: (s) => { /* some validation*/; return s} 
});

const trustedHTML = policy.createHTML('bar');
anElement.innerHTML = trustedHTML

anElement.innerHTML === 'bar'

The above code works regardless if the Trusted Types enforcement is enabled or not.

Reading from the DOM is unaffected, so Element.innerHTML getter returns a string. That's for practical reasons -- web applications read from DOM more often than they write to it, and only writing exposes the application to DOM XSS risks. Typing only the setters allows us to secure web applications with minimal code changes.

It's difficult to map that API using TS types (due to #2521). The only way is to change the DOM sink functions to have the any type, which is obviously suboptimal.

Use Cases

Writing a TS application that uses the Trusted Types API.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[engelsdamien]

For an additional data point, the way the closure compiler supports those sink assignments seems to be through the @implicitCast annotation.

[koto]

Trusted Types are now available in Chrome canary.

[wibimaster]

Need it, it's on Chrome official release :x

[shicks]

FWIW, it looks like there's finally some traction on #2521 so this might become feasible at some point.

[shhnjk]

@RyanCavanaugh, any update on this?

[koto]

The setters/getters typing needed to unblock this will, to my understanding, ship in 4.3. Should we create a PR to change the lib.dom.d.ts type annotation for the sinks to align with https://w3c.github.io/webappsec-trusted-types/dist/spec/ ? Essentially, in a couple of places in DOM the setter type would be TrustedHTML | string (or similar unions for other types), instead of string.

[aryzing]

Seems to we well supported now

• https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy

Would be great to have TS support for this.

[shicks]

The necessary TS language support landed in 4.3: https://devblogs.microsoft.com/typescript/announcing-typescript-4-3/#separate-write-types

I had assumed somebody was updating the standard library declarations to accommodate this, but maybe that never happened? In any case, as far as I'm aware that's all that's left to do, and it should be pretty straightforward.

[shhnjk]

Should we create a PR to change the lib.dom.d.ts type annotation for the sinks to align with https://w3c.github.io/webappsec-trusted-types/dist/spec/ ? Essentially, in a couple of places in DOM the setter type would be TrustedHTML | string (or similar unions for other types), instead of string.

Yes, if you have bandwidth @koto! :)

[tosmolka]

This is starting to block our adoption of Trusted Types so we took a look as well. Is microsoft/TypeScript-DOM-lib-generator#1246 roughly what you guys had in mind as next step? Can you pls take a look? Thanks.

[shicks]

microsoft/TypeScript-DOM-lib-generator#1246 is backward-incompatible and will break a bunch of existing code. The fix is to only widen the type on writing, while leaving the read type the same:

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

[tosmolka]

@shicks , the PR with the fix has been updated, can you please check the fix again for backward-compatibility? Thanks.