W3cubDocs

/Web APIs

TrustedTypePolicyFactory: createPolicy() method

The createPolicy() method of the TrustedTypePolicyFactory interface creates a TrustedTypePolicy object that implements the rules passed as policyOptions.

The default policy

In Chrome a policy with a name of "default" creates a special policy that will be used if a string (rather than a Trusted Type object) is passed to an injection sink. This can be used in a transitional phase while moving from an application that inserted strings into injection sinks.

Note: The above behavior is not yet settled in the specification and may change in future.

Warning: A lax default policy could defeat the purpose of using Trusted Types, and therefore should be defined with strict rules to ensure it cannot be used to run dangerous code.

Syntax

js

createPolicy(policyName, policyOptions)

Parameters

policyName

A string with the name of the policy.

policyOptions Optional

User-defined functions for converting strings into trusted values.

createHTML(input[,args])

A callback function in the form of a string that contains code to run when creating a TrustedHTML object.

createScript(input[,args])

A callback function in the form of a string that contains code to run when creating a TrustedScript object.

createScriptURL(input[,args])

A callback function in the form of a string that contains code to run when creating a TrustedScriptURL object.

Return value

Exceptions

TypeError

Thrown if policy names are restricted by the Content Security Policy trusted-types directive and this name is not on the allowlist.

TypeError

Thrown if the name is a duplicate and the Content Security Policy trusted-types directive is not using allow-duplicates.

Examples

The below code creates a policy with the name "myEscapePolicy" with a function defined for createHTML() which sanitizes HTML.

js

const escapeHTMLPolicy = trustedTypes.createPolicy("myEscapePolicy", {
  createHTML: (string) => string.replace(/>/g, "<"),
});

Creating a default policy

On a site where Trusted Types are enforced via a Content Security Policy with the require-trusted-types-for directive set to script, any injection script that accepts a script expects a Trusted Type object. In the case that a string is inserted instead, the following default policy will be used.

The policy logs a message to the console to remind the developer to refactor this part of the application to use a Trusted Type object. It also appends details of the use of the default policy, type, and injection sink to the returned value.

js

trustedTypes.createPolicy("default", {
  createScriptURL: (s, type, sink) => {
    console.log("Please refactor.");
    return `${s}?default-policy-used&type=${encodeURIComponent(
      type,
    )}&sink=${encodeURIComponent(sink)}`;
  },
});

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
createPolicy 83 83 No No 69 No 83 83 No 59 No 13.0

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/createPolicy