diff --git a/files/en-us/web/javascript/reference/global_objects/eval/index.md b/files/en-us/web/javascript/reference/global_objects/eval/index.md index 9f430c1d683440a..398b1dd8f690f54 100644 --- a/files/en-us/web/javascript/reference/global_objects/eval/index.md +++ b/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 `