Browse Source

docs: update contextIsolation documentation on access to globals (#19732)

Shiranka Miskin 4 years ago
parent
commit
ec85a91472
2 changed files with 13 additions and 14 deletions
  1. 11 12
      docs/api/browser-window.md
  2. 2 2
      docs/tutorial/security.md

+ 11 - 12
docs/api/browser-window.md

@@ -337,18 +337,17 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       more details.
     * `contextIsolation` Boolean (optional) - Whether to run Electron APIs and
       the specified `preload` script in a separate JavaScript context. Defaults
-      to `false`. The context that the `preload` script runs in will still
-      have full access to the `document` and `window` globals but it will use
-      its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.)
-      and will be isolated from any changes made to the global environment
-      by the loaded page. The Electron API will only be available in the
-      `preload` script and not the loaded page. This option should be used when
-      loading potentially untrusted remote content to ensure the loaded content
-      cannot tamper with the `preload` script and any Electron APIs being used.
-      This option uses the same technique used by [Chrome Content Scripts][chrome-content-scripts].
-      You can access this context in the dev tools by selecting the
-      'Electron Isolated Context' entry in the combo box at the top of the
-      Console tab.
+      to `false`. The context that the `preload` script runs in will only have
+      access to its own dedicated `document` and `window` globals, as well as
+      its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.),
+      which are all invisible to the loaded content. The Electron API will only
+      be available in the `preload` script and not the loaded page. This option
+      should be used when loading potentially untrusted remote content to ensure
+      the loaded content cannot tamper with the `preload` script and any
+      Electron APIs being used.  This option uses the same technique used by
+      [Chrome Content Scripts][chrome-content-scripts].  You can access this
+      context in the dev tools by selecting the 'Electron Isolated Context'
+      entry in the combo box at the top of the Console tab.
     * `worldSafeExecuteJavaScript` Boolean (optional) - If true, values returned from `webFrame.executeJavaScript` will be sanitized to ensure JS values
       can't unsafely cross between worlds when using `contextIsolation`.  The default
       is `false`. In Electron 12, the default will be changed to `true`. _Deprecated_

+ 2 - 2
docs/tutorial/security.md

@@ -233,8 +233,8 @@ practice, that means that global objects like `Array.prototype.push` or
 Electron uses the same technology as Chromium's [Content Scripts](https://developer.chrome.com/extensions/content_scripts#execution-environment)
 to enable this behavior.
 
-Even when you use `nodeIntegration: false` to enforce strong isolation and
-prevent the use of Node primitives, `contextIsolation` must also be used.
+Even when `nodeIntegration: false` is used, to truly enforce strong isolation
+and prevent the use of Node primitives `contextIsolation` **must** also be used.
 
 ### Why & How?