From 311a0038f367092aba263c4735a6983de5af05df Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Fri, 12 Aug 2022 13:09:32 -0300 Subject: [PATCH 1/3] doc: move policy docs to the permissions scope --- doc/api/{policy.md => permissions.md} | 39 ++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 6 deletions(-) rename doc/api/{policy.md => permissions.md} (92%) diff --git a/doc/api/policy.md b/doc/api/permissions.md similarity index 92% rename from doc/api/policy.md rename to doc/api/permissions.md index 233d6c94640790..fe6385c7e1dd70 100644 --- a/doc/api/policy.md +++ b/doc/api/permissions.md @@ -1,4 +1,28 @@ -# Policies +# Permissions + +This section exposes security features available to be adopted in a +Node.js application. The available scopes are: + +* [Resource-based permissions](#resource-based-permissions) +* [Process-based permissions](#process-based-permissions) + +Resource-based permissions stands for the managment of modules using +policies. A policy can guarantee which module/resource is available +during the application execution. + +Process-based permissions stands for the management of resources such +as _File System_ or _Network_. A permission can be configured to restrict +access to specific resources, for instance, one can restrict access to +all the _File System_ write. + +Both permissions can be used together to provide a safer environment. + +**Note**: if you find a potential security vulnerability on Node.js, +refer to our [Security Policy][]. + +## Resource-based permissions + +## Policies @@ -22,7 +46,7 @@ by the running Node.js application in any way. A typical setup would be to create the policy file as a different user id than the one running Node.js and granting read permissions to the user id running Node.js. -## Enabling +### Enabling @@ -48,9 +72,9 @@ even if the file is changed on disk. node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" app.js ``` -## Features +### Features -### Error behavior +#### Error behavior When a policy check fails, Node.js by default will throw an error. It is possible to change the error behavior to one of a few possibilities @@ -74,7 +98,7 @@ available to change the behavior: } ``` -### Integrity checks +#### Integrity checks Policy files must use integrity checks with Subresource Integrity strings compatible with the browser @@ -116,7 +140,7 @@ body for the resource which can be useful for local development. It is not recommended in production since it would allow unexpected alteration of resources to be considered valid. -### Dependency redirection +#### Dependency redirection An application may need to ship patched versions of modules or to prevent modules from allowing all modules access to all other modules. Redirection @@ -423,6 +447,9 @@ 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. +## Process-based permissions + [import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string [relative-url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string [special schemes]: https://url.spec.whatwg.org/#special-scheme +[Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md From 8261f2c7f69c9e8d86e718137df743324b33e44d Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Fri, 12 Aug 2022 13:30:08 -0300 Subject: [PATCH 2/3] doc: rename policy references --- doc/api/errors.md | 2 +- doc/api/index.md | 2 +- doc/api/permissions.md | 33 ++++++++++++--------------------- doc/api/policy.md | 11 +++++++++++ 4 files changed, 25 insertions(+), 23 deletions(-) create mode 100644 doc/api/policy.md diff --git a/doc/api/errors.md b/doc/api/errors.md index 4c544ef734776e..0608cacce13ec0 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -3577,7 +3577,7 @@ The native call from `process.cpuUsage` could not be processed. [domains]: domain.md [event emitter-based]: events.md#class-eventemitter [file descriptors]: https://en.wikipedia.org/wiki/File_descriptor -[policy]: policy.md +[policy]: permissions.md#policies [self-reference a package using its name]: packages.md#self-referencing-a-package-using-its-name [stream-based]: stream.md [syscall]: https://man7.org/linux/man-pages/man2/syscalls.2.html diff --git a/doc/api/index.md b/doc/api/index.md index c999258769c95b..9c35550f5daf81 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -45,7 +45,7 @@ * [OS](os.md) * [Path](path.md) * [Performance hooks](perf_hooks.md) -* [Policies](policy.md) +* [Permissions](permissions.md) * [Process](process.md) * [Punycode](punycode.md) * [Query strings](querystring.md) diff --git a/doc/api/permissions.md b/doc/api/permissions.md index fe6385c7e1dd70..e2764c0ef957ad 100644 --- a/doc/api/permissions.md +++ b/doc/api/permissions.md @@ -1,26 +1,19 @@ # Permissions -This section exposes security features available to be adopted in a -Node.js application. The available scopes are: +Permissions can be used to control what system resources the +Node.js process has access to or what actions the process can take +with those resources. Permissions can also control what modules can +be accessed by other modules. -* [Resource-based permissions](#resource-based-permissions) -* [Process-based permissions](#process-based-permissions) +* [Module-based permissions](#module-based-permissions) control which files + or URLs are available to other modules during application execution. + This can be used to control what modules can be accessed by third-party + dependencies, for example. -Resource-based permissions stands for the managment of modules using -policies. A policy can guarantee which module/resource is available -during the application execution. +If you find a potential security vulnerability, please refer to our +[Security Policy][]. -Process-based permissions stands for the management of resources such -as _File System_ or _Network_. A permission can be configured to restrict -access to specific resources, for instance, one can restrict access to -all the _File System_ write. - -Both permissions can be used together to provide a safer environment. - -**Note**: if you find a potential security vulnerability on Node.js, -refer to our [Security Policy][]. - -## Resource-based permissions +## Module-based permissions ## Policies @@ -447,9 +440,7 @@ 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. -## Process-based permissions - +[Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md [import maps]: https://url.spec.whatwg.org/#relative-url-with-fragment-string [relative-url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string [special schemes]: https://url.spec.whatwg.org/#special-scheme -[Security Policy]: https://github.com/nodejs/node/blob/main/SECURITY.md diff --git a/doc/api/policy.md b/doc/api/policy.md new file mode 100644 index 00000000000000..cf2ff88b7ffdaf --- /dev/null +++ b/doc/api/policy.md @@ -0,0 +1,11 @@ +# Policies + + + + + +> Stability: 1 - Experimental + +The former Policies documentation is now at [Permissions documentation][] + +[Permissions documentation]: permissions.md#policies From 3e6c93b1765ed165b7b0108b547facfb6493ac64 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 31 Aug 2022 10:41:53 -0300 Subject: [PATCH 3/3] test: bypass renamed fields holding the old link --- doc/api/permissions.md | 24 ++++++++++++------------ test/doctool/test-make-doc.mjs | 6 ++++++ 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/doc/api/permissions.md b/doc/api/permissions.md index e2764c0ef957ad..a4be1a7c399b4e 100644 --- a/doc/api/permissions.md +++ b/doc/api/permissions.md @@ -15,7 +15,7 @@ If you find a potential security vulnerability, please refer to our ## Module-based permissions -## Policies +### Policies @@ -39,7 +39,7 @@ by the running Node.js application in any way. A typical setup would be to create the policy file as a different user id than the one running Node.js and granting read permissions to the user id running Node.js. -### Enabling +#### Enabling @@ -65,9 +65,9 @@ even if the file is changed on disk. node --experimental-policy=policy.json --policy-integrity="sha384-SggXRQHwCG8g+DktYYzxkXRIkTiEYWBHqev0xnpCxYlqMBufKZHAHQM3/boDaI/0" app.js ``` -### Features +#### Features -#### Error behavior +##### Error behavior When a policy check fails, Node.js by default will throw an error. It is possible to change the error behavior to one of a few possibilities @@ -91,7 +91,7 @@ available to change the behavior: } ``` -#### Integrity checks +##### Integrity checks Policy files must use integrity checks with Subresource Integrity strings compatible with the browser @@ -133,7 +133,7 @@ body for the resource which can be useful for local development. It is not recommended in production since it would allow unexpected alteration of resources to be considered valid. -#### Dependency redirection +##### Dependency redirection An application may need to ship patched versions of modules or to prevent modules from allowing all modules access to all other modules. Redirection @@ -218,7 +218,7 @@ 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. -#### Example: Patched dependency +##### Example: Patched dependency Redirected dependencies can provide attenuated or modified functionality as fits the application. For example, log data about timing of function durations by @@ -238,7 +238,7 @@ module.exports = function fn(...args) { }; ``` -### Scopes +#### Scopes Use the `"scopes"` field of a manifest to set configuration for many resources at once. The `"scopes"` field works by matching resources by their segments. @@ -259,7 +259,7 @@ origin of `blob:https://nodejs.org`; URLs starting with thus `https:` for its protocol scope. For opaque origin `blob:` URLs they will have `blob:` for their protocol scope since they do not adopt origins. -#### Example +##### Example ```json { @@ -314,7 +314,7 @@ in the `"scopes"` of the policy. This determines the policy for all resources. It would not be used for `file:///C:/app/bin/main.js` unless `"file:"` is set to cascade. -#### Integrity using scopes +##### Integrity using scopes Setting an integrity to `true` on a scope will set the integrity for any resource not found in the manifest to `true`. @@ -339,7 +339,7 @@ The following example allows loading any file: } ``` -#### Dependency redirection using scopes +##### Dependency redirection using scopes The following example, would allow access to `fs` for all resources within `./app/`: @@ -382,7 +382,7 @@ The following example, would allow access to `fs` for all `data:` resources: } ``` -#### Example: [import maps][] emulation +##### Example: [import maps][] emulation Given an import map: diff --git a/test/doctool/test-make-doc.mjs b/test/doctool/test-make-doc.mjs index 54483c7d68932d..5771f4e1ce777f 100644 --- a/test/doctool/test-make-doc.mjs +++ b/test/doctool/test-make-doc.mjs @@ -45,6 +45,7 @@ const linkedHtmls = [...new Set(links)].map((link) => link.match(re)[1]) const expectedJsons = linkedHtmls .map((name) => name.replace('.html', '.json')); const expectedDocs = linkedHtmls.concat(expectedJsons); +const renamedDocs = ['policy.json', 'policy.html']; // Test that all the relative links in the TOC match to the actual documents. for (const expectedDoc of expectedDocs) { @@ -54,6 +55,11 @@ for (const expectedDoc of expectedDocs) { // Test that all the actual documents match to the relative links in the TOC // and that they are not empty files. for (const actualDoc of actualDocs) { + // When renaming the documentation, the old url is lost + // Unless the old file is still available pointing to the correct location + // 301 redirects are not yet automated. So keeping the old URL is a + // reasonable workaround. + if (renamedDocs.includes(actualDoc)) continue; assert.ok( expectedDocs.includes(actualDoc), `${actualDoc} does not match TOC`);