@noego/trust 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -54,7 +54,7 @@ export default [
54
54
  }
55
55
  ```
56
56
 
57
- - `extend`: a preset (`default`) or a relative path. Chains are followed.
57
+ - `extend`: a preset (`js`, `node`, `web`, `default`) or a relative path. Chains are followed.
58
58
  - `trust` / `distrust`: origins. An entry covers the origin itself, its subpaths (`node:fs` covers
59
59
  `node:fs/promises`), and its members (`js:JSON` covers `js:JSON.parse`). Lookup walks from this file toward the
60
60
  root preset; the first level whose `distrust` matches makes it untrusted, so `distrust` removes inherited trust.
@@ -68,6 +68,37 @@ A call is also trusted when its declared return type is `Result` / `Promise<Resu
68
68
  unless its origin is explicitly distrusted. `Result.err`, `Result.try` and `Result.tryAsync` are recognised
69
69
  by declaration, not by name.
70
70
 
71
+ ### Presets
72
+
73
+ | Preset | Extends | Trusts |
74
+ |---|---|---|
75
+ | `js` | | Pure JavaScript built-ins that cannot fail on typed input (`js:Array`, `js:Map`, `js:Math`, …), the same in every runtime. |
76
+ | `node` | `js` | Node built-in APIs, audited member by member against the Node v24 source (v26 recorded). |
77
+ | `web` | `js` | Nothing beyond `js` yet: browser globals have not been audited. |
78
+ | `default` | `node` | Alias of `node`. |
79
+
80
+ The `node` list trusts a call only if arguments that satisfy its TypeScript types cannot make it throw or fail
81
+ asynchronously (rejected promise, error-first callback, an `'error'` event caused by the call). Doing I/O or
82
+ calling native code is fine on its own; a reachable failure path is not. An exception from a callback or
83
+ listener you pass counts as a failure. Proxy traps, getters, implicit coercion and TypeScript-unsound inputs do
84
+ not, and neither do engine resource limits. Whole-module or whole-class entries appear only where every member
85
+ was trusted, with explicit `distrust` entries for any member that can fail under a trusted class. The evidence
86
+ for every entry is in `research/node-api/`.
87
+
88
+ A project with several runtimes gives each area its own trust config:
89
+
90
+ ```js
91
+ // eslint.config.js
92
+ export default [
93
+ ...typedConfig({ files: ['server/**/*.ts'], configFile: 'trust.server.json' }), // { "extend": "node" }
94
+ ...typedConfig({ files: ['web/**/*.ts'], configFile: 'trust.web.json' }), // { "extend": "web" }
95
+ ...typedConfig({ files: ['shared/**/*.ts'], configFile: 'trust.shared.json' }), // { "extend": "js" }
96
+ ];
97
+ ```
98
+
99
+ Origins depend on the project's TypeScript libs: with the DOM lib loaded (the default when `lib` is not set),
100
+ web globals such as `URL`, `TextEncoder` and `URLSearchParams` resolve to `js:` origins, not `node:`.
101
+
71
102
  ### Origins
72
103
 
73
104
  | Kind | Origin | Example |