doc: clarify policy expectations

RafaelGSS · UlisesGascon · commit f82347266b06 · 2023-09-10T18:09:32.000Z
PR-URL: #48947 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
diff --git a/doc/api/permissions.md b/doc/api/permissions.md
@@ -33,11 +33,18 @@ If you find a potential security vulnerability, please refer to our
 
 Node.js contains experimental support for creating policies on loading code.
 
-Policies are a security feature intended to allow guarantees
-about what code Node.js is able to load. The use of policies assumes
-safe practices for the policy files such as ensuring that policy
-files cannot be overwritten by the Node.js application by using
-file permissions.
+Policies are a security feature intended to ensure the integrity
+of the loaded code.
+
+While it does not function as a provenance mechanism to trace the origin of
+code, it serves as a robust defense against the execution of malicious code.
+Unlike runtime-based models that may restrict capabilities once the code is
+loaded, Node.js policies focus on preventing malicious code from ever being
+fully loaded into the application in the first place.
+
+The use of policies assumes safe practices for the policy
+files such as ensuring that policy files cannot be overwritten by the Node.js
+application by using file permissions.
 
 A best practice would be to ensure that the policy manifest is read-only for
 the running Node.js application and that the file cannot be changed
@@ -202,12 +209,6 @@ the manifest and then immediately used without searching.
 Any specifier string for which resolution is attempted and that is not listed in
 the dependencies results in an error according to the policy.
 
-Redirection does not prevent access to APIs through means such as direct access
-to `require.cache` or through `module.constructor` which allow access to
-loading modules. Policy redirection only affects specifiers to `require()` and
-`import`. Other means, such as to prevent undesired access to APIs through
-variables, are necessary to lock down that path of loading modules.
-
 A boolean value of `true` for the dependencies map can be specified to allow a
 module to load any specifier without redirection. This can be useful for local
 development and may have some valid usage in production, but should be used
@@ -224,6 +225,9 @@ can be used to ensure some kinds of dynamic access are explicitly prevented.
 Unknown values for the resolved module location cause failures but are
 not guaranteed to be forward compatible.
 
+All the guarantees for policy redirection are specified in the
+[Guarantees](#guarantees) section.
+
 ##### Example: Patched dependency
 
 Redirected dependencies can provide attenuated or modified functionality as fits
@@ -446,6 +450,18 @@ not adopt the origin of the `blob:` URL.
 Additionally, import maps only work on `import` so it may be desirable to add a
 `"import"` condition to all dependency mappings.
 
+#### Guarantees
+
+* The policies guarantee the file integrity when a module is loaded using
+  `require()`, `import()` or `new Module()`.
+* Redirection does not prevent access to APIs through means such as direct
+  access to `require.cache` which allow access to loaded modules.
+  Policy redirection only affects specifiers to `require()` and
+  `import`.
+* The approval of the module integrity in policies threat model implies
+  they are allowed to muck with and even circumvent security features once
+  loaded so environmental/runtime hardening is expected.
+
 ## Process-based permissions
 
 ### Permission Model
