@mainwave/cli 0.11.0 → 0.13.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 +203 -16
- package/dist/adapters/claude-code.js +3 -3
- package/dist/adapters/claude-desktop.js +35 -1
- package/dist/adapters/codex-cli.js +16 -16
- package/dist/adapters/cursor.js +7 -2
- package/dist/adapters/kiro.js +13 -8
- package/dist/commands.js +219 -0
- package/dist/core/apply.js +47 -8
- package/dist/core/auth-commands.js +2 -1
- package/dist/core/codecs/kiro-hooks-json.js +1 -1
- package/dist/core/codex-trust.js +178 -0
- package/dist/core/doctor.js +144 -12
- package/dist/core/entry-script.js +2 -3
- package/dist/core/format.js +0 -1
- package/dist/core/hook-copies.js +157 -0
- package/dist/core/install-hooks.js +198 -15
- package/dist/core/interview.js +36 -16
- package/dist/core/markers.js +209 -44
- package/dist/core/redaction.js +188 -0
- package/dist/core/skills.js +3 -11
- package/dist/core/status.js +21 -1
- package/dist/core/store.js +254 -4
- package/dist/core/wizard.js +91 -6
- package/dist/main.js +173 -163
- package/hooks/codex-turns.mjs +584 -0
- package/hooks/kiro-otlp.mjs +10 -1
- package/hooks/mainwave-hook.mjs +27 -3
- package/hooks/marker-core.mjs +66 -8
- package/hooks/matchers.json +98 -1
- package/hooks/redaction-data.mjs +209 -0
- package/hooks/redaction-json.mjs +215 -0
- package/hooks/redaction-pattern.mjs +503 -0
- package/hooks/redaction.d.mts +84 -0
- package/hooks/redaction.mjs +701 -0
- package/hooks/vocabulary.mjs +41 -2
- package/package.json +3 -1
- package/skills/mainwave-instrument/SKILL.md +24 -6
- package/skills/mainwave-instrument/reference/frameworks.md +4 -2
- package/skills/mainwave-instrument/reference/troubleshooting.md +4 -0
- package/skills/mainwave-instrument-node/SKILL.md +83 -38
- package/skills/mainwave-instrument-node/reference/api.md +16 -16
- package/skills/mainwave-instrument-node/reference/frameworks.md +42 -27
- package/skills/mainwave-instrument-node/reference/troubleshooting.md +11 -7
|
@@ -0,0 +1,701 @@
|
|
|
1
|
+
// Redaction of hook telemetry before it leaves the machine: the same rules
|
|
2
|
+
// file format, packs and semantics as the Mainwave SDKs' redaction, so one
|
|
3
|
+
// rules file means the same thing in an application and in a coding tool's
|
|
4
|
+
// hooks.
|
|
5
|
+
//
|
|
6
|
+
// The rules object: `packs` (built-in rule packs, off unless listed),
|
|
7
|
+
// `blocked_values` (every match replaced by `[REDACTED:<name>]`, or
|
|
8
|
+
// `[REDACTED]` when the rule has no name), `allowed_values` (a blocked or pack
|
|
9
|
+
// match one of these matches in full is kept), `blocked_key_patterns` (searched
|
|
10
|
+
// in the attribute key; a hit replaces the whole value), `ignored_keys` and
|
|
11
|
+
// `ignored_key_patterns` (never scanned), and `summary` (`info`, the default,
|
|
12
|
+
// stamps `mainwave.redaction.count` on each span that had a replacement;
|
|
13
|
+
// `silent` does not). A rule is a pattern string or `{ name, pattern,
|
|
14
|
+
// case_insensitive }`. Patterns are checked against a fixed grammar and cost
|
|
15
|
+
// limits at load (redaction-pattern.mjs); anything else is a config error
|
|
16
|
+
// naming the rule, pack or key, and a hook never runs on rules it could not
|
|
17
|
+
// load (`loadHookRedaction` reports `error`, and the caller drops the span).
|
|
18
|
+
//
|
|
19
|
+
// What is scanned, per span: its name, its status message, and every string
|
|
20
|
+
// attribute value (and string element of an array value) in its own, its
|
|
21
|
+
// events', its links' and its resource's attributes. Event names, numbers and
|
|
22
|
+
// booleans, and non-string array elements are not. A shape the walk cannot
|
|
23
|
+
// scan (a `kvlistValue`, a `bytesValue`, an array nested in an array, scope
|
|
24
|
+
// attributes) is never passed through: `redactOtlpTraces` throws, so the
|
|
25
|
+
// caller drops the span rather than send what was not checked. A value that is strict JSON
|
|
26
|
+
// is redacted in place (redaction-json.mjs): only its string and number value
|
|
27
|
+
// tokens are scanned, and only a changed token is rewritten. Per attribute:
|
|
28
|
+
// an exempt or ignored key skips everything; then key rules; then value rules,
|
|
29
|
+
// packs first in their fixed order, then `blocked_values`. The span name and
|
|
30
|
+
// status message have no key, so only value rules apply to them.
|
|
31
|
+
|
|
32
|
+
import { readFileSync } from 'node:fs'
|
|
33
|
+
import { homedir } from 'node:os'
|
|
34
|
+
import { isAbsolute, join, resolve } from 'node:path'
|
|
35
|
+
|
|
36
|
+
import { BUILTIN_EXEMPT_KEYS, PACKS } from './redaction-data.mjs'
|
|
37
|
+
import { decodeJsonString, encodeJsonString, tokenizeJson } from './redaction-json.mjs'
|
|
38
|
+
import { PatternError, translatePattern } from './redaction-pattern.mjs'
|
|
39
|
+
|
|
40
|
+
/** A rules object or rules file that cannot be used. The message names the
|
|
41
|
+
* offending rule (its name, else its pattern), pack or top-level key; from
|
|
42
|
+
* `readRedactionFile`, the file too. */
|
|
43
|
+
export class RedactionConfigError extends Error {
|
|
44
|
+
name = 'RedactionConfigError'
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The span attribute that carries the replacement count. */
|
|
48
|
+
export const REDACTION_COUNT_KEY = 'mainwave.redaction.count'
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Present in a `redaction.mjs` that reads the organization's packs from
|
|
52
|
+
* `redaction.org`. `install-hooks`, `status` and `doctor` look for it in the
|
|
53
|
+
* text of a copy already on the machine to tell one from before the packs; it
|
|
54
|
+
* appears nowhere else in this file, so a comment cannot stand in for it.
|
|
55
|
+
*/
|
|
56
|
+
export const ORG_PACKS_SUPPORT = 'mainwave:org-redaction-packs/1'
|
|
57
|
+
|
|
58
|
+
/** The built-in pack names, in the order they run. */
|
|
59
|
+
export const REDACTION_PACKS = Object.freeze(Object.keys(PACKS))
|
|
60
|
+
|
|
61
|
+
const TOP_LEVEL_KEYS = [
|
|
62
|
+
'packs',
|
|
63
|
+
'blocked_values',
|
|
64
|
+
'allowed_values',
|
|
65
|
+
'blocked_key_patterns',
|
|
66
|
+
'ignored_keys',
|
|
67
|
+
'ignored_key_patterns',
|
|
68
|
+
'summary',
|
|
69
|
+
]
|
|
70
|
+
const RULE_KEYS = new Set(['name', 'pattern', 'case_insensitive'])
|
|
71
|
+
|
|
72
|
+
const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
73
|
+
|
|
74
|
+
const ruleError = (list, label, reason) =>
|
|
75
|
+
new RedactionConfigError(`redaction: ${list} rule ${JSON.stringify(label)}: ${reason}`)
|
|
76
|
+
|
|
77
|
+
/** The Luhn checksum of the digits in `text`: from the rightmost digit, double
|
|
78
|
+
* every second digit (subtracting 9 above 9) and sum; divisible by 10 passes. */
|
|
79
|
+
const luhnValid = (text) => {
|
|
80
|
+
let sum = 0
|
|
81
|
+
let double = false
|
|
82
|
+
for (let i = text.length - 1; i >= 0; i--) {
|
|
83
|
+
const c = text.charCodeAt(i)
|
|
84
|
+
if (c < 0x30 || c > 0x39) continue
|
|
85
|
+
let digit = c - 0x30
|
|
86
|
+
if (double) {
|
|
87
|
+
digit *= 2
|
|
88
|
+
if (digit > 9) digit -= 9
|
|
89
|
+
}
|
|
90
|
+
sum += digit
|
|
91
|
+
double = !double
|
|
92
|
+
}
|
|
93
|
+
return sum % 10 === 0
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
// ─── Load: check and compile ─────────────────────────────────────────────
|
|
97
|
+
|
|
98
|
+
/** One compiled rule: its replacement token, a global regex (every match), a
|
|
99
|
+
* plain one (key search), an anchored one (`allowed_values`, whole match) and
|
|
100
|
+
* a pack rule's post-match check. */
|
|
101
|
+
const buildRule = (list, index, { name, pattern, caseInsensitive, validate }) => {
|
|
102
|
+
if (typeof pattern !== 'string' || pattern === '') {
|
|
103
|
+
throw ruleError(list, name ?? `#${index}`, 'pattern must be a non-empty string')
|
|
104
|
+
}
|
|
105
|
+
const label = name ?? pattern
|
|
106
|
+
let source
|
|
107
|
+
try {
|
|
108
|
+
source = translatePattern(pattern, caseInsensitive)
|
|
109
|
+
} catch (error) {
|
|
110
|
+
if (error instanceof PatternError) throw ruleError(list, label, error.message)
|
|
111
|
+
// A pattern nested deeper than the parser's stack.
|
|
112
|
+
throw ruleError(list, label, 'the pattern is too complex to check')
|
|
113
|
+
}
|
|
114
|
+
try {
|
|
115
|
+
return {
|
|
116
|
+
token: name === undefined ? '[REDACTED]' : `[REDACTED:${name}]`,
|
|
117
|
+
global: new RegExp(source, 'gu'),
|
|
118
|
+
search: new RegExp(source, 'u'),
|
|
119
|
+
full: new RegExp(`^(?:${source})(?![^])`, 'u'),
|
|
120
|
+
validate,
|
|
121
|
+
}
|
|
122
|
+
} catch (error) {
|
|
123
|
+
throw ruleError(list, label, `does not compile: ${error?.message ?? String(error)}`)
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** A user rule: a pattern string or `{ name, pattern, case_insensitive }`.
|
|
128
|
+
* `validate` is for pack rules only, so here it is an unknown key. */
|
|
129
|
+
const compileRule = (list, input, index) => {
|
|
130
|
+
if (typeof input === 'string') {
|
|
131
|
+
return buildRule(list, index, { name: undefined, pattern: input, caseInsensitive: false })
|
|
132
|
+
}
|
|
133
|
+
if (!isRecord(input))
|
|
134
|
+
throw ruleError(list, `#${index}`, 'a rule is a pattern string or an object')
|
|
135
|
+
const label =
|
|
136
|
+
typeof input.name === 'string' && input.name !== ''
|
|
137
|
+
? input.name
|
|
138
|
+
: typeof input.pattern === 'string'
|
|
139
|
+
? input.pattern
|
|
140
|
+
: `#${index}`
|
|
141
|
+
for (const key of Object.keys(input)) {
|
|
142
|
+
if (!RULE_KEYS.has(key)) throw ruleError(list, label, `unknown key ${JSON.stringify(key)}`)
|
|
143
|
+
}
|
|
144
|
+
if (input.name !== undefined && (typeof input.name !== 'string' || input.name === '')) {
|
|
145
|
+
throw ruleError(list, label, 'name must be a non-empty string')
|
|
146
|
+
}
|
|
147
|
+
if (input.case_insensitive !== undefined && typeof input.case_insensitive !== 'boolean') {
|
|
148
|
+
throw ruleError(list, label, 'case_insensitive must be a boolean')
|
|
149
|
+
}
|
|
150
|
+
return buildRule(list, index, {
|
|
151
|
+
name: input.name,
|
|
152
|
+
pattern: input.pattern,
|
|
153
|
+
caseInsensitive: input.case_insensitive === true,
|
|
154
|
+
})
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
const compileRules = (rules, list) => {
|
|
158
|
+
const value = rules[list]
|
|
159
|
+
if (value === undefined) return []
|
|
160
|
+
if (!Array.isArray(value)) throw new RedactionConfigError(`redaction: ${list} must be a list`)
|
|
161
|
+
return value.map((entry, index) => compileRule(list, entry, index))
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
const stringList = (rules, key) => {
|
|
165
|
+
const value = rules[key]
|
|
166
|
+
if (value === undefined) return []
|
|
167
|
+
if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry === '')) {
|
|
168
|
+
throw new RedactionConfigError(`redaction: ${key} must be a list of non-empty strings`)
|
|
169
|
+
}
|
|
170
|
+
return value
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** The packs `packs` turns on, in canonical order (the packs file's, whatever
|
|
174
|
+
* order the rules list them in: a card rule must not read the digits inside
|
|
175
|
+
* a token the secrets pack replaces), and their compiled rules. */
|
|
176
|
+
const compilePacks = (rules) => {
|
|
177
|
+
const value = rules.packs
|
|
178
|
+
if (value === undefined) return { names: [], rules: [] }
|
|
179
|
+
if (!Array.isArray(value)) throw new RedactionConfigError('redaction: packs must be a list')
|
|
180
|
+
const listed = new Set()
|
|
181
|
+
for (const entry of value) {
|
|
182
|
+
if (typeof entry !== 'string') {
|
|
183
|
+
throw new RedactionConfigError('redaction: packs must be a list of pack names (strings)')
|
|
184
|
+
}
|
|
185
|
+
if (!Object.hasOwn(PACKS, entry)) {
|
|
186
|
+
throw new RedactionConfigError(
|
|
187
|
+
`redaction: packs: unknown pack ${JSON.stringify(entry)} (known: ${REDACTION_PACKS.join(', ')})`,
|
|
188
|
+
)
|
|
189
|
+
}
|
|
190
|
+
if (listed.has(entry)) {
|
|
191
|
+
throw new RedactionConfigError(
|
|
192
|
+
`redaction: packs: pack ${JSON.stringify(entry)} is listed twice`,
|
|
193
|
+
)
|
|
194
|
+
}
|
|
195
|
+
listed.add(entry)
|
|
196
|
+
}
|
|
197
|
+
const names = REDACTION_PACKS.filter((name) => listed.has(name))
|
|
198
|
+
const compiled = names.flatMap((name) =>
|
|
199
|
+
PACKS[name].map((rule, index) =>
|
|
200
|
+
buildRule(`pack ${name}`, index, {
|
|
201
|
+
name: `${name}.${rule.name}`,
|
|
202
|
+
pattern: rule.pattern,
|
|
203
|
+
caseInsensitive: rule.case_insensitive,
|
|
204
|
+
validate: rule.validate,
|
|
205
|
+
}),
|
|
206
|
+
),
|
|
207
|
+
)
|
|
208
|
+
return { names, rules: compiled }
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
// A redactor's compiled passes, kept off the object callers see: one for a
|
|
212
|
+
// rules object, several for the hooks' layered rules (§ `layered`).
|
|
213
|
+
const internals = new WeakMap()
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Checks and compiles a rules object. Returns a frozen `{ packs, summary }`
|
|
217
|
+
* (the enabled packs in canonical order, and the summary mode) that
|
|
218
|
+
* `redactOtlpTraces` accepts. Throws RedactionConfigError naming the
|
|
219
|
+
* offending rule, pack or top-level key. A rules file cannot carry a masking
|
|
220
|
+
* function, so there is none here.
|
|
221
|
+
*/
|
|
222
|
+
export const compileRedaction = (rules) => {
|
|
223
|
+
if (!isRecord(rules)) throw new RedactionConfigError('redaction: the rules must be an object')
|
|
224
|
+
for (const key of Object.keys(rules)) {
|
|
225
|
+
if (!TOP_LEVEL_KEYS.includes(key)) {
|
|
226
|
+
throw new RedactionConfigError(
|
|
227
|
+
`redaction: unknown key ${JSON.stringify(key)} (expected ${TOP_LEVEL_KEYS.join(', ')})`,
|
|
228
|
+
)
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
// Only an absent key defaults to info: null or any other value is an error.
|
|
232
|
+
const summary = rules.summary === undefined ? 'info' : rules.summary
|
|
233
|
+
if (summary !== 'info' && summary !== 'silent') {
|
|
234
|
+
throw new RedactionConfigError(
|
|
235
|
+
`redaction: summary must be "info" or "silent", got ${JSON.stringify(summary)}`,
|
|
236
|
+
)
|
|
237
|
+
}
|
|
238
|
+
const packs = compilePacks(rules)
|
|
239
|
+
const blocked = compileRules(rules, 'blocked_values')
|
|
240
|
+
const allowed = compileRules(rules, 'allowed_values')
|
|
241
|
+
const keyRules = compileRules(rules, 'blocked_key_patterns')
|
|
242
|
+
const ignoredKeys = stringList(rules, 'ignored_keys')
|
|
243
|
+
const ignoredKeyPatterns = stringList(rules, 'ignored_key_patterns').map((pattern, index) =>
|
|
244
|
+
compileRule('ignored_key_patterns', pattern, index),
|
|
245
|
+
)
|
|
246
|
+
const values = [...packs.rules, ...blocked]
|
|
247
|
+
const redactor = Object.freeze({ packs: Object.freeze(packs.names), summary })
|
|
248
|
+
internals.set(redactor, [
|
|
249
|
+
{
|
|
250
|
+
values,
|
|
251
|
+
allowed,
|
|
252
|
+
keyRules,
|
|
253
|
+
exempt: new Set([...BUILTIN_EXEMPT_KEYS, ...ignoredKeys]),
|
|
254
|
+
ignoredKeyPatterns,
|
|
255
|
+
summary,
|
|
256
|
+
// Only allow or ignore lists change nothing.
|
|
257
|
+
active: values.length > 0 || keyRules.length > 0,
|
|
258
|
+
},
|
|
259
|
+
])
|
|
260
|
+
return redactor
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/** One redactor that runs `redactors`' rules as separate passes, in order:
|
|
264
|
+
* each pass scans what the one before it left, so a later pass's
|
|
265
|
+
* `allowed_values` cannot bring back what an earlier one replaced. Its
|
|
266
|
+
* `packs` are every pass's, in canonical order, and its `summary` the last
|
|
267
|
+
* pass's. A single redactor is returned as it is. */
|
|
268
|
+
const layered = (redactors) => {
|
|
269
|
+
if (redactors.length === 1) return redactors[0]
|
|
270
|
+
const packs = REDACTION_PACKS.filter((name) => redactors.some((r) => r.packs.includes(name)))
|
|
271
|
+
const redactor = Object.freeze({
|
|
272
|
+
packs: Object.freeze(packs),
|
|
273
|
+
summary: redactors.at(-1)?.summary ?? 'info',
|
|
274
|
+
})
|
|
275
|
+
internals.set(
|
|
276
|
+
redactor,
|
|
277
|
+
redactors.flatMap((r) => internals.get(r)),
|
|
278
|
+
)
|
|
279
|
+
return redactor
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
// ─── Run ─────────────────────────────────────────────────────────────────
|
|
283
|
+
|
|
284
|
+
/** `text` with every value-rule match replaced, and the number replaced. A
|
|
285
|
+
* match an allow rule keeps, or a pack match that fails its check, stays and
|
|
286
|
+
* is not counted. */
|
|
287
|
+
const scan = (r, text) => {
|
|
288
|
+
let count = 0
|
|
289
|
+
let out = text
|
|
290
|
+
for (const rule of r.values) {
|
|
291
|
+
out = out.replace(rule.global, (match) => {
|
|
292
|
+
if (match === '') return match
|
|
293
|
+
if (rule.validate === 'luhn' && !luhnValid(match)) return match
|
|
294
|
+
if (r.allowed.some((allow) => allow.full.test(match))) return match
|
|
295
|
+
count++
|
|
296
|
+
return rule.token
|
|
297
|
+
})
|
|
298
|
+
}
|
|
299
|
+
return [out, count]
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
const unscanned = (key, shape) => {
|
|
303
|
+
throw new Error(`redaction cannot scan ${shape} in attribute ${JSON.stringify(key)}`)
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
const isExempt = (r, key) =>
|
|
307
|
+
r.exempt.has(key) || r.ignoredKeyPatterns.some((rule) => rule.search.test(key))
|
|
308
|
+
|
|
309
|
+
const keyToken = (r, key) => r.keyRules.find((rule) => rule.search.test(key))?.token
|
|
310
|
+
|
|
311
|
+
/** One span's (or one resource's) worth of redaction; `count` is what it
|
|
312
|
+
* replaced. */
|
|
313
|
+
const session = (r) => {
|
|
314
|
+
const s = { count: 0 }
|
|
315
|
+
|
|
316
|
+
// A plain string: the value rules alone.
|
|
317
|
+
s.leaf = (text) => {
|
|
318
|
+
if (r.values.length === 0 || text === '') return text
|
|
319
|
+
const [out, count] = scan(r, text)
|
|
320
|
+
s.count += count
|
|
321
|
+
return out
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
// A JSON-valued string, redacted in place: each string and number value
|
|
325
|
+
// token on its own, and only a changed token rewritten as a canonical JSON
|
|
326
|
+
// string. undefined when `text` is not JSON.
|
|
327
|
+
const json = (text) => {
|
|
328
|
+
const tokens = tokenizeJson(text)
|
|
329
|
+
if (tokens === undefined) return undefined
|
|
330
|
+
let out = ''
|
|
331
|
+
let last = 0
|
|
332
|
+
for (const token of tokens) {
|
|
333
|
+
const raw = text.slice(token.start, token.end)
|
|
334
|
+
const scanned = token.kind === 'string' ? decodeJsonString(raw) : raw
|
|
335
|
+
const next = s.leaf(scanned)
|
|
336
|
+
if (next === scanned) continue
|
|
337
|
+
out += text.slice(last, token.start) + encodeJsonString(next)
|
|
338
|
+
last = token.end
|
|
339
|
+
}
|
|
340
|
+
return last === 0 ? text : out + text.slice(last)
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
// One string under a key the caller has found not exempt.
|
|
344
|
+
const string = (key, text) => {
|
|
345
|
+
const token = keyToken(r, key)
|
|
346
|
+
if (token !== undefined) {
|
|
347
|
+
s.count++
|
|
348
|
+
// A value that is JSON stays JSON: the token as a JSON string.
|
|
349
|
+
return tokenizeJson(text) === undefined ? token : encodeJsonString(token)
|
|
350
|
+
}
|
|
351
|
+
// With no value rules nothing in a JSON value can change: skip tokenizing.
|
|
352
|
+
return (r.values.length === 0 ? undefined : json(text)) ?? s.leaf(text)
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
// OTLP/JSON `{ key, value }` entries, in place: a `stringValue`, and each
|
|
356
|
+
// `stringValue` element of an `arrayValue`. Numbers, booleans and non-string
|
|
357
|
+
// elements stay; a shape that could hold text the walk does not reach throws.
|
|
358
|
+
s.keyValues = (list) => {
|
|
359
|
+
if (!Array.isArray(list)) return
|
|
360
|
+
for (const kv of list) {
|
|
361
|
+
if (!isRecord(kv) || typeof kv.key !== 'string' || !isRecord(kv.value)) continue
|
|
362
|
+
if (isExempt(r, kv.key)) continue
|
|
363
|
+
const value = kv.value
|
|
364
|
+
for (const shape of ['kvlistValue', 'bytesValue']) {
|
|
365
|
+
if (Object.hasOwn(value, shape)) unscanned(kv.key, shape)
|
|
366
|
+
}
|
|
367
|
+
if (typeof value.stringValue === 'string') {
|
|
368
|
+
value.stringValue = string(kv.key, value.stringValue)
|
|
369
|
+
} else if (isRecord(value.arrayValue) && Array.isArray(value.arrayValue.values)) {
|
|
370
|
+
for (const element of value.arrayValue.values) {
|
|
371
|
+
if (!isRecord(element)) continue
|
|
372
|
+
for (const shape of ['arrayValue', 'kvlistValue', 'bytesValue']) {
|
|
373
|
+
if (Object.hasOwn(element, shape)) unscanned(kv.key, `${shape} element`)
|
|
374
|
+
}
|
|
375
|
+
if (typeof element.stringValue === 'string') {
|
|
376
|
+
element.stringValue = string(kv.key, element.stringValue)
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
return s
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
const listOf = (value) => (Array.isArray(value) ? value : [])
|
|
386
|
+
|
|
387
|
+
/** The count on a span's own attributes: replaces an existing entry, else
|
|
388
|
+
* appends one. */
|
|
389
|
+
const stamp = (span, count) => {
|
|
390
|
+
const entry = { key: REDACTION_COUNT_KEY, value: { intValue: String(count) } }
|
|
391
|
+
if (!Array.isArray(span.attributes)) span.attributes = []
|
|
392
|
+
const at = span.attributes.findIndex((kv) => kv?.key === REDACTION_COUNT_KEY)
|
|
393
|
+
if (at === -1) span.attributes.push(entry)
|
|
394
|
+
else span.attributes[at] = entry
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
/**
|
|
398
|
+
* A redacted deep copy of an OTLP/JSON `ExportTraceServiceRequest`; the input
|
|
399
|
+
* is never changed. Each resource's attributes are redacted once and their
|
|
400
|
+
* replacements count toward every span under that resource, so a span's
|
|
401
|
+
* count is the total over its name, status message, own, event, link and
|
|
402
|
+
* resource attributes. A layered redactor (§ `layered`) runs its passes in
|
|
403
|
+
* order over every value, and a span's count is the sum over the passes whose
|
|
404
|
+
* `summary` is `info`. A span whose count is above zero carries it as
|
|
405
|
+
* `mainwave.redaction.count` (an int) on its own attributes; the resource
|
|
406
|
+
* never does.
|
|
407
|
+
*/
|
|
408
|
+
export const redactOtlpTraces = (redactor, payload) => {
|
|
409
|
+
const passes = internals.get(redactor)?.filter((r) => r.active)
|
|
410
|
+
if (passes === undefined) throw new TypeError('redactOtlpTraces: not a compiled redactor')
|
|
411
|
+
const out = structuredClone(payload)
|
|
412
|
+
if (passes.length === 0) return out
|
|
413
|
+
for (const resourceSpans of listOf(out?.resourceSpans)) {
|
|
414
|
+
const resource = passes.map((r) => {
|
|
415
|
+
const s = session(r)
|
|
416
|
+
s.keyValues(resourceSpans?.resource?.attributes)
|
|
417
|
+
return s.count
|
|
418
|
+
})
|
|
419
|
+
for (const scopeSpans of listOf(resourceSpans?.scopeSpans)) {
|
|
420
|
+
if (listOf(scopeSpans?.scope?.attributes).length > 0) {
|
|
421
|
+
throw new Error('redaction cannot scan scope attributes')
|
|
422
|
+
}
|
|
423
|
+
for (const span of listOf(scopeSpans?.spans)) {
|
|
424
|
+
if (!isRecord(span)) continue
|
|
425
|
+
let total = 0
|
|
426
|
+
passes.forEach((r, i) => {
|
|
427
|
+
const s = session(r)
|
|
428
|
+
s.count = resource[i]
|
|
429
|
+
if (typeof span.name === 'string') span.name = s.leaf(span.name)
|
|
430
|
+
s.keyValues(span.attributes)
|
|
431
|
+
for (const event of listOf(span.events)) s.keyValues(event?.attributes)
|
|
432
|
+
for (const link of listOf(span.links)) s.keyValues(link?.attributes)
|
|
433
|
+
if (isRecord(span.status) && typeof span.status.message === 'string') {
|
|
434
|
+
span.status.message = s.leaf(span.status.message)
|
|
435
|
+
}
|
|
436
|
+
if (r.summary === 'info') total += s.count
|
|
437
|
+
})
|
|
438
|
+
if (total > 0) stamp(span, total)
|
|
439
|
+
}
|
|
440
|
+
}
|
|
441
|
+
}
|
|
442
|
+
return out
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
// ─── Files ───────────────────────────────────────────────────────────────
|
|
446
|
+
|
|
447
|
+
const reasonOf = (error) =>
|
|
448
|
+
error?.code === 'ENOENT' ? 'no such file' : (error?.message ?? String(error))
|
|
449
|
+
|
|
450
|
+
/** Where a JSON parse failed, from the digits in the engine's message only: the
|
|
451
|
+
* message can quote the file, and a rules file may hold a secret. */
|
|
452
|
+
const jsonPosition = (error) => {
|
|
453
|
+
const message = String(error?.message ?? '')
|
|
454
|
+
// Anchored to the end, where the engine puts the position, so digits in a
|
|
455
|
+
// quoted snippet never match.
|
|
456
|
+
const found = / at position (\d+)(?: \(line (\d+) column (\d+)\))?$/.exec(message)
|
|
457
|
+
if (!found) return ''
|
|
458
|
+
return found[2] ? ` (line ${found[2]}, column ${found[3]})` : ` (at offset ${found[1]})`
|
|
459
|
+
}
|
|
460
|
+
|
|
461
|
+
/** The rules with the `secrets` pack on: appended to a valid `packs` list that
|
|
462
|
+
* lacks it, set when `packs` is absent. Anything else (`packs` of the wrong
|
|
463
|
+
* type, a rules value that is not an object) is left for `compileRedaction`
|
|
464
|
+
* to reject, so the file's own error is the one reported. */
|
|
465
|
+
const withSecretsPack = (rules) => {
|
|
466
|
+
if (!isRecord(rules)) return rules
|
|
467
|
+
if (rules.packs === undefined) return { ...rules, packs: ['secrets'] }
|
|
468
|
+
if (!Array.isArray(rules.packs) || rules.packs.includes('secrets')) return rules
|
|
469
|
+
return { ...rules, packs: [...rules.packs, 'secrets'] }
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
/** Reads, parses and compiles a rules file. Every failure (missing,
|
|
473
|
+
* unreadable, empty, not JSON, invalid rules) throws RedactionConfigError
|
|
474
|
+
* naming the path and the reason. `withSecrets` adds the `secrets` pack when
|
|
475
|
+
* the file does not list it, the way the hooks run a recorded file. */
|
|
476
|
+
export const readRedactionFile = (path, { withSecrets = false } = {}) => {
|
|
477
|
+
const where = `redaction rules file ${JSON.stringify(path)}`
|
|
478
|
+
let text
|
|
479
|
+
try {
|
|
480
|
+
text = readFileSync(path, 'utf8')
|
|
481
|
+
} catch (error) {
|
|
482
|
+
throw new RedactionConfigError(`${where} cannot be read: ${reasonOf(error)}`)
|
|
483
|
+
}
|
|
484
|
+
if (text.trim() === '') throw new RedactionConfigError(`${where} is empty`)
|
|
485
|
+
let rules
|
|
486
|
+
try {
|
|
487
|
+
rules = JSON.parse(text)
|
|
488
|
+
} catch (error) {
|
|
489
|
+
throw new RedactionConfigError(`${where} is not valid JSON${jsonPosition(error)}`)
|
|
490
|
+
}
|
|
491
|
+
try {
|
|
492
|
+
return compileRedaction(withSecrets ? withSecretsPack(rules) : rules)
|
|
493
|
+
} catch (error) {
|
|
494
|
+
throw new RedactionConfigError(`${where}: ${reasonOf(error)}`)
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
// What the hooks run when no rules file is recorded: the `secrets` pack alone,
|
|
499
|
+
// from the packs this module ships. Compiled on first use and kept.
|
|
500
|
+
let defaultRedactor
|
|
501
|
+
const defaultRules = () => {
|
|
502
|
+
defaultRedactor ??= compileRedaction({ packs: ['secrets'] })
|
|
503
|
+
return defaultRedactor
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
/** The CLI's own settings file, where setup records the rules file. */
|
|
507
|
+
const defaultSettingsPath = () => join(homedir(), '.mainwave', 'settings.json')
|
|
508
|
+
|
|
509
|
+
// A settings file that is absent (or under a missing directory) never
|
|
510
|
+
// configured redaction.
|
|
511
|
+
const isMissing = (error) => error?.code === 'ENOENT' || error?.code === 'ENOTDIR'
|
|
512
|
+
|
|
513
|
+
/**
|
|
514
|
+
* The packs an organization's managed settings set, as `install-hooks`
|
|
515
|
+
* records them: `redaction.org`, keyed by Claude config dir (an absolute
|
|
516
|
+
* path), each `{ packs: [<pack name>...] }`. For `configDir`, that dir's
|
|
517
|
+
* packs; with no `configDir` (a hook that cannot tell which Claude config
|
|
518
|
+
* dir it runs for: Cursor's, Kiro's, Codex's) every recorded dir's, merged,
|
|
519
|
+
* so such a hook redacts more, never less. `{ packs }` in canonical order, or
|
|
520
|
+
* `{ error }` for a malformed slot or a pack these hooks do not have (a newer
|
|
521
|
+
* CLI recorded it): the caller drops the span.
|
|
522
|
+
*/
|
|
523
|
+
const orgPacks = (config, settingsPath, configDir) => {
|
|
524
|
+
if (!Object.hasOwn(config, 'org')) return { packs: [] }
|
|
525
|
+
const org = config.org
|
|
526
|
+
if (!isRecord(org)) return { error: `${settingsPath}: redaction.org must be an object` }
|
|
527
|
+
const want = configDir === undefined ? undefined : resolve(configDir)
|
|
528
|
+
const named = new Set()
|
|
529
|
+
for (const [dir, entry] of Object.entries(org)) {
|
|
530
|
+
if (
|
|
531
|
+
!isRecord(entry) ||
|
|
532
|
+
!Array.isArray(entry.packs) ||
|
|
533
|
+
entry.packs.some((name) => typeof name !== 'string')
|
|
534
|
+
) {
|
|
535
|
+
return {
|
|
536
|
+
error: `${settingsPath}: redaction.org[${JSON.stringify(dir)}] must be { "packs": [<pack names>] }`,
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
if (want !== undefined && !(isAbsolute(dir) && resolve(dir) === want)) continue
|
|
540
|
+
for (const name of entry.packs) named.add(name)
|
|
541
|
+
}
|
|
542
|
+
const unknown = [...named].filter((name) => !Object.hasOwn(PACKS, name))
|
|
543
|
+
if (unknown.length > 0) {
|
|
544
|
+
return {
|
|
545
|
+
error:
|
|
546
|
+
`${settingsPath}: your organization's redaction packs name ${unknown.map((n) => JSON.stringify(n)).join(', ')}, ` +
|
|
547
|
+
`which these hooks do not have (known: ${REDACTION_PACKS.join(', ')}); a newer mainwave-cli has them`,
|
|
548
|
+
}
|
|
549
|
+
}
|
|
550
|
+
return { packs: REDACTION_PACKS.filter((name) => named.has(name)) }
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
/**
|
|
554
|
+
* Every recorded config dir's organization packs, `{ "<config dir>": [names] }`,
|
|
555
|
+
* for `status` and `doctor`: the entries that have the slot's shape and name a
|
|
556
|
+
* pack, as written. Empty when the file or the slot can't be read; the loader
|
|
557
|
+
* reports that. Never throws.
|
|
558
|
+
*/
|
|
559
|
+
export const recordedOrgPacks = ({ settingsPath } = {}) => {
|
|
560
|
+
let settings
|
|
561
|
+
try {
|
|
562
|
+
settings = JSON.parse(readFileSync(settingsPath ?? defaultSettingsPath(), 'utf8'))
|
|
563
|
+
} catch {
|
|
564
|
+
return {}
|
|
565
|
+
}
|
|
566
|
+
const org =
|
|
567
|
+
isRecord(settings) && isRecord(settings.redaction) ? settings.redaction.org : undefined
|
|
568
|
+
if (!isRecord(org)) return {}
|
|
569
|
+
const out = {}
|
|
570
|
+
for (const [dir, entry] of Object.entries(org)) {
|
|
571
|
+
if (!isRecord(entry) || !Array.isArray(entry.packs)) continue
|
|
572
|
+
const packs = entry.packs.filter((name) => typeof name === 'string')
|
|
573
|
+
if (packs.length > 0) out[dir] = packs
|
|
574
|
+
}
|
|
575
|
+
return out
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
/**
|
|
579
|
+
* The rules the hooks run, from the CLI's settings file (`~/.mainwave/
|
|
580
|
+
* settings.json` unless `settingsPath` says otherwise), key `redaction:
|
|
581
|
+
* { file?: "<absolute path>", secrets?: false, org?: { "<config dir>":
|
|
582
|
+
* { packs } } }`. `configDir` is the Claude config dir the hook runs for, when
|
|
583
|
+
* it can tell (§ `orgPacks`). Synchronous; never throws.
|
|
584
|
+
*
|
|
585
|
+
* Up to two passes. The first runs the organization's packs and only those
|
|
586
|
+
* (`org`, which `install-hooks` records from the org's managed settings and
|
|
587
|
+
* nothing else writes), and is absent when there are none; it always stamps
|
|
588
|
+
* its count. The second is the developer's own rules, exactly as they run when
|
|
589
|
+
* no organization chose packs: the recorded file's rules plus the `secrets`
|
|
590
|
+
* pack, or `secrets` alone with no file, or nothing when `secrets` is off and
|
|
591
|
+
* no file is recorded. It scans what the first pass left, so nothing in it,
|
|
592
|
+
* `allowed_values` included, brings back a value the first pass replaced.
|
|
593
|
+
* `secrets` is in the first pass only when the organization lists it. One of:
|
|
594
|
+
* - `{ state: 'on', source: 'default', org, secrets, redactor }`: no rules
|
|
595
|
+
* file. With no settings at all that is the `secrets` pack alone; it also
|
|
596
|
+
* covers a settings file with no `redaction` key, and one that is not JSON
|
|
597
|
+
* and never mentions `"redaction"` (a mangled unrelated file must not turn
|
|
598
|
+
* redaction off);
|
|
599
|
+
* - `{ state: 'on', source: 'file', file, org, secrets, redactor }`: the
|
|
600
|
+
* organization's packs, then the recorded rules file's rules;
|
|
601
|
+
* - `{ state: 'off' }`: `redaction.secrets` is `false`, and no rules file
|
|
602
|
+
* and no organization packs are recorded;
|
|
603
|
+
* - `{ state: 'error', file?, org?, reason }`: the settings file exists but
|
|
604
|
+
* cannot be read, or is not JSON and mentions `"redaction"`; the key is
|
|
605
|
+
* there but malformed; the organization's packs cannot be loaded (`org:
|
|
606
|
+
* true`); or the rules file cannot be loaded. The caller drops the span:
|
|
607
|
+
* redaction that was asked for never silently turns off.
|
|
608
|
+
* `org` is the organization's packs this hook runs, in canonical order, and
|
|
609
|
+
* `secrets` whether the default is on.
|
|
610
|
+
* The hooks do not read `MAINWAVE_REDACTION_FILE`, the SDKs' variable: the
|
|
611
|
+
* settings file setup writes is the one source of truth, and a hook's
|
|
612
|
+
* environment is partly the repository's to set.
|
|
613
|
+
*/
|
|
614
|
+
export const loadHookRedaction = ({ settingsPath, configDir } = {}) => {
|
|
615
|
+
let text
|
|
616
|
+
try {
|
|
617
|
+
settingsPath ??= defaultSettingsPath()
|
|
618
|
+
text = readFileSync(settingsPath, 'utf8')
|
|
619
|
+
} catch (error) {
|
|
620
|
+
if (isMissing(error)) return defaultOn()
|
|
621
|
+
return {
|
|
622
|
+
state: 'error',
|
|
623
|
+
reason: `${settingsPath ?? 'settings file'} cannot be read: ${error?.code ?? reasonOf(error)}: ${reasonOf(error)}`,
|
|
624
|
+
}
|
|
625
|
+
}
|
|
626
|
+
let settings
|
|
627
|
+
try {
|
|
628
|
+
settings = JSON.parse(text)
|
|
629
|
+
} catch {
|
|
630
|
+
settings = undefined
|
|
631
|
+
}
|
|
632
|
+
if (!isRecord(settings)) {
|
|
633
|
+
// A file we cannot parse may still hold redaction the developer set up (a
|
|
634
|
+
// hand-edit left a trailing comma), so it fails closed when it mentions the
|
|
635
|
+
// key. One that never did gets the default: a mangled file must neither
|
|
636
|
+
// drop every hook span nor switch the default off.
|
|
637
|
+
if (text.includes('"redaction"')) {
|
|
638
|
+
return {
|
|
639
|
+
state: 'error',
|
|
640
|
+
reason: `${settingsPath} is not valid JSON, so its redaction settings cannot be read`,
|
|
641
|
+
}
|
|
642
|
+
}
|
|
643
|
+
return defaultOn()
|
|
644
|
+
}
|
|
645
|
+
if (!Object.hasOwn(settings, 'redaction')) return defaultOn()
|
|
646
|
+
const config = settings.redaction
|
|
647
|
+
if (!isRecord(config)) {
|
|
648
|
+
return { state: 'error', reason: `${settingsPath}: redaction must be an object` }
|
|
649
|
+
}
|
|
650
|
+
if (Object.hasOwn(config, 'secrets') && typeof config.secrets !== 'boolean') {
|
|
651
|
+
return {
|
|
652
|
+
state: 'error',
|
|
653
|
+
reason: `${settingsPath}: redaction.secrets must be true or false, got ${JSON.stringify(config.secrets)}`,
|
|
654
|
+
}
|
|
655
|
+
}
|
|
656
|
+
const secrets = config.secrets !== false
|
|
657
|
+
const org = orgPacks(config, settingsPath, configDir)
|
|
658
|
+
if (org.error !== undefined) return { state: 'error', org: true, reason: org.error }
|
|
659
|
+
// The organization's pass, then the developer's own (§ above).
|
|
660
|
+
const first = () => (org.packs.length > 0 ? [compileRedaction({ packs: org.packs })] : [])
|
|
661
|
+
if (!Object.hasOwn(config, 'file')) {
|
|
662
|
+
if (org.packs.length === 0) return secrets ? defaultOn() : { state: 'off' }
|
|
663
|
+
return on('default', { org: org.packs, secrets }, () => [
|
|
664
|
+
...first(),
|
|
665
|
+
...(secrets ? [defaultRules()] : []),
|
|
666
|
+
])
|
|
667
|
+
}
|
|
668
|
+
const file = config.file
|
|
669
|
+
if (typeof file !== 'string' || file === '' || !isAbsolute(file)) {
|
|
670
|
+
return {
|
|
671
|
+
state: 'error',
|
|
672
|
+
...(typeof file === 'string' && file !== '' ? { file } : {}),
|
|
673
|
+
reason: `${settingsPath}: redaction.file must be an absolute path, got ${JSON.stringify(file)}`,
|
|
674
|
+
}
|
|
675
|
+
}
|
|
676
|
+
let developer
|
|
677
|
+
try {
|
|
678
|
+
developer = readRedactionFile(file, { withSecrets: secrets })
|
|
679
|
+
} catch (error) {
|
|
680
|
+
return { state: 'error', file, reason: reasonOf(error) }
|
|
681
|
+
}
|
|
682
|
+
return on('file', { file, org: org.packs, secrets }, () => [...first(), developer])
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
/** An `on` loader result over the passes `build` compiles. The packs ship in
|
|
686
|
+
* this package, so compiling them does not fail in practice; if the packaged
|
|
687
|
+
* data were ever broken it fails closed rather than send unchecked spans. */
|
|
688
|
+
const on = (source, fields, build) => {
|
|
689
|
+
try {
|
|
690
|
+
return { state: 'on', source, ...fields, redactor: layered(build()) }
|
|
691
|
+
} catch (error) {
|
|
692
|
+
return {
|
|
693
|
+
state: 'error',
|
|
694
|
+
...(fields.file === undefined ? {} : { file: fields.file }),
|
|
695
|
+
reason: `the redaction packs cannot be loaded: ${reasonOf(error)}`,
|
|
696
|
+
}
|
|
697
|
+
}
|
|
698
|
+
}
|
|
699
|
+
|
|
700
|
+
/** The default rules as a loader result: the `secrets` pack alone. */
|
|
701
|
+
const defaultOn = () => on('default', { org: [], secrets: true }, () => [defaultRules()])
|