@noego/trust 0.1.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 ADDED
@@ -0,0 +1,91 @@
1
+ # @noego/trust
2
+
3
+ Make the failure path explicit. Everything is untrusted by default: every call into untrusted code,
4
+ and every `throw`, must be handled locally by a `try` whose `catch` returns `Result.err(...)` (or by
5
+ `Result.try` / `Result.tryAsync`). The goal is prevention. When something on the trust list causes a
6
+ bug, remove it from the list, and the lint flags every call to it.
7
+
8
+ ## Runtime: `@noego/trust`
9
+
10
+ Zero imports, safe in any bundle.
11
+
12
+ ```ts
13
+ import { Result } from '@noego/trust';
14
+
15
+ function parse(text: string): Result<Config, ParseError> {
16
+ try {
17
+ return Result.ok(readConfig(text));
18
+ } catch (cause) {
19
+ return Result.err({ kind: 'parse_failed', message: String(cause) });
20
+ }
21
+ }
22
+
23
+ const loaded = Result.try(() => JSON.parse(text), () => ({ kind: 'bad_json' }) as const);
24
+ const fetched = await Result.tryAsync(() => client.get(url), (cause) => toHttpError(cause));
25
+ ```
26
+
27
+ ## Lint: `@noego/trust/eslint`
28
+
29
+ Rules (typed linting required for `untrusted-call-must-return-result`):
30
+
31
+ - `trust/untrusted-call-must-return-result`: calls/`new` into untrusted origins must be guarded.
32
+ Messages: `unguarded`, `notAwaited`, `callsIgnored`, `rethrow`, `notResultErr`, `rawCatchValue`, `notAllPaths`.
33
+ - `trust/throw-must-return-result`: every `throw` must be guarded.
34
+
35
+ ```js
36
+ // eslint.config.js
37
+ import { typedConfig } from '@noego/trust/eslint';
38
+
39
+ export default [
40
+ // ...parser setup with parserOptions.projectService for these files...
41
+ ...typedConfig({ files: ['server/**/*.ts'], ignores: ['**/*.test.ts'], configFile: 'trust.config.json', severity: 'warn' }),
42
+ ];
43
+ ```
44
+
45
+ ### trust.config.json
46
+
47
+ ```json
48
+ {
49
+ "extend": "default",
50
+ "trust": ["zod", { "origin": "@noego/ioc", "reason": "DI container, no I/O" }],
51
+ "distrust": ["js:Array.from"],
52
+ "passthrough": ["server/repositories/**"],
53
+ "ignore": ["**/*.test.ts", "server/testing/**"]
54
+ }
55
+ ```
56
+
57
+ - `extend`: a preset (`default`) or a relative path. Chains are followed.
58
+ - `trust` / `distrust`: origins. An entry covers the origin itself, its subpaths (`node:fs` covers
59
+ `node:fs/promises`), and its members (`js:JSON` covers `js:JSON.parse`). Lookup walks from this file toward the
60
+ root preset; the first level whose `distrust` matches makes it untrusted, so `distrust` removes inherited trust.
61
+ - `passthrough`: files not checked inside; calls *into* them from checked code are untrusted (`local:<path>#<member>`).
62
+ - `ignore`: files not checked inside and trusted from outside; calls into them from checked code are reported
63
+ (`callsIgnored`) because ignoring alone silently trusts.
64
+ - Globs use ESLint flat-config semantics (minimatch, `dot: true`, `!negation`, last match wins), relative to the
65
+ config file's directory, matched on realpaths. A glob matching no file is a load error.
66
+
67
+ A call is also trusted when its declared return type is `Result` / `Promise<Result>` from `@noego/trust`,
68
+ unless its origin is explicitly distrusted. `Result.err`, `Result.try` and `Result.tryAsync` are recognised
69
+ by declaration, not by name.
70
+
71
+ ### Origins
72
+
73
+ | Kind | Origin | Example |
74
+ |---|---|---|
75
+ | JavaScript built-in | `js:<member>` | `js:JSON.parse`, `js:Array.map`, `js:URL` |
76
+ | Node built-in module | `node:<module>.<member>` | `node:fs.existsSync`, `node:fs/promises.readFile`, `node:child_process.spawn` |
77
+ | Node global | `node:global.<member>` | `node:global.setTimeout`, `node:global.Buffer.from`, `node:global.process.cwd` |
78
+ | npm package | `<package>.<member>` | `zod.object`, `better-sqlite3.Database.prepare`, `@scope/pkg.fn` |
79
+ | passthrough file | `local:<path>#<member>` | `local:server/repositories/x.ts#XRepository.find` |
80
+
81
+ `node:` keeps Node's own modules apart from npm packages with the same name (`path`, `events`, `util`, …).
82
+ Package entries never cover a different package that shares a prefix (`lodash` does not cover `lodash.merge`).
83
+ The old `builtin:` and `node.` prefixes are rejected at load time with the replacement name.
84
+
85
+ ## CLI: `trust`
86
+
87
+ ```sh
88
+ trust explain server/services/foo.ts:42[:7] # origin + verdict for each call on that line
89
+ trust baseline server --update # write trust-baseline.json (file + rule + origin -> count)
90
+ trust baseline server # exit 1 when any count grows
91
+ ```