QoL updates to some pieces of Chrome docs

Change-Id: Id597a8c49a06bd34da4dd525db24a485b592f8da
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5876211
Auto-Submit: Carlos Knippschild <carlosk@chromium.org>
Commit-Queue: Nico Weber <thakis@chromium.org>
Reviewed-by: Nico Weber <thakis@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1357761}

docs/README.md

@@ -55,6 +55,8 @@ used when committed.
 
 ## Document Index
 
+**Note**: this is not an exhaustive list of all documents.
+
 ### Checking Out and Building
 *   [Linux Build Instructions](linux/build_instructions.md) - Linux
 *   [Mac Build Instructions](mac_build_instructions.md) - MacOS
@@ -163,13 +165,14 @@ used when committed.
     Docs for the subsystem that allows one to sync data across devices.
 *   [Ozone Overview](ozone_overview.md) - Ozone is an abstraction layer between
     the window system and low level input and graphics.
-*   [Optimizing Chrome Web UIs](optimizing_web_uis.md) - Notes on making webuis
-    more performant*   [Guidelines for considering branch dates in project planning](release_branch_guidance.md) -
+*   [Guidelines for considering branch dates in project planning](release_branch_guidance.md) -
     What to do (and not to do) around branch dates when scheduling your project
     work.
 *   [WebUI Explainer](webui_explainer.md) - An explanation of C++ and JavaScript
     infrastructural code for Chrome UIs implemented with web technologies (i.e.
     chrome:// URLs).
+*   [Optimizing Chrome Web UIs](optimizing_web_uis.md) - Notes on making webuis
+    more performant
 *   [Watchlists](infra/watchlists.md) - Use watchlists to get notified of CLs
     you are interested in.
 *   [Shutdown](shutdown.md) - Explains the steps of Chrome shutdown, to make it
@@ -336,10 +339,13 @@ used when committed.
 *   [What is Lacros](lacros.md)
 
 ### Misc WebUI-Specific Docs
-*   [Creating WebUI Interfaces in components/](webui_in_components.md) How to
+*   [Creating WebUI Interfaces in components/](webui_in_components.md) - How to
     create a new WebUI component in the `components/` directory.
-*   [Trusted Types on WebUI](trusted_types_on_webui.md) Tips for coding in WebUI
-    with Trusted Types in mind.
+*   [Trusted Types on WebUI](trusted_types_on_webui.md) - Tips for coding in
+    WebUI with Trusted Types in mind.
+*   [chrome-untrusted:// FAQ](chrome_untrusted.md) - Explainer on the usage of
+    the `chrome-untrusted://` scheme for hosting WebUIs that handle
+    untrustworthy content.
 
 ### Media
 *   [Audio Focus Handling](media/audio_focus.md) - How multiple MediaSession
@@ -432,6 +438,10 @@ used when committed.
 *   [D-Bus Mojo Connection Service](dbus_mojo_connection_service.md) - A service
     in Chrome to bootstrap CrOS services' Mojo connection.
 
+### Security
+*   [The Rule Of 2](security/rule-of-2.md) - An imoportant security rule when
+    handling untrustworthy contents (like anything downloaded from the web).
+
 ### Speed
 *   [Chrome Speed](speed/README.md) - Documentation for performance measurements and regressions in Chrome.
 *   [Chrome Speed Metrics](speed_metrics/README.md) - Documentation about user experience metrics on the web and their JavaScript APIs.

docs/chrome_untrusted.md

@@ -14,7 +14,7 @@ Examples of trustworthy content include, the contents of `chrome://version` whic
 
 It is a new scheme which can be used to serve resources bundled with Chrome and that process untrustworthy content. It has the usual protections provided to `chrome://`, e.g. process isolation, but it won’t be default-granted extra capabilities that are default-granted to `chrome://`.
 
-The `-untrusted` suffix indicates that the WebUI processes untrustworthy content. For example, rendering an image provided by users, parsing a PDF file, etc.
+The `-untrusted` suffix indicates that the [WebUI](webui_explainer.md) processes untrustworthy content. For example, rendering an image provided by users, parsing a PDF file, etc.
 
 The `-untrusted` suffix does not mean the web page is designed to do malicious things, or users should not trust it. Instead, the `-untrusted` suffix is to signal to us, Chromium developers, that this page will process untrustworthy content, and should be assumed to be compromised, much like an ordinary renderer process.
 
@@ -32,10 +32,11 @@ Semantic because it indicates to chromium developers and security reviewers that
 
 Historically, `chrome://` pages have been built with the assumption that they are an extension to the browser process, so `chrome://` web pages are granted special capabilities not granted to ordinary web pages. For example, all `chrome://` pages can use Web APIs like camera and mic without requesting permission.
 
-Some WebUIs would like to be able to process untrustworthy content, but granting these capabilities to a `chrome://` page would violate the rule of 2:
-running in an privileged context:
+Some WebUIs would like to be able to process untrustworthy content, but granting these capabilities to a `chrome://` page would violate the [rule of 2](security/rule-of-2.md):
+
  * a `chrome://` page is considered an extension to the browser process
  * the renderer is written in an unsafe programming language (C++).
+ * running in an privileged context:
 
 By using `chrome-untrusted://` we put the untrustworthy content into a sandboxed and non-privileged environment (an ordinary renderer, with no dangerous capabilities). This brings us back to safety, a compromised `chrome-untrusted://` page is no worse than an ordinary web page.
 
@@ -59,17 +60,17 @@ Any team that requires extra capabilities granted to `chrome-untrusted://` shoul
 
 We recommend using Mojo to expose APIs to `chrome-untrusted://`. Mojo for `chrome-untrusted://` works similarly to how it works for `chrome://` with a few key differences:
 
-* Unlike chrome:// pages, chrome-untrusted:// pages don't get access to all renderer exposed Mojo interfaces by default. Use `PopulateChromeWebUIFrameInterfaceBrokers` to expose WebUI specific interfaces to your WebUI. See [this CL](https://crrev.com/c/3138688/5/chrome/browser/chrome_browser_interface_binders.cc) for example.
+* Unlike `chrome://` pages, `chrome-untrusted://` pages don't get access to all renderer exposed Mojo interfaces by default. Use `PopulateChromeWebUIFrameInterfaceBrokers` to expose WebUI specific interfaces to your WebUI. See [this CL](https://crrev.com/c/3138688/5/chrome/browser/chrome_browser_interface_binders.cc) for example.
 * The exposed interface has a different threat model: a compromised `chrome-untrusted://` page could try to exploit the interface (e.g. sending malformed messages, closing the Mojo pipe).
 
-When exposing extra capabilities to chrome-untrusted://, keep in mind:
+When exposing extra capabilities to `chrome-untrusted://`, keep in mind:
 
 * Don't grant any capabilities that we wouldn't grant to a regular renderer. For example, don't expose unrestricted access to Bluetooth devices, but expose a method that opens a browser-controlled dialog where the user chooses a device.
 * What you received (from the WebUI page) is untrustworthy. You must sanitize and verify its content before processing.
 * What you send (to the WebUI page) could be exfiltrated to the Web. Don't send sensitive information (e.g. user credentials). Only send what you actually need.
 * The difference in Mojo interface lifetimes could lead to use-after-free bugs (e.g. a page reloads itself when it shouldn't). We recommend you create and reinitialize the interface on each page load (using [WebUIPrimaryPageChanged](https://source.chromium.org/chromium/chromium/src/+/main:content/public/browser/web_ui_controller.h;l=54?q=WebUIPrimaryPageChanged&ss=chromium)), and have the JavaScript bind the interface on page load.
 
-We also recommend using Mojo to communicate between parent and child frames whenever possible. See [this CL](https://crrev.com/c/3222406) for example. 
+We also recommend using Mojo to communicate between parent and child frames whenever possible. See [this CL](https://crrev.com/c/3222406) for example.
 
 You should only use `postMessage()` when transferring objects unsupported by Mojo. For example, Media App uses `postMessage()` to pass a read-only [`FileSystemHandle`](https://developer.mozilla.org/en-US/docs/Web/API/File_System_Access_API) file handle to `chrome-untrusted://media-app` from its parent `chrome://media-app`.
 

docs/webui_explainer.md

@@ -232,7 +232,7 @@ whether a certain subclass of `WebUIController` should be created for a given
 URL.
 
 A `WebUIConfig` holds information about the host and scheme (`chrome://` or
-`chrome-untrusted://`) that the controller serves.
+[`chrome-untrusted://`](chrome_untrusted.md)) that the controller serves.
 
 A `WebUIConfig` may contain logic to check if the WebUI is enabled for a given
 `BrowserContext` and url (e.g., if relevant feature flags are enabled/disabled,