A browser API to prevent DOM-Based Cross Site Scripting in modern web applications.
![npm bundle size](https://img.shields.io/bundlephobia/minzip/trusted-types.svg)
![Libraries.io dependency status for latest release](https://img.shields.io/librariesio/release/npm/trusted-types.svg)
![GitHub issues](https://img.shields.io/github/issues/w3c/trusted-types.svg)
![npm](https://img.shields.io/npm/v/trusted-types.svg)
[![BrowserStack Status](https://www.browserstack.com/automate/badge.svg?badge_key=eGZQNXU1U09vZjkrZzYzU3YrQ2FsbUpheGczR0VmMTZUSjBydnNjd1pKTT0tLTZPMWVJTnU1UHJvYjFCb0pHQmlsaXc9PQ%3d%3d--295829245abf0dd0cd150f9ca4fe3198da38747b)](https://www.browserstack.com/automate/public-build/eGZQNXU1U09vZjkrZzYzU3YrQ2FsbUpheGczR0VmMTZUSjBydnNjd1pKTT0tLTZPMWVJTnU1UHJvYjFCb0pHQmlsaXc9PQ%3d%3d--295829245abf0dd0cd150f9ca4fe3198da38747b)

# 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](https://web.dev/trusted-types/) - API description with examples.
 * [Explainer](explainer.md) - introductory explainer (what problem is the API solving?).
 * [Specification draft](https://w3c.github.io/trusted-types/dist/spec/) - a more comprehensive and formalized description of the Trusted Types API.
 * [Browser Support](https://caniuse.com/trusted-types) - 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](dist/).

### 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 policy it infers from the current document (see [src/polyfill/full.js](src/polyfill/full.js)).

```html
<!-- 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>
```

```html
<!-- 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](https://www.npmjs.com/package/trusted-types):

```sh
$ npm install trusted-types
```

The polyfill supports both CommonJS and ES Modules.

```javascript
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:

```javascript
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 policy 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):

```sh
$ 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](https://w3c.github.io/trusted-types/demo/).

## Testing
It can be tested by running:
```sh
$ npm test
```
The polyfill can also be run against the [web platform test suite](https://github.com/w3c/web-platform-tests), but that requires small patches to the suite - see [tests/platform-tests/platform-tests-runner.sh](tests/platform-tests/platform-tests-runner.sh).

Cross-browser testing provided by BrowserStack.

<a href="https://www.browserstack.com">
  <img height="70" src="assets/browserstack-logo.svg" alt="BrowserStack">
</a>

# Contributing

See [CONTRIBUTING](CONTRIBUTING.md).

# Questions?

Our [wiki](https://github.com/w3c/trusted-types/wiki) or the [specification](https://w3c.github.io/trusted-types/dist/spec/) may already contain an answer
to your question. If not, please [contact us](https://github.com/w3c/trusted-types/wiki/Contact)!
