sensorium-trace 0.18.2__py3-none-any.whl

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.
Files changed (135) hide show
  1. sensorium/__init__.py +0 -0
  2. sensorium/__main__.py +4 -0
  3. sensorium/_c/rt/sensorium_c_rt.c +1446 -0
  4. sensorium/_typescript/package-lock.json +68 -0
  5. sensorium/_typescript/package.json +39 -0
  6. sensorium/_typescript/src/bindings.mjs +792 -0
  7. sensorium/_typescript/src/cap.mjs +227 -0
  8. sensorium/_typescript/src/capabilities.mjs +40 -0
  9. sensorium/_typescript/src/dbg.mjs +348 -0
  10. sensorium/_typescript/src/escape.mjs +351 -0
  11. sensorium/_typescript/src/focus.mjs +135 -0
  12. sensorium/_typescript/src/hook.mjs +127 -0
  13. sensorium/_typescript/src/index.mjs +1 -0
  14. sensorium/_typescript/src/naming.mjs +63 -0
  15. sensorium/_typescript/src/positions.mjs +37 -0
  16. sensorium/_typescript/src/probe.mjs +246 -0
  17. sensorium/_typescript/src/qualname.mjs +236 -0
  18. sensorium/_typescript/src/redact.mjs +711 -0
  19. sensorium/_typescript/src/register.mjs +15 -0
  20. sensorium/_typescript/src/resolve.mjs +260 -0
  21. sensorium/_typescript/src/rt.mjs +798 -0
  22. sensorium/_typescript/src/setup.mjs +11 -0
  23. sensorium/_typescript/src/tally.mjs +164 -0
  24. sensorium/_typescript/src/tasks.mjs +175 -0
  25. sensorium/_typescript/src/transform.mjs +800 -0
  26. sensorium/_typescript/src/vite.mjs +99 -0
  27. sensorium/c/__init__.py +8 -0
  28. sensorium/c/cc.py +612 -0
  29. sensorium/c/cli.py +60 -0
  30. sensorium/c/convert.py +669 -0
  31. sensorium/c/decode.py +300 -0
  32. sensorium/c/driver.py +365 -0
  33. sensorium/c/dwarf.py +706 -0
  34. sensorium/c/format.py +271 -0
  35. sensorium/c/pkg.py +187 -0
  36. sensorium/c/plan.py +277 -0
  37. sensorium/cli.py +140 -0
  38. sensorium/driver.py +47 -0
  39. sensorium/exit.py +33 -0
  40. sensorium/invocations.py +83 -0
  41. sensorium/limits.py +253 -0
  42. sensorium/mcp/__init__.py +0 -0
  43. sensorium/mcp/audit.py +162 -0
  44. sensorium/mcp/child.py +240 -0
  45. sensorium/mcp/cmd.py +101 -0
  46. sensorium/mcp/jsonrpc.py +172 -0
  47. sensorium/mcp/result.py +187 -0
  48. sensorium/mcp/schema.py +390 -0
  49. sensorium/mcp/server.py +493 -0
  50. sensorium/mcp/tools.py +299 -0
  51. sensorium/paths.py +80 -0
  52. sensorium/query/__init__.py +0 -0
  53. sensorium/query/caps.py +150 -0
  54. sensorium/query/dbg_dialects.py +64 -0
  55. sensorium/query/diff_cmd.py +748 -0
  56. sensorium/query/diff_notes.py +117 -0
  57. sensorium/query/exceptions_c.py +263 -0
  58. sensorium/query/exceptions_cmd.py +788 -0
  59. sensorium/query/exceptions_group.py +571 -0
  60. sensorium/query/exceptions_invocation.py +487 -0
  61. sensorium/query/exceptions_rust.py +683 -0
  62. sensorium/query/exceptions_typescript.py +688 -0
  63. sensorium/query/expr.py +606 -0
  64. sensorium/query/failures_cmd.py +306 -0
  65. sensorium/query/flow_cmd.py +778 -0
  66. sensorium/query/flow_report.py +128 -0
  67. sensorium/query/flow_values.py +195 -0
  68. sensorium/query/fmt.py +280 -0
  69. sensorium/query/frame_cmd.py +237 -0
  70. sensorium/query/grep_cmd.py +156 -0
  71. sensorium/query/help.py +18 -0
  72. sensorium/query/info_cmd.py +527 -0
  73. sensorium/query/info_rust.py +214 -0
  74. sensorium/query/info_typescript.py +261 -0
  75. sensorium/query/js_inspect.py +394 -0
  76. sensorium/query/moves.py +254 -0
  77. sensorium/query/redact_cmd.py +304 -0
  78. sensorium/query/refocus_cmd.py +661 -0
  79. sensorium/query/refocus_env.py +493 -0
  80. sensorium/query/refocus_facts.py +269 -0
  81. sensorium/query/refocus_licence.py +187 -0
  82. sensorium/query/refocus_report.py +327 -0
  83. sensorium/query/refocus_rust.py +537 -0
  84. sensorium/query/refocus_threads.py +197 -0
  85. sensorium/query/refocus_typescript.py +756 -0
  86. sensorium/query/refocus_world.py +666 -0
  87. sensorium/query/runs_cmd.py +213 -0
  88. sensorium/query/rust_debug.py +176 -0
  89. sensorium/query/sites.py +171 -0
  90. sensorium/query/tree_cmd.py +511 -0
  91. sensorium/query/tree_threads.py +168 -0
  92. sensorium/query/vocab.py +723 -0
  93. sensorium/query/watch_cmd.py +657 -0
  94. sensorium/record/__init__.py +0 -0
  95. sensorium/record/boot.py +797 -0
  96. sensorium/record/boot_io.py +141 -0
  97. sensorium/record/budget.py +135 -0
  98. sensorium/record/capture.py +433 -0
  99. sensorium/record/children.py +755 -0
  100. sensorium/record/children_merge.py +179 -0
  101. sensorium/record/elide.py +55 -0
  102. sensorium/record/fingerprint.py +26 -0
  103. sensorium/record/thread_starts.py +261 -0
  104. sensorium/record/tracer.py +798 -0
  105. sensorium/record/tracer_exc.py +199 -0
  106. sensorium/record/tracer_frames.py +618 -0
  107. sensorium/redact.py +304 -0
  108. sensorium/redact_content.py +156 -0
  109. sensorium/redact_key.py +317 -0
  110. sensorium/redact_store.py +502 -0
  111. sensorium/redact_values.py +433 -0
  112. sensorium/store/__init__.py +0 -0
  113. sensorium/store/db.py +284 -0
  114. sensorium/store/gc.py +360 -0
  115. sensorium/store/payloads.py +69 -0
  116. sensorium/store/reader.py +438 -0
  117. sensorium/store/writer.py +283 -0
  118. sensorium/ts/__init__.py +10 -0
  119. sensorium/ts/build.py +783 -0
  120. sensorium/ts/cli.py +130 -0
  121. sensorium/ts/driver.py +472 -0
  122. sensorium/ts/focus.py +146 -0
  123. sensorium/ts/harness.py +314 -0
  124. sensorium/ts/ingest.py +380 -0
  125. sensorium/ts/invocation.py +252 -0
  126. sensorium/ts/pkg.py +167 -0
  127. sensorium/ts/redaction.py +64 -0
  128. sensorium/ts/spool.py +168 -0
  129. sensorium/ts/truncation.py +81 -0
  130. sensorium/ts/wrapper.py +255 -0
  131. sensorium_trace-0.18.2.dist-info/METADATA +245 -0
  132. sensorium_trace-0.18.2.dist-info/RECORD +135 -0
  133. sensorium_trace-0.18.2.dist-info/WHEEL +4 -0
  134. sensorium_trace-0.18.2.dist-info/entry_points.txt +3 -0
  135. sensorium_trace-0.18.2.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,711 @@
