TrustedTypes: Function() constructor + eval() (#42462)

Author: hamishwillee

files/en-us/web/javascript/reference/global_objects/eval/index.md

@@ -7,7 +7,12 @@ sidebar: jssidebar
 ---
 
 > [!WARNING]
-> Executing JavaScript from a string is an enormous security risk. It is far too easy for a bad actor to run arbitrary code when you use `eval()`. See [Never use direct eval()!](#never_use_direct_eval!), below.
+> The argument passed to this method is dynamically evaluated and executed as JavaScript.
+> APIs like this are known as [injection sinks](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage), and are potentially a vector for [cross-site-scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
+>
+> You can mitigate this risk by always passing {{domxref("TrustedScript")}} objects instead of strings and [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types).
+>
+> See [Security considerations](#security_considerations) for more information.
 
 The **`eval()`** function evaluates JavaScript code represented as a string and returns its completion value. The source is parsed as a script.
 
@@ -36,15 +41,22 @@ eval(script)
 ### Parameters
 
 - `script`
-  - : A string representing a JavaScript expression, statement, or sequence of statements. The expression can include variables and properties of existing objects. It will be parsed as a script, so [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) declarations (which can only exist in modules) are not allowed.
+  - : A {{domxref("TrustedScript")}} instance or string representing a JavaScript expression, statement, or sequence of statements.
+    The expression can include variables and properties of existing objects. It will be parsed as a script, so [`import`](/en-US/docs/Web/JavaScript/Reference/Statements/import) declarations (which can only exist in modules) are not allowed.
 
 ### Return value
 
-The completion value of evaluating the given code. If the completion value is empty, {{jsxref("undefined")}} is returned. If `script` is not a string primitive, `eval()` returns the argument unchanged.
+The completion value of evaluating the given code. If the completion value is empty, {{jsxref("undefined")}} is returned.
+If `script` is not a {{domxref("TrustedScript")}} or string primitive, `eval()` returns the argument unchanged.
 
 ### Exceptions
 
-Throws any exception that occurs during evaluation of the code, including {{jsxref("SyntaxError")}} if `script` fails to be parsed as a script.
+- {{jsxref("SyntaxError")}}
+  - : The `script` parameter cannot be parsed as a script.
+- {{jsxref("TypeError")}}
+  - : `script` is a string when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are [enforced by a CSP](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) and no default policy is defined.
+
+The method also throws any exception that occurs during evaluation of the code.
 
 ## Description
 
@@ -60,7 +72,8 @@ In strict mode, declaring a variable named `eval` or re-assigning `eval` is a {{
 const eval = 1; // SyntaxError: Unexpected eval or arguments in strict mode
 ```
 
-If the argument of `eval()` is not a string, `eval()` returns the argument unchanged. In the following example, passing a `String` object instead of a primitive causes `eval()` to return the `String` object rather than evaluating the string.
+If the argument of `eval()` is not a {{domxref("TrustedScript")}} or string, `eval()` returns the argument unchanged.
+In the following example, passing a `String` object instead of a primitive causes `eval()` to return the `String` object rather than evaluating the string.
 
 ```js
 eval(new String("2 + 2")); // returns a String object containing "2 + 2"
@@ -190,7 +203,10 @@ Indirect eval can be seen as if the code is evaluated within a separate `<script
 
 Using direct `eval()` suffers from multiple problems:
 
-- `eval()` executes the code it's passed with the privileges of the caller. If you run `eval()` with a string that could be affected by a malicious party, you may end up running malicious code on the user's machine with the permissions of your webpage / extension. More importantly, allowing third-party code to access the scope in which `eval()` was invoked (if it's a direct eval) can lead to possible attacks that reads or changes local variables.
+- `eval()` executes the code it's passed with the privileges of the caller.
+  If you run `eval()` with a string that could be affected by a malicious party, you may end up running malicious code on the user's machine with the permissions of your webpage / extension.
+  More importantly, allowing third-party code to access the scope in which `eval()` was invoked (if it's a direct eval) can lead to possible attacks that reads or changes local variables.
+  See [Security considerations](#security_considerations) for approaches that mitigate these risks.
 - `eval()` is slower than the alternatives, since it has to invoke the JavaScript interpreter, while many other constructs are optimized by modern JS engines.
 - Modern JavaScript interpreters convert JavaScript to machine code. This means that any concept of variable naming gets obliterated. Thus, any use of `eval()` will force the browser to do long expensive variable name lookups to figure out where the variable exists in the machine code and set its value. Additionally, new things can be introduced to that variable through `eval()`, such as changing the type of that variable, forcing the browser to re-evaluate all of the generated machine code to compensate.
 - Minifiers give up on any minification if the scope is transitively depended on by `eval()`, because otherwise `eval()` cannot read the correct variable at runtime.
@@ -345,8 +361,83 @@ Note that since JSON syntax is limited compared to JavaScript syntax, many valid
 
 Passing carefully constrained data instead of arbitrary code is a good idea in general. For example, an extension designed to scrape contents of web-pages could have the scraping rules defined in [XPath](/en-US/docs/Web/XML/XPath) instead of JavaScript code.
 
+### Security considerations
+
+The method can be used to execute arbitrary input with the privileges of the caller.
+If the input is a potentially unsafe string provided by a user, this is a possible vector for [Cross-site-scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
+
+For example, the following code shows how `eval()` might execute `untrustedCode` provided by a user:
+
+```js example-bad
+const untrustedCode = "alert('Potentially evil code!');";
+const adder = eval(untrustedCode);
+```
+
+Websites with a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) that specifies [`script-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) or [`default-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/default-src) will prevent such code running by default.
+If you must allow the scripts to run via `eval()` you can mitigate the risks by always assigning a {{domxref("TrustedScript")}} instance instead of a string, and [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) using the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) CSP directive.
+This ensures that the input is passed through a transformation function.
+
+To allow `eval()` to run, you will additionally need to specify the [`trusted-types-eval` keyword](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval) in your CSP `script-src` directive.
+
+The [`unsafe-eval`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#unsafe-eval) keyword also allows `eval()`, but is much less safe then `trusted-types-eval` because it would allow execution even on browsers that do not support trusted types.
+
+For example, the required CSP for your site might look like this:
+
+```http
+Content-Security-Policy: require-trusted-types-for 'script'; script-src '<your_allowlist>' 'trusted-types-eval'
+```
+
+The behavior of the transformation function implemented in your trusted types policy will depend on the specific use case that requires a user provided script.
+If possible you should lock the allowed scripts to exactly the code that you trust to run.
+If that is not possible, you might allow or block the use of certain functions within the provided input.
+
 ## Examples
 
+Note that the first example shows how to use the method with trusted types.
+The other examples omit this step for brevity.
+
+### Using TrustedScript
+
+To mitigate the risk of XSS, we should always assign `TrustedScript` instances to the `script` parameter.
+We also need to do this if we're enforcing trusted types for other reasons and we want to allow some script sources that have been permitted (by `CSP: script-src`).
+
+Trusted types are not yet supported on all browsers, so first we define the [trusted types tinyfill](/en-US/docs/Web/API/Trusted_Types_API#trusted_types_tinyfill).
+This acts as a transparent replacement for the Trusted Types JavaScript API:
+
+```js
+if (typeof trustedTypes === "undefined")
+  trustedTypes = { createPolicy: (n, rules) => rules };
+```
+
+Next we create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createScript", "createScript()")}} method for transforming input strings into {{domxref("TrustedScript")}} instances.
+
+For the purpose of this example we'll assume that we have a function `transformedScript()` that defines our tranformation/filtering logic.
+
+```js
+const policy = trustedTypes.createPolicy("script-policy", {
+  createScript(input) {
+    const transformed = transformedScript(input); // Our filter method
+    return transformed;
+  },
+});
+```
+
+Then we use the `policy` object to create a `TrustedScript` object from a potentially unsafe input string:
+
+```js
+// The potentially malicious string
+const untrustedScript = "alert('Potentially evil code!');";
+
+// Create a TrustedScriptURL instance using the policy
+const trustedScript = policy.createScript(untrustedScript);
+```
+
+The `TrustedScript` object can now be passed to `eval()`:
+
+```js
+eval(trustedScriptURL);
+```
+
 ### Using eval()
 
 In the following code, both of the statements containing `eval()` return 42.

files/en-us/web/javascript/reference/global_objects/function/function/index.md

@@ -7,7 +7,16 @@ browser-compat: javascript.builtins.Function.Function
 sidebar: jsref
 ---
 
-The **`Function()`** constructor creates {{jsxref("Function")}} objects. Calling the constructor directly can create functions dynamically, but suffers from security and similar (but far less significant) performance issues as {{jsxref("Global_Objects/eval", "eval()")}}. However, unlike `eval` (which may have access to the local scope), the `Function` constructor creates functions which execute in the global scope only.
+> [!WARNING]
+> The arguments passed this method are dynamically evaluated and executed as JavaScript.
+> APIs like this are known as [injection sinks](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage), and are potentially a vector for [cross-site-scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
+>
+> You can mitigate this risk by always passing {{domxref("TrustedScript")}} objects instead of strings and [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types).
+>
+> See [Security considerations](#security_considerations) for more information.
+
+The **`Function()`** constructor creates {{jsxref("Function")}} objects.
+Calling the constructor directly can create functions dynamically, but suffers from security and similar (but far less significant) performance issues as {{jsxref("Global_Objects/eval", "eval()")}}. However, unlike `eval` (which may have access to the local scope), the `Function` constructor creates functions which execute in the global scope only.
 
 {{InteractiveExample("JavaScript Demo: Function() constructor", "shorter")}}
 
@@ -38,12 +47,24 @@ Function(arg1, arg2, /* …, */ argN, functionBody)
 ### Parameters
 
 - `arg1`, …, `argN` {{optional_inline}}
-  - : Names to be used by the function as formal argument names. Each must be a string that corresponds to a valid JavaScript parameter (any of plain [identifier](/en-US/docs/Glossary/Identifier), [rest parameter](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters), or [destructured](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) parameter, optionally with a [default](/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters)), or a list of such strings separated with commas.
+  - : {{domxref("TrustedScript")}} instances or strings specifying names to be used by the function as formal argument names.
+    The value must correspond to a valid JavaScript parameter (any of plain [identifier](/en-US/docs/Glossary/Identifier), [rest parameter](/en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters), or [destructured](/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring) parameter, optionally with a [default](/en-US/docs/Web/JavaScript/Reference/Functions/Default_parameters)), or a list of such strings separated with commas.
 
-    As the parameters are parsed in the same way as function expressions, whitespace and comments are accepted. For example: `"x", "theValue = 42", "[a, b] /* numbers */"` — or `"x, theValue = 42, [a, b] /* numbers */"`. (`"x, theValue = 42", "[a, b]"` is also correct, though very confusing to read.)
+    As the parameters are parsed in the same way as function expressions, whitespace and comments are accepted.
+    For example: `"x", "theValue = 42", "[a, b] /* numbers */"` — or `"x, theValue = 42, [a, b] /* numbers */"`.
+    (`"x, theValue = 42", "[a, b]"` is also correct, though very confusing to read.)
 
 - `functionBody`
-  - : A string containing the JavaScript statements comprising the function definition.
+  - : A {{domxref("TrustedScript")}} or a string containing the JavaScript statements comprising the function definition.
+
+### Exceptions
+
+- {{jsxref("SyntaxError")}}
+  - : Function parameter arguments can't be evaluated as valid identifiers, or the `functionBody` can't be parsed as a script.
+- {{jsxref("TypeError")}}
+  - : Any parameter is a string when [Trusted Types](/en-US/docs/Web/API/Trusted_Types_API) are [enforced by a CSP](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) and no default policy is defined.
+
+The method also throws any exception that occurs during evaluation of the code.
 
 ## Description
 
@@ -85,8 +106,41 @@ new Function("/*", "*/) {");
 // Doesn't become "function anonymous(/*) {*/) {}"
 ```
 
+### Security considerations
+
+The method can be used to execute arbitrary input passed to any parameter.
+If the input is a potentially unsafe string provided by a user, this is a possible vector for [Cross-site-scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
+For example, the following example assumes the `untrustedCode` was provided by a user:
+
+```js example-bad
+const untrustedCode = "alert('Potentially evil code!');";
+const adder = new Function("a", "b", untrustedCode);
+```
+
+Websites with a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) that specifies [`script-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) or [`default-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/default-src) will prevent such code running by default.
+
+If you must allow the scripts to run via `Function()` you can mitigate these issues by always assigning {{domxref("TrustedScript")}} objects instead of strings, and [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) using the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) CSP directive.
+This ensures that the input is passed through a transformation function.
+
+To allow `Function()` to run, you will additionally need to specify the [`trusted-types-eval` keyword](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#trusted-types-eval) in your CSP `script-src` directive.
+
+The [`unsafe-eval`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy#unsafe-eval) keyword also allows `Function()`, but is much less safe then `trusted-types-eval` because it would allow execution even on browsers that do not support trusted types.
+
+For example, the required CSP for your site might look like this:
+
+```http
+Content-Security-Policy: require-trusted-types-for 'script'; script-src '<your_allowlist>' 'trusted-types-eval'
+```
+
+The behavior of the transformation function will depend on the specific use case that requires a user provided script.
+If possible you should lock the allowed scripts to exactly the code that you trust to run.
+If that is not possible, you might allow or block the use of certain functions within the provided string.
+
 ## Examples
 
+Note that these examples omit the use of trusted types for brevity.
+For code showing the usual approach, see [Using `TrustedScript`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval#using_trustedscript) in `eval()`.
+
 ### Specifying arguments with the Function constructor
 
 The following code creates a `Function` object that takes two arguments.
@@ -147,6 +201,7 @@ sayHello("world");
 
 ## See also
 
+- [Using the function constructor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval#using_the_function_constructor) in `eval()`
 - [`function`](/en-US/docs/Web/JavaScript/Reference/Statements/function)
 - [`function` expression](/en-US/docs/Web/JavaScript/Reference/Operators/function)
 - {{jsxref("Functions", "Functions", "", 1)}}