Skip to content

Commit 1589f0e

Browse files
Trottrichardlau
authored andcommitted
doc: make general copy-edit changes to policy.md
PR-URL: #34943 Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Evan Lucas <[email protected]>
1 parent fcb211f commit 1589f0e

File tree

1 file changed

+16
-16
lines changed

1 file changed

+16
-16
lines changed

doc/api/policy.md

+16-16
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ safe practices for the policy files such as ensuring that policy
1515
files cannot be overwritten by the Node.js application by using
1616
file permissions.
1717

18-
A best practice would be to ensure that the policy manifest is read only for
19-
the running Node.js application, and that the file cannot be changed
18+
A best practice would be to ensure that the policy manifest is read-only for
19+
the running Node.js application and that the file cannot be changed
2020
by the running Node.js application in any way. A typical setup would be to
2121
create the policy file as a different user id than the one running Node.js
2222
and granting read permissions to the user id running Node.js.
@@ -99,8 +99,8 @@ An example policy file that would allow loading a file `checked.js`:
9999
Each resource listed in the policy manifest can be of one the following
100100
formats to determine its location:
101101

102-
1. A [relative url string][] to a resource from the manifest such as `./resource.js`, `../resource.js`, or `/resource.js`.
103-
2. A complete url string to a resource such as `file:///resource.js`.
102+
1. A [relative-URL string][] to a resource from the manifest such as `./resource.js`, `../resource.js`, or `/resource.js`.
103+
2. A complete URL string to a resource such as `file:///resource.js`.
104104

105105
When loading resources the entire URL must match including search parameters
106106
and hash fragment. `./a.js?b` will not be used when attempting to load
@@ -151,12 +151,12 @@ be used to find the module.
151151
If the value of the redirection is a string, it will be resolved relative to
152152
the manifest and then immediately be used without searching.
153153

154-
Any specifier string that is attempted to resolved and not listed in the
154+
Any specifier string that is attempted to resolve and not listed in the
155155
dependencies will result in an error according to the policy.
156156

157157
Redirection will not prevent access to APIs through means such as direct access
158158
to `require.cache` and/or through `module.constructor` which allow access to
159-
loading modules. Policy redirection only affect specifiers to `require()` and
159+
loading modules. Policy redirection only affects specifiers to `require()` and
160160
`import`. Other means such as to prevent undesired access to APIs through
161161
variables are necessary to lock down that path of loading modules.
162162

@@ -165,15 +165,15 @@ module to load any specifier without redirection. This can be useful for local
165165
development and may have some valid usage in production, but should be used
166166
only with care after auditing a module to ensure its behavior is valid.
167167

168-
Similar to `"exports"` in `package.json` dependencies can also be specified to
168+
Similar to `"exports"` in `package.json`, dependencies can also be specified to
169169
be objects containing conditions which branch how dependencies are loaded. In
170-
the above example `"http"` will be allowed when the `"import"` condition is
170+
the preceding example, `"http"` will be allowed when the `"import"` condition is
171171
part of loading it.
172172

173-
A value of `null` for the resolved value will cause the resolution to fail.
174-
This can be used to ensure some kinds dynamic access are explicitly prevented.
173+
A value of `null` for the resolved value will cause the resolution to fail. This
174+
can be used to ensure some kinds of dynamic access are explicitly prevented.
175175

176-
Unknown values for the resolved module location will cause failure, but are
176+
Unknown values for the resolved module location will cause failure but are
177177
not guaranteed to be forwards compatible.
178178

179179
#### Example: Patched dependency
@@ -200,10 +200,10 @@ module.exports = function fn(...args) {
200200

201201
Use the `"scopes"` field of a manifest to set configuration for many resources
202202
at once. The `"scopes"` field works by matching resources by their segments.
203-
If a scope or resource includes `"cascade": true` unknown specifiers will
203+
If a scope or resource includes `"cascade": true`, unknown specifiers will
204204
be searched for in their containing scope. The containing scope for cascading
205205
is found by recursively reducing the resource URL by removing segments for
206-
[special schemes][], keeping trailing `"/"` suffixes and removing the query and
206+
[special schemes][], keeping trailing `"/"` suffixes, and removing the query and
207207
hash fragment. This leads to the eventual reduction of the URL to its origin.
208208
If the URL is non-special the scope will be located by the URL's origin. If no
209209
scope is found for the origin or in the case of opaque origins, a protocol
@@ -216,7 +216,7 @@ origin of `blob:https://nodejs.org`; URLs starting with
216216
thus `https:` for its protocol scope. For opaque origin `blob:` URLs they will
217217
have `blob:` for their protocol scope since they do not adopt origins.
218218

219-
#### Integrity Using Scopes
219+
#### Integrity using scopes
220220

221221
Setting an integrity to `true` on a scope will set the integrity for any
222222
resource not found in the manifest to `true`.
@@ -241,7 +241,7 @@ The following example allows loading any file:
241241
}
242242
```
243243

244-
#### Dependency Redirection Using Scopes
244+
#### Dependency redirection using scopes
245245

246246
The following example, would allow access to `fs` for all resources within
247247
`./app/`:
@@ -284,5 +284,5 @@ The following example, would allow access to `fs` for all `data:` resources:
284284
}
285285
```
286286

287-
[relative url string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
287+
[relative-URL string]: https://url.spec.whatwg.org/#relative-url-with-fragment-string
288288
[special schemes]: https://url.spec.whatwg.org/#special-scheme

0 commit comments

Comments
 (0)