1
+ // Rule v1: which NAMES hold a secret, the knobs that amend that judgement,
2
+ // and the key the digests are taken under.
3
+ //
4
+ // This recorder stored the whole process environment in plaintext until this
5
+ // slice, at 0644, so a trace of any suite launched from a developer's shell
6
+ // held whatever that shell was carrying. Rule v1 replaces such a value with
7
+ // `<redacted>` at the WRITER, before anything reaches disk, and keeps an
8
+ // HMAC-SHA256 of the plaintext beside it so a reader can still say "this
9
+ // changed" without being told what it changed to.
10
+ //
11
+ // WHAT THIS IS NOT
12
+ // ----------------
13
+ // **Not a secret scanner.** The rule fires on a name's SEGMENTS, so a secret
14
+ // in a variable called `x`, or one this set has never heard of, is stored as
15
+ // typed. Matching is segment-exact, never substring: substring `KEY` would
16
+ // fire on `MONKEY_PATCH` and substring `PASS` on `BYPASS_CACHE`.
17
+ // `SENSORIUM_REDACT_NAMES` is the remedy for a name this misses and
18
+ // `SENSORIUM_REDACT_ALLOW` for one it wrongly fires on, and both are recorded
19
+ // so a reader sees what the recording was made under.
20
+ //
21
+ // THE FIXTURE
22
+ // -----------
23
+ // `docs/trace-format/redaction-v1.json` holds every `split` and `fires` case,
24
+ // and the Python recorder's suite, `sensorium-rt`'s and `test/redact.test.mjs`
25
+ // read the SAME file. A case belongs there, not in a test module: three
26
+ // implementations of one rule agree only on what all three are asked.
27
+ //
28
+ // THE KEY
29
+ // -------
30
+ // This runtime only ever PARSES `SENSORIUM_REDACT_KEY`, which the driver hands
31
+ // it. It never creates a key, never writes one and never reads a key file:
32
+ // creating one means a directory, a temporary, a link and a race, and this
33
+ // module runs inside somebody else's test suite. An absent, short, long or
34
+ // non-hex value is simply unkeyed -- the names are still redacted, and the
35
+ // BOOT says `keyed: false` so nobody mistakes a missing digest for a value
36
+ // that did not change.
37
+ //
38
+ // This module imports `node:crypto` and nothing else of ours at RUNTIME:
39
+ // `rt.mjs` calls `bootEnv` once at boot and `redactCaptures`/`redactReturn`
40
+ // at every capture, and `dbg.mjs` calls `content` and `current` for the one
41
+ // text that has no name — a thrown message. The `Captured` type is read back
42
+ // from `dbg.mjs` through JSDoc, which is a type reference and not an import,
43
+ // so the two modules do not form a cycle.
44
+ import crypto from 'node:crypto';
45
+
46
+ /**
47
+ * The rule's identity, stamped in every BOOT it touches. A later rule is v2;
48
+ * v1 is never amended, because a trace that says `v1` has to mean one thing
49
+ * forever.
50
+ */
51
+ export const RULE = 'v1';
52
+
53
+ /** What a whole-redacted value reads as. */
54
+ export const REDACTED = '<redacted>';
55
+
56
+ /**
57
+ * The hex key the driver hands a recorded process. DELETED from every recorded
58
+ * environment rather than redacted: a digest of the key under the key is a
59
+ * pointless row, and `keyed: true` already implies it was there.
60
+ */
61
+ export const KEY_VAR = 'SENSORIUM_REDACT_KEY';
62
+
63
+ const OFF_VAR = 'SENSORIUM_NO_REDACT';
64
+ const NAMES_VAR = 'SENSORIUM_REDACT_NAMES';
65
+ const ALLOW_VAR = 'SENSORIUM_REDACT_ALLOW';
66
+
67
+ /**
68
+ * A segment here fires the rule. Every one of them has a firing case in the
69
+ * fixture. The four compounds (`APIKEY`, `ACCESSKEY`, `SECRETKEY`,
70
+ * `AUTHTOKEN`) exist because a name written as one word — `apikey` — splits
71
+ * into one segment that none of `API`, `KEY` matches.
72
+ */
73
+ const SEGMENTS = [
74
+ 'KEY', 'APIKEY', 'TOKEN', 'SECRET', 'SECRETS', 'PASSWORD', 'PASSWD',
75
+ 'PASSPHRASE', 'PASS', 'AUTH', 'AUTHORIZATION', 'CREDENTIAL', 'CREDENTIALS',
76
+ 'CREDS', 'PRIVATE', 'COOKIE', 'COOKIES', 'SIGNATURE', 'BEARER', 'JWT', 'DSN',
77
+ 'ACCESSKEY', 'SECRETKEY', 'AUTHTOKEN', 'PWD',
78
+ ];
79
+
80
+ /**
81
+ * The segments that fire only as part of a LONGER name (ruling B28, for
82
+ * `KEY`). `PWD`: `MYSQL_PWD` and `DB_PWD` are passwords, and `PWD` and
83
+ * `OLDPWD` are the shell's working directory, on every machine that has ever
84
+ * run a shell. `KEY`: a bare `key` is a cache key, a dict key, a lookup key
85
+ * on almost every function that iterates a mapping, and redacting it by
86
+ * default would blind `watch` on the commonest local in the language, while
87
+ * every compound spelling (`api_key`, `apiKey`, `secret_key`, `build_key`,
88
+ * `KEY_FILE`) still fires and `SENSORIUM_REDACT_NAMES=key` restores it per
89
+ * run.
90
+ */
91
+ const SOLO_EXEMPT = ['PWD', 'KEY'];
92
+
93
+ /**
94
+ * Whole NORMALISED names that fire whatever their segments say. Segment-exact
95
+ * matching cannot see inside a compound word: `PGPASSWORD` splits into the
96
+ * single segment `PGPASSWORD`, which is neither `PG` nor `PASSWORD`. Short by
97
+ * design: a name earns a place only when a census or a report shows it
98
+ * matters, never on imagination.
99
+ */
100
+ const EXACT = ['PGPASSWORD'];
101
+
102
+ /** How many bytes a key is, and how many hex characters that is on the wire. */
103
+ const KEY_BYTES = 32;
104
+
105
+ /**
106
+ * The two camelCase boundaries, in this order: an uppercase RUN followed by
107
+ * Upper+lower (`HTTPToken` -> `HTTP Token`), then lower-or-digit followed by
108
+ * upper (`apiKey` -> `api Key`). Global, because the rule is SPECIFIED as
109
+ * Python's `re.sub`, which rewrites every occurrence and not just the first.
110
+ */
111
+ const CAMEL_RUN = /([A-Z]+)([A-Z][a-z])/g;
112
+ const CAMEL_STEP = /([a-z0-9])([A-Z])/g;
113
+ const SEPARATOR = /[^A-Za-z0-9]+/;
114
+
115
+ /**
116
+ * `name`'s uppercased segments: `apiKey` -> `[API, KEY]`, `SSH_AUTH_SOCK` ->
117
+ * `[SSH, AUTH, SOCK]`, `XAUTHORITY` -> `[XAUTHORITY]`. Empty segments are
118
+ * dropped, so `__init__` is `[INIT]` and `''` is `[]`.
119
+ * @param {string} name
120
+ * @returns {string[]}
121
+ */
122
+ export function split(name) {
123
+ const spaced = name.replace(CAMEL_RUN, '$1 $2').replace(CAMEL_STEP, '$1 $2');
124
+ return spaced.split(SEPARATOR).filter((part) => part !== '')
125
+ .map((part) => part.toUpperCase());
126
+ }
127
+
128
+ /**
129
+ * The comparison form the two knobs use: the segments, joined. So `myco_dsn`,
130
+ * `MYCO_DSN` and `mycoDsn` are one name to a user's list.
131
+ * @param {string} name
132
+ * @returns {string}
133
+ */
134
+ export function normalise(name) {
135
+ return split(name).join('');
136
+ }
137
+
138
+ /** @typedef {{off: boolean, names: string[], allow: string[]}} Knobs */
139
+
140
+ /**
141
+ * The three environment variables, as read once at boot.
142
+ *
143
+ * `names` and `allow` are held NORMALISED and SORTED, so a comparison against
144
+ * a variable's own normalised form is exact and case-blind at once, and the
145
+ * BOOT records one list for one set of knobs whatever order they were written
146
+ * in.
147
+ * @param {Record<string, string|undefined>} env
148
+ * @returns {Knobs}
149
+ */
150
+ export function knobsFromEnv(env) {
151
+ const off = env[OFF_VAR];
152
+ return {
153
+ // Reads like `SENSORIUM_NO_INVOCATION_LOG`: any non-empty value other than
154
+ // `"0"` turns the rule off, and `=0`, empty and unset all leave it on.
155
+ off: off !== undefined && off !== '' && off !== '0',
156
+ names: listed(env[NAMES_VAR]),
157
+ allow: listed(env[ALLOW_VAR]),
158
+ };
159
+ }
160
+
161
+ /**
162
+ * A comma list, trimmed, empties dropped, each entry normalised, sorted and
163
+ * deduplicated. An entry that normalises to nothing (`','`, `'-'`) is dropped
164
+ * too — an empty string in the list would match a nameless value.
165
+ * @param {string|undefined} raw
166
+ * @returns {string[]}
167
+ */
168
+ function listed(raw) {
169
+ const names = (raw ?? '').split(',')
170
+ .map((part) => normalise(part.trim()))
171
+ .filter((name) => name !== '');
172
+ return [...new Set(names)].sort();
173
+ }
174
+
175
+ /**
176
+ * Whether the name rule fires on `name`.
177
+ *
178
+ * Allow first, and it WINS over `names` — a user's statement about their own
179
+ * variable outranks their own list. Then `EXACT`, then the segments.
180
+ * `knobs.off` is not read here: turning the whole rule off is `redactEnv`'s
181
+ * business, one level up, so that this function stays the answer to "is this a
182
+ * secret-shaped name".
183
+ *
184
+ * A LINEAR scan, not a binary search over the sorted lists (R24). `Knobs` is a
185
+ * plain object any hand can build, and one built with an unsorted list would
186
+ * make a binary search miss — silently, and the price of a miss here is a
187
+ * plaintext secret on disk. The lists are two or three entries long.
188
+ * @param {string} name
189
+ * @param {Knobs} knobs
190
+ * @returns {boolean}
191
+ */
192
+ export function fires(name, knobs) {
193
+ const segments = split(name);
194
+ const normalised = segments.join('');
195
+ if (knobs.allow.includes(normalised)) return false;
196
+ if (knobs.names.includes(normalised)) return true;
197
+ if (EXACT.includes(normalised)) return true;
198
+ const multi = segments.length > 1;
199
+ return segments.some((s) => SEGMENTS.includes(s) && (multi || !SOLO_EXEMPT.includes(s)));
200
+ }
201
+
202
+ /**
203
+ * The store's redaction key: 32 bytes, or none of them.
204
+ *
205
+ * Never throws, on any path. `material === null` is the whole of the unkeyed
206
+ * state — `keyed`, `keyId` and `digest` all read from it.
207
+ */
208
+ export class Key {
209
+ /**
210
+ * Exactly 64 hex characters and nothing else: `Buffer.from(s, 'hex')` stops
211
+ * silently at the first character that is not one and returns the short
212
+ * buffer, so a key that arrived down a wire between two implementations is
213
+ * checked for the shape it was promised in. Anything else is unkeyed rather
214
+ * than an error — a recorder that refused to record over a malformed knob
215
+ * would cost the whole run.
216
+ * @param {string|undefined} text
217
+ * @returns {Key}
218
+ */
219
+ static fromHex(text) {
220
+ if (typeof text !== 'string' || text.length !== 2 * KEY_BYTES
221
+ || !/^[0-9a-fA-F]+$/.test(text)) {
222
+ return new Key(null);
223
+ }
224
+ return new Key(Buffer.from(text, 'hex'));
225
+ }
226
+
227
+ /** @param {Buffer|null} material */
228
+ constructor(material) {
229
+ /** @type {Buffer|null} */
230
+ this.material = material;
231
+ }
232
+
233
+ /** @returns {boolean} */
234
+ get keyed() {
235
+ return this.material !== null;
236
+ }
237
+
238
+ /**
239
+ * `SHA-256(key)`, first 8 hex: whether two traces' digests are comparable at
240
+ * all.
241
+ * @returns {string|null}
242
+ */
243
+ get keyId() {
244
+ if (this.material === null) return null;
245
+ return crypto.createHash('sha256').update(this.material).digest('hex').slice(0, 8);
246
+ }
247
+
248
+ /**
249
+ * `HMAC-SHA256(key, text)`, first 16 hex — an equality identity, not a
250
+ * commitment — or null when there is no key.
251
+ *
252
+ * The UTF-8 bytes of the value as this runtime holds it. A JavaScript string
253
+ * CAN hold a lone surrogate, and node's UTF-8 encoder writes U+FFFD for one;
254
+ * so does the Python recorder's `encode('utf-8', 'replace')` fallback, so
255
+ * the two languages that can hold one agree on its digest. Nothing to do
256
+ * here but say so (R14).
257
+ * @param {string} text
258
+ * @returns {string|null}
259
+ */
260
+ digest(text) {
261
+ if (this.material === null) return null;
262
+ return crypto.createHmac('sha256', this.material).update(text)
263
+ .digest('hex').slice(0, 16);
264
+ }
265
+ }
266
+
267
+ /**
268
+ * (the environment to STORE, the name -> digest table for the BOOT).
269
+ *
270
+ * A new object either way — the caller's is never touched — minus `KEY_VAR`.
271
+ * With the rule off that deletion is the only thing that happens, and the
272
+ * BOOT's `mode: "off"` says so, so a reader knows the plaintext was recorded
273
+ * on purpose.
274
+ *
275
+ * The table's keys are SORTED (R13) so that one environment gives one table,
276
+ * byte for byte, whichever language wrote it — Rust's caller sorts and
277
+ * Python's `redact.env` sorts too. The stored environment keeps the order it
278
+ * arrived in; only the table is ordered.
279
+ * @param {Record<string, string|undefined>} env
280
+ * @param {Key} key
281
+ * @param {Knobs} knobs
282
+ * @returns {{env: Record<string, string|undefined>,
283
+ * table: Record<string, string|null>}}
284
+ */
285
+ export function redactEnv(env, key, knobs) {
286
+ /** @type {Record<string, string|undefined>} */
287
+ const stored = {};
288
+ for (const [name, value] of Object.entries(env)) {
289
+ if (name !== KEY_VAR) stored[name] = value;
290
+ }
291
+ /** @type {Record<string, string|null>} */
292
+ const table = {};
293
+ if (knobs.off) return { env: stored, table };
294
+ for (const name of Object.keys(stored).sort()) {
295
+ if (!fires(name, knobs)) continue;
296
+ table[name] = key.digest(stored[name] ?? '');
297
+ stored[name] = REDACTED;
298
+ }
299
+ return { env: stored, table };
300
+ }
301
+
302
+ /**
303
+ * The BOOT's `redaction` object, in the format's key order.
304
+ *
305
+ * Off is TWO keys and no more: a record that named a key or a knob list while
306
+ * claiming to have applied nothing would invite a reader to believe the
307
+ * plaintext beside it had been considered. The converter adds `env` and `by`
308
+ * to this object later; the runtime writes what the runtime knows.
309
+ *
310
+ * `key_id` and not `keyId`, alone among this module's names: the converter
311
+ * passes this object into the trace's `redaction` meta unchanged, and that is
312
+ * the format's spelling in all three languages.
313
+ * @param {Key} key
314
+ * @param {Knobs} knobs
315
+ * @returns {Record<string, unknown>}
316
+ */
317
+ export function redactionMeta(key, knobs) {
318
+ if (knobs.off) return { rule: RULE, mode: 'off' };
319
+ return {
320
+ rule: RULE,
321
+ mode: 'on',
322
+ keyed: key.keyed,
323
+ key_id: key.keyId,
324
+ names: [...knobs.names],
325
+ allow: [...knobs.allow],
326
+ };
327
+ }
328
+
329
+ /**
330
+ * The Rust recorder's recipe: sorted `k=v` lines, sha256, first 16 hex.
331
+ * Comparable within one language, and the ledger says so.
332
+ *
333
+ * Here, beside `redactEnv`, because the hash is taken over what that function
334
+ * RETURNS — the environment the trace will hold, not the one the process was
335
+ * started with. `src/sensorium/ts/invocation.py::env_hash` is the same recipe
336
+ * on the Python side, for the driver's own record and for the converter
337
+ * applying the rule to a BOOT written before it existed.
338
+ * @param {Record<string, string|undefined>} env
339
+ * @returns {string}
340
+ */
341
+ export function envHash(env) {
342
+ const lines = Object.keys(env).sort().map((k) => `${k}=${env[k]}`).join('\n');
343
+ return crypto.createHash('sha256').update(lines).digest('hex').slice(0, 16);
344
+ }
345
+
346
+ /**
347
+ * Everything the BOOT record says about the environment it was started with:
348
+ * what to store, its hash, the digest table and the rule it was all done
349
+ * under.
350
+ *
351
+ * One call, because the four are one decision and `rt.mjs` spreading four
352
+ * separate ones could get them out of step — the hash in particular is over
353
+ * the REDACTED environment, and a hash of `process.env` beside a redacted
354
+ * `env` would report a world change whose evidence the trace does not hold.
355
+ * @param {Record<string, string|undefined>} processEnv
356
+ * @returns {{env: Record<string, string|undefined>, envHash: string,
357
+ * envRedaction: Record<string, string|null>,
358
+ * redaction: Record<string, unknown>}}
359
+ */
360
+ export function bootEnv(processEnv) {
361
+ const knobs = knobsFromEnv(processEnv);
362
+ const key = Key.fromHex(processEnv[KEY_VAR]);
363
+ const { env, table } = redactEnv(processEnv, key, knobs);
364
+ return {
365
+ env,
366
+ envHash: envHash(env),
367
+ envRedaction: table,
368
+ redaction: redactionMeta(key, knobs),
369
+ };
370
+ }
371
+
372
+ // ---------------------------------------------------------------------------
373
+ // The content rule (§2.2)
374
+ // ---------------------------------------------------------------------------
375
+ //
376
+ // `redactEnv` above is the NAME half of rule v1: it decides whether a whole
377
+ // value is worth redacting at all. `content` below is the CONTENT half: a
378
+ // fixed list of patterns over a value's TEXT, whatever it was called. §2.3:
379
+ // a name hit redacts the WHOLE value; a content hit replaces the matched
380
+ // SPAN and keeps everything around it (`postgres://u:<redacted>@h/db`) — a
381
+ // repr or a log line is not a value with an identity, it is text that
382
+ // happened to contain one.
383
+ //
384
+ // NOT A SECRET SCANNER: the list is a floor, nineteen shapes each with a
385
+ // minimum length so a short benign string cannot fire. A secret that
386
+ // matches none of them is stored as typed.
387
+ //
388
+ // THE FIXTURE: `docs/trace-format/redaction-v1.json`'s `content` list holds
389
+ // every case, and `src/sensorium/redact_content.py`'s suite and
390
+ // `cargo-sensorium`'s `redact_content.rs` read the SAME file. The three
391
+ // implementations are the same nineteen patterns, textually, save for the
392
+ // one place the three engines cannot agree on a spelling: end-of-text in
393
+ // the PEM row's truncated form (`\Z` in Python, `\z` in Rust, plain `$`
394
+ // here under the `s` flag) and inline case/dotall flags — Python and Rust
395
+ // accept `(?i)`/`(?s)` inside the pattern text; JavaScript's `RegExp` does
396
+ // not, so the `i`/`s` flags stand in for them on the two patterns that need
397
+ // them. Three spellings, one pattern.
398
+
399
+ /**
400
+ * Escapes a literal string for use inside a `RegExp` source — the handful
401
+ * of characters that are regex metacharacters get a backslash. No engine
402
+ * ships `RegExp.escape` yet; this is the whole of what {@link TRIGGER}
403
+ * needs it for.
404
+ * @param {string} s
405
+ * @returns {string}
406
+ */
407
+ function escapeLiteral(s) {
408
+ return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
409
+ }
410
+
411
+ /**
412
+ * §2.2's table, verbatim, in the order the table gives it — table order
413
+ * matters exactly once, for `sk-ant` before `sk`: both match an Anthropic
414
+ * key, the whole match is replaced either way so the two rows' output never
415
+ * differs, and the order is only for which row NAME a test or a report
416
+ * attributes the hit to.
417
+ *
418
+ * `group` is which capture a match replaces (`0` is the whole match). The
419
+ * three patterns whose group is not `0` carry the `d` (`hasIndices`) flag,
420
+ * which is how {@link applyOne} recovers a group's own start and end
421
+ * offsets — `String.prototype.replace`'s replacer callback is handed a
422
+ * group's captured VALUE but never its position, so there is no way to
423
+ * "replace only the group" through `replace` alone.
424
+ * @type {{name: string, regex: RegExp, group: number}[]}
425
+ */
426
+ export const PATTERNS = [
427
+ { name: 'url-userinfo', regex: /:\/\/[^/\s:@]{1,64}:([^@\s/]{1,256})@/gd, group: 1 },
428
+ // The PEM body, through the matching END line or to end of text when
429
+ // truncated. `s` is inline DOTALL: the body spans real newlines.
430
+ {
431
+ name: 'pem',
432
+ regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----(.*?)(?:-----END [A-Z ]*PRIVATE KEY-----|$)/gsd,
433
+ group: 1,
434
+ },
435
+ { name: 'authorization-header', regex: /\b(Bearer|Basic)\s+([A-Za-z0-9._~+/=-]{16,})/gid, group: 2 },
436
+ { name: 'jwt', regex: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, group: 0 },
437
+ { name: 'sk-ant', regex: /\bsk-ant-[A-Za-z0-9_-]{20,}/g, group: 0 },
438
+ { name: 'sk', regex: /\bsk-[A-Za-z0-9_-]{20,}/g, group: 0 },
439
+ { name: 'stripe', regex: /\b(sk|rk)_(live|test)_[A-Za-z0-9]{16,}/g, group: 0 },
440
+ { name: 'github', regex: /\bgh[pousr]_[A-Za-z0-9]{20,}/g, group: 0 },
441
+ { name: 'github-pat', regex: /\bgithub_pat_[A-Za-z0-9_]{20,}/g, group: 0 },
442
+ { name: 'gitlab', regex: /\bglpat-[A-Za-z0-9_-]{20,}/g, group: 0 },
443
+ { name: 'slack', regex: /\bxox[abprs]-[A-Za-z0-9-]{10,}/g, group: 0 },
444
+ { name: 'aws', regex: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/g, group: 0 },
445
+ { name: 'google', regex: /\bAIza[0-9A-Za-z_-]{35}\b/g, group: 0 },
446
+ { name: 'huggingface', regex: /\bhf_[A-Za-z0-9]{20,}/g, group: 0 },
447
+ { name: 'npm', regex: /\bnpm_[A-Za-z0-9]{20,}/g, group: 0 },
448
+ { name: 'pypi', regex: /\bpypi-[A-Za-z0-9_-]{20,}/g, group: 0 },
449
+ { name: 'digitalocean', regex: /\bdop_v1_[a-f0-9]{20,}/g, group: 0 },
450
+ { name: 'shopify', regex: /\bshpat_[a-f0-9]{20,}/g, group: 0 },
451
+ { name: 'sendgrid', regex: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g, group: 0 },
452
+ ];
453
+
454
+ /**
455
+ * B18's pre-check (§12's mitigation, built in rather than waited for): the
456
+ * literal prefix every CASE-SENSITIVE pattern above starts with, as one
457
+ * alternation. A string that matches neither this nor {@link TRIGGER_CI}
458
+ * cannot match any of the nineteen patterns either, so {@link content} skips
459
+ * the whole table rather than running twenty regexes over every string a
460
+ * recording ever touches.
461
+ */
462
+ export const TRIGGER = new RegExp([
463
+ '://', '-----BEGIN', 'eyJ', 'sk-', 'sk_', 'rk_', 'gh', 'github_pat_',
464
+ 'glpat-', 'xox', 'AKIA', 'ASIA', 'AIza', 'hf_', 'npm_', 'pypi-',
465
+ 'dop_v1_', 'shpat_', 'SG.',
466
+ ].map(escapeLiteral).join('|'));
467
+
468
+ /**
469
+ * The same pre-check for the one pattern above that is itself case-blind.
470
+ *
471
+ * `authorization-header` accepts every case spelling of each word, and a
472
+ * literal alternation of `Bearer|Basic|bearer|basic` stood in front of it
473
+ * covering two of each: `Authorization: BEARER <token>` matched no literal,
474
+ * skipped the table, and reached the spool in plaintext. A pre-check
475
+ * NARROWER than the pattern it guards is a leak and not an optimisation
476
+ * (ruling R21). Its own `RegExp` with the `i` flag, which is this engine's
477
+ * only spelling of a scoped case fold, and the shape the Python and Rust
478
+ * twins take too so the three agree in behaviour rather than in syntax.
479
+ */
480
+ export const TRIGGER_CI = /Bearer|Basic/i;
481
+
482
+ /**
483
+ * Whether any §2.2 pattern could match `text` at all: the union of the two
484
+ * pre-checks, and the one thing {@link content} consults.
485
+ *
486
+ * The union is what a test may pin. Either half alone is a pre-check for
487
+ * part of the table, and pinning one of them proves nothing about the shapes
488
+ * the other stands in front of.
489
+ * @param {string} text
490
+ * @returns {boolean}
491
+ */
492
+ export function triggers(text) {
493
+ return TRIGGER.test(text) || TRIGGER_CI.test(text);
494
+ }
495
+
496
+ /**
497
+ * One pattern's substitution over `text`: the whole match for group `0`
498
+ * (a plain string replacement — `REDACTED` holds no `$` and needs no
499
+ * replacer), or the match with only its group's span swapped for
500
+ * `REDACTED` — never the whole match when a narrower group was asked for
501
+ * (§2.3's span operation: everything around the secret is kept).
502
+ * @param {string} text
503
+ * @param {{regex: RegExp, group: number}} pattern
504
+ * @returns {string}
505
+ */
506
+ function applyOne(text, { regex, group }) {
507
+ regex.lastIndex = 0;
508
+ if (group === 0) return text.replace(regex, REDACTED);
509
+
510
+ let out = '';
511
+ let lastEnd = 0;
512
+ let m = regex.exec(text);
513
+ while (m !== null) {
514
+ // `d` (`hasIndices`) is on every pattern whose group is not 0, so the
515
+ // match HAS them; the cast is what says so to a checker that reads
516
+ // `indices` as optional on every `RegExp` match.
517
+ const [groupStart, groupEnd] = /** @type {[number, number]} */ (m.indices?.[group]);
518
+ out += text.slice(lastEnd, groupStart) + REDACTED;
519
+ lastEnd = groupEnd;
520
+ // A pattern that could match empty would loop forever at the same
521
+ // position; none of the three do, but a broken pattern must not hang.
522
+ if (m[0].length === 0) regex.lastIndex += 1;
523
+ m = regex.exec(text);
524
+ }
525
+ return out + text.slice(lastEnd);
526
+ }
527
+
528
+ /**
529
+ * `text` with every matched span replaced by `REDACTED`, and whether the
530
+ * text CHANGED — never whether some pattern merely matched.
531
+ *
532
+ * That distinction is the whole of the contract: `url-userinfo` matches
533
+ * `postgres://u:<redacted>@h/db` (its group already reads as the marker),
534
+ * and replacing it with itself is not a hit. Comparing the WHOLE result to
535
+ * the input, once, at the end, is what makes that true without a special
536
+ * case for it — the converters that count `values` from this flag rely on
537
+ * it (Task 6/7).
538
+ *
539
+ * Applied left to right, pattern by pattern in table order, over the
540
+ * CURRENT text — so a later pattern sees an earlier pattern's markers,
541
+ * never the original secret twice.
542
+ * @param {string} text
543
+ * @returns {{text: string, hit: boolean}}
544
+ */
545
+ export function content(text) {
546
+ if (!text || !triggers(text)) return { text, hit: false };
547
+ let out = text;
548
+ for (const pattern of PATTERNS) out = applyOne(out, pattern);
549
+ return { text: out, hit: out !== text };
550
+ }
551
+
552
+ // ---------------------------------------------------------------------------
553
+ // The value rules (§2.3, at the capture)
554
+ // ---------------------------------------------------------------------------
555
+ //
556
+ // `redactEnv` applies the two halves above to the ENVIRONMENT, once, at boot.
557
+ // These apply them to every value a recording captures, at the writer: a
558
+ // CALL's arguments, a statement's deltas and a RETURN's value. From 0.6.0
559
+ // this runtime does it ITSELF rather than leaving it to the converter, so a
560
+ // secret is never on the disk to be retrofitted — which is the only place
561
+ // the promise can actually be kept (§5.1).
562
+ //
563
+ // A capture meets ONE of the two halves, never both, and which one is the
564
+ // name's to decide: a value the name rule takes has no text left to scan, and
565
+ // one it leaves is offered to the content rule here. That ORDER is the whole
566
+ // reason both live in this function rather than in `dbg.mjs` where the text
567
+ // is made — a digest taken after a span had been replaced would be an HMAC of
568
+ // the marker, which is a CONSTANT, and two different secrets would then carry
569
+ // one identity and read as the same value. `redact_values.named` (Python) and
570
+ // the Rust runtime's tag-4 delta take the same order for the same reason:
571
+ // three implementations of one rule, digesting one text.
572
+
573
+ /** @typedef {import('./dbg.mjs').Captured} Captured */
574
+
575
+ /** @type {{key: Key, knobs: Knobs}|null} */
576
+ let state = null;
577
+
578
+ /**
579
+ * The key and the knobs this PROCESS records under, read once.
580
+ *
581
+ * Lazily, and never re-read (B22): a recording is made under one set of
582
+ * rules, and a program that edits `process.env` half way through its own test
583
+ * run must not be able to change what the rest of the recording was made
584
+ * under — or to turn the rule off after the first secret has been withheld.
585
+ * `bootEnv` above keeps its own reads: it is called once, at boot, before
586
+ * anything else, and its answer goes into the BOOT record for a reader.
587
+ * @returns {{key: Key, knobs: Knobs}}
588
+ */
589
+ export function current() {
590
+ if (state === null) {
591
+ state = { key: Key.fromHex(process.env[KEY_VAR]), knobs: knobsFromEnv(process.env) };
592
+ }
593
+ return state;
594
+ }
595
+
596
+ /**
597
+ * The name a returned value was asked for by (B7): `Store.getApiKey` ->
598
+ * `getApiKey`, `fetch.<anonymous>` -> `<anonymous>`.
599
+ *
600
+ * `<anonymous>` and the other bracketed spellings come through unchanged and
601
+ * fire on nothing — their segments are words in no set — which is the
602
+ * answer, not a special case.
603
+ * @param {string} qualname
604
+ * @returns {string}
605
+ */
606
+ export function lastSegment(qualname) {
607
+ const tail = qualname.slice(qualname.lastIndexOf('.') + 1);
608
+ return tail === '' ? qualname : tail;
609
+ }
610
+
611
+ /**
612
+ * `map` with every capture whose NAME fires taken whole.
613
+ *
614
+ * The arguments of a focused CALL and the deltas of a LINE, which are the two
615
+ * places this runtime holds a value under a name the program chose. A name
616
+ * that does not fire is left with the capture it arrived with — the same
617
+ * object, not a copy of it.
618
+ * @param {Record<string, Captured>} map
619
+ * @returns {Record<string, Captured>}
620
+ */
621
+ export function redactCaptures(map) {
622
+ const { key, knobs } = current();
623
+ if (knobs.off) return map;
624
+ /** @type {Record<string, Captured>} */
625
+ const out = {};
626
+ for (const [name, captured] of Object.entries(map)) {
627
+ out[name] = fires(name, knobs) ? taken(captured, key) : scanned(captured);
628
+ }
629
+ return out;
630
+ }
631
+
632
+ /**
633
+ * A RETURN's capture, taken whole when the CALLEE's own name fires (B7).
634
+ *
635
+ * The value a function hands back has no name of its own, so the rule reads
636
+ * the one it was asked for by: `getApiKey()`'s answer is an API key whatever
637
+ * the caller stores it in.
638
+ * @param {string} qualname the callee's, as the FILE record declared it
639
+ * @param {Captured} captured
640
+ * @returns {Captured}
641
+ */
642
+ export function redactReturn(qualname, captured) {
643
+ const { key, knobs } = current();
644
+ if (knobs.off) return captured;
645
+ return fires(lastSegment(qualname), knobs)
646
+ ? taken(captured, key) : scanned(captured);
647
+ }
648
+
649
+ /**
650
+ * The texts that withhold NOTHING, so the name rule leaves them alone (ruling
651
+ * R19). A function that returned nothing is a fact about the program, and a
652
+ * name is not a reason to hide that it returned: the marker would cost a
653
+ * reader that fact, hide no secret, and publish a digest of a constant. The
654
+ * same exemption Python gives its `none` kind and Rust its `()` (R17),
655
+ * written over the TEXT because `dbg` has no type of its own. Two spellings
656
+ * and nothing near them: `NaN` is a value the program had, and a text that
657
+ * merely contains one of these is taken like any other.
658
+ */
659
+ const WITHHOLDS_NOTHING = new Set(['undefined', 'null']);
660
+
661
+ /**
662
+ * B4: the whole value, gone, and an HMAC of it in its place.
663
+ *
664
+ * `oid` and `type` STAY — the address and the constructor are facts about
665
+ * the program, not about the value, and `flow --object` follows them. `trunc`
666
+ * is written FALSE rather than dropped: nothing was clipped, because the
667
+ * whole of it was taken, and a reader that met the key missing would have to
668
+ * guess whether the formatter had been cut short.
669
+ *
670
+ * Two captures are left exactly as they are, for one reason: there is nothing
671
+ * to take. An `unread` never held a text, and a `dbg` whose text is one of
672
+ * {@link WITHHOLDS_NOTHING} holds one that says the program produced no value
673
+ * — and a reader told `<redacted>` there would have lost a fact and been
674
+ * shown no secret.
675
+ * @param {Captured} captured
676
+ * @param {Key} key
677
+ * @returns {Captured}
678
+ */
679
+ function taken(captured, key) {
680
+ if (captured.k !== 'dbg' || WITHHOLDS_NOTHING.has(captured.v)) return captured;
681
+ return {
682
+ ...captured,
683
+ v: REDACTED,
684
+ trunc: false,
685
+ redacted: { by: 'name', digest: key.digest(captured.v) },
686
+ };
687
+ }
688
+
689
+ /**
690
+ * The CONTENT half over one capture's own text: every matched span replaced,
691
+ * and a `redacted` object saying so — with no digest, because a partial
692
+ * cannot honestly commit to the whole.
693
+ *
694
+ * Over the CAPPED text, which is what the trace would otherwise have held: a
695
+ * secret the 200-byte cap already cut in half is not there to match, and a
696
+ * rule run over the whole rendering would mark a capture for a span the
697
+ * record does not carry. `trunc` STAYS: the text was clipped, and a span
698
+ * inside it was replaced.
699
+ *
700
+ * The mark is written on a CHANGE, never on a match — `<redacted>` inside a
701
+ * URL's userinfo matches the pattern that put it there, and replacing it with
702
+ * itself is not a hit. `content` above is where that distinction lives.
703
+ * @param {Captured} captured
704
+ * @returns {Captured}
705
+ */
706
+ function scanned(captured) {
707
+ if (captured.k !== 'dbg') return captured;
708
+ const { text, hit } = content(captured.v);
709
+ if (!hit) return captured;
710
+ return { ...captured, v: text, redacted: { by: 'content', digest: null } };
711
+ }