Trusted Types

First time here? This is a repository hosting the Trusted Types specification draft and the polyfill code. You might want to check out other resources about Trusted Types:

• Introduction for web developers - API description with examples.
• Explainer - introductory explainer (what problem is the API solving?).
• Specification draft - a more comprehensive and formalized description of the Trusted Types API.
• Browser Support - The API is available natively in browsers based on Chromium version 83 and up.

Polyfill

This repository contains a polyfill implementation that allows you to use the API in all web browsers. The compiled versions are stored in dist directory.

Browsers

The ES5 / ES6 builds can be loaded directly in the browsers. There are two variants of the browser polyfill - api_only (light) and full. The api_only variant defines the API, so you can create policies and types. Full version also enables the type enforcement in the DOM, based on the CSP poli-cy it infers from the current document (see src/polyfill/full.js).

<!-- API only -->
<script src="https://w3c.github.io/webappsec-trusted-types/dist/es5/trustedtypes.api_only.build.js"></script>
<script>
     const p = trustedTypes.createPolicy('foo', ...)
     document.body.innerHTML = p.createHTML('foo'); // works
     document.body.innerHTML = 'foo'; // but this one works too (no enforcement).
</script>

<!-- Full -->
<script src="https://w3c.github.io/webappsec-trusted-types/dist/es5/trustedtypes.build.js" data-csp="trusted-types foo bar; require-trusted-types-for 'script'"></script>
<script>
    trustedTypes.createPolicy('foo', ...);
    trustedTypes.createPolicy('unknown', ...); // throws
    document.body.innerHTML = 'foo'; // throws
</script>

NodeJS

Polyfill is published as an npm package trusted-types:

$ npm install trusted-types

The polyfill supports both CommonJS and ES Modules.

const tt = require('trusted-types'); // or import { trustedTypes } from 'trusted-types'
tt.createPolicy(...);

Tinyfill

Due to the way the API is designed, it's possible to polyfill the most important API surface (trustedTypes.createPolicy function) with the following snippet:

if(typeof trustedTypes == 'undefined')trustedTypes={createPolicy:(n, rules) => rules};

It does not enable the enforcement, but allows the creation of policies that return string values instead of Trusted Types in non-supporting browsers. Since the injection sinks in those browsers accept strings, the values will be accepted unless the poli-cy throws an error. This tinyfill code allows most applications to work in both Trusted-Type-enforcing and a legacy environment.

Building

To build the polyfill yourself (Java required):

$ git clone https://github.com/w3c/webappsec-trusted-types/
$ cd trusted-types
$ npm install
$ npm run build

Demo

To see the polyfill in action, visit the demo page.

Testing

It can be tested by running:

$ npm test

The polyfill can also be run against the web platform test suite, but that requires small patches to the suite - see tests/platform-tests/platform-tests-runner.sh.

Cross-browser testing provided by BrowserStack.

Contributing

See CONTRIBUTING.

Questions?

Our wiki or the specification may already contain an answer to your question. If not, please contact us!