DOM lib: Add support for Trusted Types API

koto commented 5 years ago

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:

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

engelsdamien commented 4 years ago

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

koto commented 4 years ago

Trusted Types are now available in Chrome canary.

wibimaster commented 4 years ago

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

shicks commented 3 years ago

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

shhnjk commented 3 years ago

@RyanCavanaugh, any update on this?

koto commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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

shicks commented 2 years ago

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 commented 2 years ago

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

microsoft / TypeScript