@smthrs/journal 0.0.0-stage → 1.0.0-rc.13

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 (257) hide show
  1. package/CHANGELOG.md +149 -0
  2. package/LICENSE +21 -0
  3. package/README.md +208 -2
  4. package/dist/cjs/CallFact.d.ts +129 -0
  5. package/dist/cjs/CallFact.d.ts.map +1 -0
  6. package/dist/cjs/CallFact.js +106 -0
  7. package/dist/cjs/CallFact.js.map +7 -0
  8. package/dist/cjs/Consensus.d.ts +492 -0
  9. package/dist/cjs/Consensus.d.ts.map +1 -0
  10. package/dist/cjs/Consensus.js +314 -0
  11. package/dist/cjs/Consensus.js.map +7 -0
  12. package/dist/cjs/EngineEvent.d.ts +890 -0
  13. package/dist/cjs/EngineEvent.d.ts.map +1 -0
  14. package/dist/cjs/EngineEvent.js +383 -0
  15. package/dist/cjs/EngineEvent.js.map +7 -0
  16. package/dist/cjs/ExecutionFact.d.ts +216 -0
  17. package/dist/cjs/ExecutionFact.d.ts.map +1 -0
  18. package/dist/cjs/ExecutionFact.js +303 -0
  19. package/dist/cjs/ExecutionFact.js.map +7 -0
  20. package/dist/cjs/Journal.d.ts +617 -0
  21. package/dist/cjs/Journal.d.ts.map +1 -0
  22. package/dist/cjs/Journal.js +190 -0
  23. package/dist/cjs/Journal.js.map +7 -0
  24. package/dist/cjs/JournalEvent.d.ts +421 -0
  25. package/dist/cjs/JournalEvent.d.ts.map +1 -0
  26. package/dist/cjs/JournalEvent.js +281 -0
  27. package/dist/cjs/JournalEvent.js.map +7 -0
  28. package/dist/cjs/JournalGeneration.d.ts +34 -0
  29. package/dist/cjs/JournalGeneration.d.ts.map +1 -0
  30. package/dist/cjs/JournalGeneration.js +73 -0
  31. package/dist/cjs/JournalGeneration.js.map +7 -0
  32. package/dist/cjs/JournalMetrics.d.ts +72 -0
  33. package/dist/cjs/JournalMetrics.d.ts.map +1 -0
  34. package/dist/cjs/JournalMetrics.js +55 -0
  35. package/dist/cjs/JournalMetrics.js.map +7 -0
  36. package/dist/cjs/Migrations.d.ts +42 -0
  37. package/dist/cjs/Migrations.d.ts.map +1 -0
  38. package/dist/cjs/Migrations.js +58 -0
  39. package/dist/cjs/Migrations.js.map +7 -0
  40. package/dist/cjs/OwnerId.d.ts +40 -0
  41. package/dist/cjs/OwnerId.d.ts.map +1 -0
  42. package/dist/cjs/OwnerId.js +40 -0
  43. package/dist/cjs/OwnerId.js.map +7 -0
  44. package/dist/cjs/Projection.d.ts +29 -0
  45. package/dist/cjs/Projection.d.ts.map +1 -0
  46. package/dist/cjs/Projection.js +25 -0
  47. package/dist/cjs/Projection.js.map +7 -0
  48. package/dist/cjs/RedactedLogger.d.ts +121 -0
  49. package/dist/cjs/RedactedLogger.d.ts.map +1 -0
  50. package/dist/cjs/RedactedLogger.js +235 -0
  51. package/dist/cjs/RedactedLogger.js.map +7 -0
  52. package/dist/cjs/Redaction.d.ts +350 -0
  53. package/dist/cjs/Redaction.d.ts.map +1 -0
  54. package/dist/cjs/Redaction.js +962 -0
  55. package/dist/cjs/Redaction.js.map +7 -0
  56. package/dist/cjs/SqlConsensus.d.ts +44 -0
  57. package/dist/cjs/SqlConsensus.d.ts.map +1 -0
  58. package/dist/cjs/SqlConsensus.js +273 -0
  59. package/dist/cjs/SqlConsensus.js.map +7 -0
  60. package/dist/cjs/SqlJournal.d.ts +173 -0
  61. package/dist/cjs/SqlJournal.d.ts.map +1 -0
  62. package/dist/cjs/SqlJournal.js +1568 -0
  63. package/dist/cjs/SqlJournal.js.map +7 -0
  64. package/dist/cjs/StepFact.d.ts +66 -0
  65. package/dist/cjs/StepFact.d.ts.map +1 -0
  66. package/dist/cjs/StepFact.js +68 -0
  67. package/dist/cjs/StepFact.js.map +7 -0
  68. package/dist/cjs/index.d.ts +95 -0
  69. package/dist/cjs/index.d.ts.map +1 -0
  70. package/dist/cjs/index.js +63 -0
  71. package/dist/cjs/index.js.map +7 -0
  72. package/dist/cjs/internal/JournalInternalFault.d.ts +37 -0
  73. package/dist/cjs/internal/JournalInternalFault.d.ts.map +1 -0
  74. package/dist/cjs/internal/JournalInternalFault.js +43 -0
  75. package/dist/cjs/internal/JournalInternalFault.js.map +7 -0
  76. package/dist/cjs/migrations/0001_initial.d.ts +15 -0
  77. package/dist/cjs/migrations/0001_initial.d.ts.map +1 -0
  78. package/dist/cjs/migrations/0001_initial.js +54 -0
  79. package/dist/cjs/migrations/0001_initial.js.map +7 -0
  80. package/dist/cjs/migrations/0002_checkpoints.d.ts +27 -0
  81. package/dist/cjs/migrations/0002_checkpoints.d.ts.map +1 -0
  82. package/dist/cjs/migrations/0002_checkpoints.js +48 -0
  83. package/dist/cjs/migrations/0002_checkpoints.js.map +7 -0
  84. package/dist/cjs/migrations/0003_startup_index.d.ts +15 -0
  85. package/dist/cjs/migrations/0003_startup_index.d.ts.map +1 -0
  86. package/dist/cjs/migrations/0003_startup_index.js +40 -0
  87. package/dist/cjs/migrations/0003_startup_index.js.map +7 -0
  88. package/dist/cjs/migrations/0004_dedup.d.ts +15 -0
  89. package/dist/cjs/migrations/0004_dedup.d.ts.map +1 -0
  90. package/dist/cjs/migrations/0004_dedup.js +57 -0
  91. package/dist/cjs/migrations/0004_dedup.js.map +7 -0
  92. package/dist/cjs/migrations/0005_run_event_type.d.ts +15 -0
  93. package/dist/cjs/migrations/0005_run_event_type.d.ts.map +1 -0
  94. package/dist/cjs/migrations/0005_run_event_type.js +40 -0
  95. package/dist/cjs/migrations/0005_run_event_type.js.map +7 -0
  96. package/dist/cjs/migrations/0006_consensus.d.ts +22 -0
  97. package/dist/cjs/migrations/0006_consensus.d.ts.map +1 -0
  98. package/dist/cjs/migrations/0006_consensus.js +84 -0
  99. package/dist/cjs/migrations/0006_consensus.js.map +7 -0
  100. package/dist/cjs/package.json +1 -0
  101. package/dist/cjs/test/Notifying.d.ts +65 -0
  102. package/dist/cjs/test/Notifying.d.ts.map +1 -0
  103. package/dist/cjs/test/Notifying.js +62 -0
  104. package/dist/cjs/test/Notifying.js.map +7 -0
  105. package/dist/cjs/test/TestJournal.d.ts +43 -0
  106. package/dist/cjs/test/TestJournal.d.ts.map +1 -0
  107. package/dist/cjs/test/TestJournal.js +43 -0
  108. package/dist/cjs/test/TestJournal.js.map +7 -0
  109. package/dist/esm/CallFact.d.ts +129 -0
  110. package/dist/esm/CallFact.d.ts.map +1 -0
  111. package/dist/esm/CallFact.js +96 -0
  112. package/dist/esm/CallFact.js.map +1 -0
  113. package/dist/esm/Consensus.d.ts +492 -0
  114. package/dist/esm/Consensus.d.ts.map +1 -0
  115. package/dist/esm/Consensus.js +548 -0
  116. package/dist/esm/Consensus.js.map +1 -0
  117. package/dist/esm/EngineEvent.d.ts +890 -0
  118. package/dist/esm/EngineEvent.d.ts.map +1 -0
  119. package/dist/esm/EngineEvent.js +614 -0
  120. package/dist/esm/EngineEvent.js.map +1 -0
  121. package/dist/esm/ExecutionFact.d.ts +216 -0
  122. package/dist/esm/ExecutionFact.d.ts.map +1 -0
  123. package/dist/esm/ExecutionFact.js +374 -0
  124. package/dist/esm/ExecutionFact.js.map +1 -0
  125. package/dist/esm/Journal.d.ts +617 -0
  126. package/dist/esm/Journal.d.ts.map +1 -0
  127. package/dist/esm/Journal.js +323 -0
  128. package/dist/esm/Journal.js.map +1 -0
  129. package/dist/esm/JournalEvent.d.ts +421 -0
  130. package/dist/esm/JournalEvent.d.ts.map +1 -0
  131. package/dist/esm/JournalEvent.js +517 -0
  132. package/dist/esm/JournalEvent.js.map +1 -0
  133. package/dist/esm/JournalGeneration.d.ts +34 -0
  134. package/dist/esm/JournalGeneration.d.ts.map +1 -0
  135. package/dist/esm/JournalGeneration.js +71 -0
  136. package/dist/esm/JournalGeneration.js.map +1 -0
  137. package/dist/esm/JournalMetrics.d.ts +72 -0
  138. package/dist/esm/JournalMetrics.d.ts.map +1 -0
  139. package/dist/esm/JournalMetrics.js +79 -0
  140. package/dist/esm/JournalMetrics.js.map +1 -0
  141. package/dist/esm/Migrations.d.ts +42 -0
  142. package/dist/esm/Migrations.d.ts.map +1 -0
  143. package/dist/esm/Migrations.js +59 -0
  144. package/dist/esm/Migrations.js.map +1 -0
  145. package/dist/esm/OwnerId.d.ts +40 -0
  146. package/dist/esm/OwnerId.d.ts.map +1 -0
  147. package/dist/esm/OwnerId.js +33 -0
  148. package/dist/esm/OwnerId.js.map +1 -0
  149. package/dist/esm/Projection.d.ts +29 -0
  150. package/dist/esm/Projection.d.ts.map +1 -0
  151. package/dist/esm/Projection.js +13 -0
  152. package/dist/esm/Projection.js.map +1 -0
  153. package/dist/esm/RedactedLogger.d.ts +121 -0
  154. package/dist/esm/RedactedLogger.d.ts.map +1 -0
  155. package/dist/esm/RedactedLogger.js +445 -0
  156. package/dist/esm/RedactedLogger.js.map +1 -0
  157. package/dist/esm/Redaction.d.ts +350 -0
  158. package/dist/esm/Redaction.d.ts.map +1 -0
  159. package/dist/esm/Redaction.js +1628 -0
  160. package/dist/esm/Redaction.js.map +1 -0
  161. package/dist/esm/SqlConsensus.d.ts +44 -0
  162. package/dist/esm/SqlConsensus.d.ts.map +1 -0
  163. package/dist/esm/SqlConsensus.js +273 -0
  164. package/dist/esm/SqlConsensus.js.map +1 -0
  165. package/dist/esm/SqlJournal.d.ts +173 -0
  166. package/dist/esm/SqlJournal.d.ts.map +1 -0
  167. package/dist/esm/SqlJournal.js +1858 -0
  168. package/dist/esm/SqlJournal.js.map +1 -0
  169. package/dist/esm/StepFact.d.ts +66 -0
  170. package/dist/esm/StepFact.d.ts.map +1 -0
  171. package/dist/esm/StepFact.js +50 -0
  172. package/dist/esm/StepFact.js.map +1 -0
  173. package/dist/esm/index.d.ts +95 -0
  174. package/dist/esm/index.d.ts.map +1 -0
  175. package/dist/esm/index.js +95 -0
  176. package/dist/esm/index.js.map +1 -0
  177. package/dist/esm/internal/JournalInternalFault.d.ts +37 -0
  178. package/dist/esm/internal/JournalInternalFault.d.ts.map +1 -0
  179. package/dist/esm/internal/JournalInternalFault.js +28 -0
  180. package/dist/esm/internal/JournalInternalFault.js.map +1 -0
  181. package/dist/esm/migrations/0001_initial.d.ts +15 -0
  182. package/dist/esm/migrations/0001_initial.d.ts.map +1 -0
  183. package/dist/esm/migrations/0001_initial.js +32 -0
  184. package/dist/esm/migrations/0001_initial.js.map +1 -0
  185. package/dist/esm/migrations/0002_checkpoints.d.ts +27 -0
  186. package/dist/esm/migrations/0002_checkpoints.d.ts.map +1 -0
  187. package/dist/esm/migrations/0002_checkpoints.js +38 -0
  188. package/dist/esm/migrations/0002_checkpoints.js.map +1 -0
  189. package/dist/esm/migrations/0003_startup_index.d.ts +15 -0
  190. package/dist/esm/migrations/0003_startup_index.d.ts.map +1 -0
  191. package/dist/esm/migrations/0003_startup_index.js +18 -0
  192. package/dist/esm/migrations/0003_startup_index.js.map +1 -0
  193. package/dist/esm/migrations/0004_dedup.d.ts +15 -0
  194. package/dist/esm/migrations/0004_dedup.d.ts.map +1 -0
  195. package/dist/esm/migrations/0004_dedup.js +38 -0
  196. package/dist/esm/migrations/0004_dedup.js.map +1 -0
  197. package/dist/esm/migrations/0005_run_event_type.d.ts +15 -0
  198. package/dist/esm/migrations/0005_run_event_type.d.ts.map +1 -0
  199. package/dist/esm/migrations/0005_run_event_type.js +18 -0
  200. package/dist/esm/migrations/0005_run_event_type.js.map +1 -0
  201. package/dist/esm/migrations/0006_consensus.d.ts +22 -0
  202. package/dist/esm/migrations/0006_consensus.d.ts.map +1 -0
  203. package/dist/esm/migrations/0006_consensus.js +69 -0
  204. package/dist/esm/migrations/0006_consensus.js.map +1 -0
  205. package/dist/esm/test/Notifying.d.ts +65 -0
  206. package/dist/esm/test/Notifying.d.ts.map +1 -0
  207. package/dist/esm/test/Notifying.js +62 -0
  208. package/dist/esm/test/Notifying.js.map +1 -0
  209. package/dist/esm/test/TestJournal.d.ts +43 -0
  210. package/dist/esm/test/TestJournal.d.ts.map +1 -0
  211. package/dist/esm/test/TestJournal.js +27 -0
  212. package/dist/esm/test/TestJournal.js.map +1 -0
  213. package/docs/README.md +166 -0
  214. package/docs/api.md +650 -0
  215. package/docs/concepts/compaction.md +157 -0
  216. package/docs/concepts/idempotency.md +127 -0
  217. package/docs/concepts/owner-fence.md +128 -0
  218. package/docs/concepts/redaction.md +222 -0
  219. package/docs/concepts/state-event-authority.md +159 -0
  220. package/docs/concepts/two-channels.md +167 -0
  221. package/docs/guides/commit-state-and-entry.md +114 -0
  222. package/docs/guides/compact-a-run.md +134 -0
  223. package/docs/guides/fold-a-projection.md +106 -0
  224. package/docs/guides/read-a-run.md +139 -0
  225. package/docs/guides/redact-log-output.md +94 -0
  226. package/docs/guides/testing.md +124 -0
  227. package/docs/guides/write-lifecycle-events.md +110 -0
  228. package/docs/installation.md +137 -0
  229. package/docs/quickstart.md +146 -0
  230. package/docs/troubleshooting.md +214 -0
  231. package/package.json +263 -3
  232. package/src/CallFact.ts +117 -0
  233. package/src/Consensus.ts +814 -0
  234. package/src/EngineEvent.ts +823 -0
  235. package/src/ExecutionFact.ts +433 -0
  236. package/src/Journal.ts +688 -0
  237. package/src/JournalEvent.ts +654 -0
  238. package/src/JournalGeneration.ts +83 -0
  239. package/src/JournalMetrics.ts +89 -0
  240. package/src/Migrations.ts +62 -0
  241. package/src/OwnerId.ts +42 -0
  242. package/src/Projection.ts +31 -0
  243. package/src/RedactedLogger.ts +483 -0
  244. package/src/Redaction.ts +1828 -0
  245. package/src/SqlConsensus.ts +384 -0
  246. package/src/SqlJournal.ts +2732 -0
  247. package/src/StepFact.ts +69 -0
  248. package/src/index.ts +109 -0
  249. package/src/internal/JournalInternalFault.ts +40 -0
  250. package/src/migrations/0001_initial.ts +41 -0
  251. package/src/migrations/0002_checkpoints.ts +46 -0
  252. package/src/migrations/0003_startup_index.ts +19 -0
  253. package/src/migrations/0004_dedup.ts +43 -0
  254. package/src/migrations/0005_run_event_type.ts +19 -0
  255. package/src/migrations/0006_consensus.ts +83 -0
  256. package/src/test/Notifying.ts +101 -0
  257. package/src/test/TestJournal.ts +52 -0
@@ -0,0 +1,1828 @@
1
+ /**
2
+ * Payload redaction for durable journal writes.
3
+ *
4
+ * The journal is permanent and broadly readable: every entry is replayed to
5
+ * sync subscribers and to time-travel consumers. A secret that reaches
6
+ * `payload_json` is therefore not a transient leak, so redaction happens once,
7
+ * on the journal write path, rather than at each reader.
8
+ *
9
+ * Redaction is an **observability** concern and is confined to journal events
10
+ * and export/display surfaces. It is deliberately not applied to executable
11
+ * state, `flows_runs.state_json`, attempt checkpoints, errors, outcomes, and
12
+ * cache results, because those are decoded and re-entered on resume: a
13
+ * placeholder there resumes the flow with the wrong data, and replacing a
14
+ * non-string value with a placeholder string makes the persisted state fail
15
+ * schema decode outright, leaving the run undrivable (issue #72). A value
16
+ * that must never reach durable executable state is a `Redacted` field in the
17
+ * caller's own schema, not a name-suffix guess made at the storage seam.
18
+ *
19
+ * The rule set is a best-effort textual net over credential shapes seen in
20
+ * real bug reports, plus structural redaction by sensitive field name. It is
21
+ * finite, so a value that must never persist belongs in a `Redacted` field of
22
+ * the caller's own schema. See https://journal.smithers.sh/concepts/redaction/
23
+ * for the rule set and how to replace it.
24
+ *
25
+ * @since 0.1.0
26
+ */
27
+
28
+ import * as Result from "effect/Result"
29
+ import * as Schema from "effect/Schema"
30
+
31
+ /** JSON text carrying an arbitrary decoded value. */
32
+ const UnknownFromJsonString = Schema.fromJsonString(Schema.Unknown)
33
+
34
+ /**
35
+ * A textual redaction rule.
36
+ *
37
+ * `replace` is the substitution for a matched span; when omitted the whole
38
+ * match is replaced by the placeholder.
39
+ *
40
+ * `rewrite`, when set, rewrites the text itself instead. It is for a rule
41
+ * whose extent is not regular: where a credential's value ends depends on
42
+ * quotes, escapes and brackets a regular expression cannot count. `pattern`
43
+ * then names what the rule looks for, and text `pattern` does not match is
44
+ * left unchanged without calling `rewrite`.
45
+ *
46
+ * @since 0.1.0
47
+ * @category models
48
+ */
49
+ export interface Rule {
50
+ readonly id: string
51
+ readonly pattern: RegExp
52
+ readonly replace?: string | undefined
53
+ readonly rewrite?: ((text: string) => string) | undefined
54
+ }
55
+
56
+ /**
57
+ * The placeholder written in place of a redacted value.
58
+ *
59
+ * @since 0.1.0
60
+ * @category constants
61
+ */
62
+ export const placeholder = "[REDACTED]"
63
+
64
+ const isQuote = (char: string | undefined): boolean => char === "\"" || char === "'" || char === "`"
65
+
66
+ const closers: Readonly<Record<string, string>> = { "{": "}", "[": "]", "(": ")" }
67
+
68
+ /**
69
+ * Whether the last {@link skipQuoted} or {@link skipContainer} found its
70
+ * closer. Both return the end of the text for a value that never closes, and
71
+ * for one that closes on the text's last character, so the end alone cannot
72
+ * say which.
73
+ */
74
+ let lastClosed = false
75
+
76
+ /**
77
+ * The index just past the quote that closes the string opened at `open`. A
78
+ * quote nested n strings deep sits behind `depth` = 2^n - 1 backslashes, and
79
+ * the quote that closes it has that count modulo 2^(n+1). A string that is
80
+ * never closed, cut by a bound or by its producer, runs to the end of the
81
+ * text. A caller that knows the backslashes were doubled again passes a larger
82
+ * `modulus`.
83
+ */
84
+ const skipQuoted = (
85
+ text: string,
86
+ open: number,
87
+ depth: number,
88
+ modulus = 2 * (depth + 1),
89
+ limit = text.length
90
+ ): number => {
91
+ let end = open + 1
92
+ while (end < limit) {
93
+ if (text[end] === text[open]) {
94
+ let slashes = 0
95
+ for (let i = end - 1; i > open && text[i] === "\\"; i--) slashes++
96
+ if (slashes % modulus === depth) {
97
+ lastClosed = true
98
+ return end + 1
99
+ }
100
+ }
101
+ end++
102
+ }
103
+ lastClosed = false
104
+ return end
105
+ }
106
+
107
+ /**
108
+ * The index just past the bracket that balances the one at `open`, skipping
109
+ * quoted strings at any escape depth. An unbalanced container runs to the end
110
+ * of the text.
111
+ */
112
+ const skipContainer = (text: string, open: number, limit = text.length): number => {
113
+ const pending: Array<string> = []
114
+ let end = open
115
+ while (end < limit) {
116
+ const char = text[end]!
117
+ if (isQuote(char)) {
118
+ let depth = 0
119
+ while (text[end - 1 - depth] === "\\") depth++
120
+ end = skipQuoted(text, end, depth, 2 * (depth + 1), limit)
121
+ if (!lastClosed) return end
122
+ continue
123
+ }
124
+ const closer = closers[char]
125
+ if (closer !== undefined) pending.push(closer)
126
+ else if (char === pending.at(-1)) {
127
+ pending.pop()
128
+ if (pending.length === 0) {
129
+ lastClosed = true
130
+ return end + 1
131
+ }
132
+ }
133
+ end++
134
+ }
135
+ lastClosed = false
136
+ return end
137
+ }
138
+
139
+ /**
140
+ * A bracket or string still open at some point of the text: a bracket by its
141
+ * closer, a string by its quote and escape depth. `string` is the index of the
142
+ * innermost open string at or below this entry, -1 when there is none, so
143
+ * finding the innermost string costs one read however deep the brackets
144
+ * above it are nested. A scan from the top made a text of n brackets and then
145
+ * n quotes cost n² (#3088).
146
+ */
147
+ interface Open {
148
+ readonly close: string
149
+ readonly depth?: number
150
+ readonly string: number
151
+ }
152
+
153
+ /**
154
+ * The escape depth of a quote behind `slashes` backslashes: 2^k - 1 for its k
155
+ * trailing escaped levels, so `\\"` (an escaped backslash, then a quote) is
156
+ * depth 0 and `\\\"` is depth 1.
157
+ */
158
+ const escapeDepth = (slashes: number): number => (slashes ^ (slashes + 1)) >> 1
159
+
160
+ const innermostString = (stack: ReadonlyArray<Open>): number => stack.at(-1)?.string ?? -1
161
+
162
+ /**
163
+ * Updates `stack` with the brackets and strings that `text[from, to)` opens
164
+ * and closes. A quote closes the innermost open string it can close at that
165
+ * string's escape depth, and otherwise opens a string at its own depth. The
166
+ * other quote characters inside a string are content (`"don't"`).
167
+ */
168
+ const track = (stack: Array<Open>, text: string, from: number, to: number): void => {
169
+ for (let i = from; i < to; i++) {
170
+ const char = text[i]!
171
+ if (isQuote(char)) {
172
+ let slashes = 0
173
+ while (text[i - 1 - slashes] === "\\") slashes++
174
+ const inner = innermostString(stack)
175
+ if (inner === -1) {
176
+ stack.push({ close: char, depth: escapeDepth(slashes), string: stack.length })
177
+ continue
178
+ }
179
+ if (stack[inner]!.close !== char) continue
180
+ // Only strings can close, so walk the strings alone, innermost first.
181
+ let closes = inner
182
+ while (closes !== -1) {
183
+ const depth = stack[closes]!.depth!
184
+ if (slashes % (2 * (depth + 1)) === depth) break
185
+ closes = closes === 0 ? -1 : stack[closes - 1]!.string
186
+ }
187
+ if (closes === -1) stack.push({ close: char, depth: escapeDepth(slashes), string: stack.length })
188
+ else stack.length = closes
189
+ continue
190
+ }
191
+ const closer = closers[char]
192
+ if (closer !== undefined) stack.push({ close: closer, string: innermostString(stack) })
193
+ else if (stack.at(-1)?.depth === undefined && char === stack.at(-1)?.close) stack.pop()
194
+ }
195
+ }
196
+
197
+ /**
198
+ * Whether the closer at `end` closes the bracket open before the name: it and
199
+ * any closers right after it balance the enclosing brackets, and a separator
200
+ * or the end of the text follows (`[{token:abc}]`, not `Tr0ub4dor)]&3`).
201
+ */
202
+ const closesEnclosing = (text: string, end: number, stack: ReadonlyArray<Open>): boolean => {
203
+ let at = end
204
+ for (let k = stack.length - 1; k >= 0 && stack[k]!.depth === undefined && text[at] === stack[k]!.close; k--) at++
205
+ return at > end && /^(?:[\s,;"'`]|\\+["'`]|$)/.test(text.slice(at, at + 2))
206
+ }
207
+
208
+ /** Credential words a name ends in. */
209
+ const credentialWord = "(?:KEY|TOKEN|SECRET|PASSWORD|PASSPHRASE|CREDENTIAL)S?"
210
+
211
+ /**
212
+ * A name's separator: `=`, `:` or `=>`, after any quote that closes the name.
213
+ * In a durable row it stays on the name's line; a diagnostic also reads a
214
+ * value on the next line (`password:` then the value), which is how a stream
215
+ * redactor sees it arrive.
216
+ */
217
+ const separator = (space: string): string => String.raw`(?:\\*["'\x60])?${space}(?:=>|[=:])${space}`
218
+
219
+ /**
220
+ * A credential name and its separator. Start once per identifier, including
221
+ * leading underscores, so a name containing many underscores cannot force
222
+ * repeated scans of its suffix. The name may close a quote of its own
223
+ * (`'password':`, `\"token\":`), so a key in a Python repr, an inspected
224
+ * `Map` or escaped JSON meets the rule too.
225
+ */
226
+ const credentialName = String.raw`(?<![A-Za-z0-9_-])([A-Za-z0-9_-]*${credentialWord})`
227
+
228
+ const credentialNames = new RegExp(credentialName + separator("[ \\t]*"), "gi")
229
+
230
+ const diagnosticNames = new RegExp(credentialName + separator(String.raw`\s*`), "gi")
231
+
232
+ /** Case-insensitive authorization names, without making scheme words prose matches. */
233
+ const authorizationName = "(?:proxy-)?authorization".replace(/[a-z]/g, (char) => `[${char}${char.toUpperCase()}]`)
234
+
235
+ /** Complete header names whose whole value is a credential whatever its scheme. */
236
+ const headerWord = String.raw`${authorizationName}|${
237
+ "(?:set-)?cookies?".replace(/[a-z]/g, (char) => `[${char}${char.toUpperCase()}]`)
238
+ }`
239
+
240
+ // Apostrophes and backticks open quoted names only outside a header token.
241
+ const headerName = String
242
+ .raw`(?<![A-Za-z0-9!#$%&*+.^_|~-])(?<![A-Za-z0-9!#$%&'*+.^_\x60|~-]['\x60])(${headerWord})`
243
+
244
+ const headerNames = new RegExp(
245
+ String.raw`((?:proxy-)?authorization|(?:set-)?cookies?)${separator(String.raw`\s*`)}`,
246
+ "gi"
247
+ )
248
+
249
+ /** Whitespace headers require a scheme spelling, so ordinary authorization prose survives. */
250
+ const diagnosticHeaderNames = new RegExp(
251
+ // A trailing token quote requires an opener; double quotes are never token characters.
252
+ `${headerName}(?:` +
253
+ String.raw`(?:(?<=["'\x60](?:${headerWord}))|(?!\\*['\x60]))${separator(String.raw`\s*`)}|` +
254
+ String.raw`(?<=${authorizationName})\s+(?=(?:Token|TOKEN|[Bb]earer|BEARER|Basic|BASIC)[ \t]+\S))`,
255
+ "g"
256
+ )
257
+
258
+ /** Any credential or header name, to stop a bare value before the next pair. */
259
+ const anyName = new RegExp(`${credentialNames.source}|${headerNames.source}`, "gi")
260
+
261
+ /** A credential or header name and its separator ending the text before a quote. */
262
+ const nameBefore = new RegExp(`(?:${credentialNames.source}|${headerNames.source})$`, "i")
263
+
264
+ /**
265
+ * The index of the next credential or header name at or after `from`; with
266
+ * `quoted`, only a name written right after a quote.
267
+ */
268
+ const nextName = (text: string, from: number, quoted: boolean): number => {
269
+ // No name starts between a search's start and what it found, so a later
270
+ // search from inside that span has the same answer. Values are read left to
271
+ // right, so this keeps every search over one text linear in total.
272
+ const cached = nameSearches[quoted ? 1 : 0]!
273
+ if (cached.text === text && from >= cached.from && from <= cached.found) return cached.found
274
+ let found = text.length
275
+ anyName.lastIndex = from
276
+ for (let match = anyName.exec(text); match !== null; match = anyName.exec(text)) {
277
+ if (!quoted || isQuote(text[match.index - 1])) {
278
+ found = match.index
279
+ break
280
+ }
281
+ }
282
+ nameSearches[quoted ? 1 : 0] = { text, from, found }
283
+ return found
284
+ }
285
+
286
+ /** The last search for any name and for a quoted name. */
287
+ const nameSearches = [{ text: "", from: 0, found: 0 }, { text: "", from: 0, found: 0 }]
288
+
289
+ /**
290
+ * How far a value may run.
291
+ *
292
+ * A diagnostic is read once, so it errs toward hiding: a bare value runs over
293
+ * several words to the end of its line, and a string or container the text
294
+ * never closes runs to the end of the text, which is how a value cut by a
295
+ * bound still ends redacted. A journal row is permanent, so there a bare value
296
+ * is one token, `Foo {`, `[Object: null prototype] {` and `new X(` included,
297
+ * and an unclosed string or container stops at the end of its line: a stray
298
+ * backtick in an agent's Markdown must not erase the rest of the row.
299
+ */
300
+ interface Scope {
301
+ readonly header: boolean
302
+ readonly diagnostic: boolean
303
+ }
304
+
305
+ /** The end of the line `index` is on. */
306
+ const lineEnd = (text: string, index: number): number => {
307
+ // Every index up to a line's end shares that end, so the last answer serves
308
+ // each later value on the same line.
309
+ if (lastLine.text === text && index >= lastLine.from && index <= lastLine.end) return lastLine.end
310
+ newline.lastIndex = index
311
+ const end = newline.exec(text)?.index ?? text.length
312
+ lastLine = { text, from: index, end }
313
+ return end
314
+ }
315
+
316
+ const newline = /[\r\n]/g
317
+
318
+ let lastLine = { text: "", from: 0, end: 0 }
319
+
320
+ /**
321
+ * Whether the whitespace at `end` continues the one-token value that began at
322
+ * `start`: `util.inspect` separates a constructor or a marker from its
323
+ * contents (`Foo {`, `Map(1) {`, `[Object: null prototype] {`, `<ref *1> {`,
324
+ * `new Password(`).
325
+ */
326
+ const continuesAcrossSpace = (text: string, start: number, end: number): number | undefined => {
327
+ const run = text.slice(start, end)
328
+ let next = end
329
+ while (text[next] === " " || text[next] === "\t") next++
330
+ if (run === "new") return next
331
+ const prefix = /^[\w$.]+$/.test(run) || /[)\]>]$/.test(run)
332
+ return prefix && closers[text[next] ?? ""] !== undefined ? next : undefined
333
+ }
334
+
335
+ /**
336
+ * Whether the `,`, `;` or `&` at `end` separates pairs rather than sitting
337
+ * inside a value (`Zq7;Syn,thetic`, `Tr0ub(4dor)&3`): a space or another name
338
+ * follows it, and for `&`, a query parameter (`&page=2`).
339
+ */
340
+ const separatesPairs = (text: string, end: number): boolean =>
341
+ text[end] === "&"
342
+ ? /^&[A-Za-z_][\w.-]*=/.test(text.slice(end, end + 64))
343
+ : /^[,;](?:\s|$|\s*\\*["'`]?[A-Za-z_][\w.-]*\\*["'`]?\s*(?:=>|[=:]))/.test(text.slice(end, end + 64))
344
+
345
+ /**
346
+ * How far past its line every durable container may read, whatever the
347
+ * {@link Budget} has left: a pretty-printed credential object of this size
348
+ * is read whole on any row.
349
+ */
350
+ const containerWindow = 4096
351
+
352
+ /**
353
+ * How many characters durable container scans past a line may read over one
354
+ * text, in total: {@link containerBudget} times the text's length. A fixed
355
+ * window alone left a secret more than 4 KiB inside a credential-named
356
+ * container in the row, and extending it without a total made a text of
357
+ * unclosed brackets cost the square of its length (#3088). With the budget a
358
+ * large container is read whole, and a row of unclosed brackets still costs
359
+ * a constant multiple of its length plus {@link containerWindow} per value.
360
+ */
361
+ interface Budget {
362
+ remaining: number
363
+ }
364
+
365
+ const containerBudget = 4
366
+
367
+ /**
368
+ * The end of the bare value at `start`, read as a run of tokens: words,
369
+ * balanced containers anywhere in it (`{bcrypt}$2a$...`, `Tr0ub(4dor)&3`,
370
+ * `Some("x")`), inspect markers (`<Buffer 73 65>`, `<ref *1>`), and quoted
371
+ * parts. `stack` is what is open before the name: the value stops at a quote
372
+ * that closes the enclosing string, at a closer that closes the enclosing
373
+ * bracket, and before the next credential name.
374
+ */
375
+ const bareValueEnd = (
376
+ text: string,
377
+ start: number,
378
+ scope: Scope,
379
+ stack: ReadonlyArray<Open>,
380
+ budget: Budget
381
+ ): number => {
382
+ const inner = stack[innermostString(stack)]
383
+ // A durable value never reads an unclosed quote past its line, and one it
384
+ // cannot close stops at its line. A bracket reads past 4 KiB only while
385
+ // the text's scan budget lasts: each unbalanced bracket costs a bounded
386
+ // scan, and all of them together a bounded multiple of the text.
387
+ const bound = scope.diagnostic ? text.length : lineEnd(text, start)
388
+ const window = scope.diagnostic
389
+ ? text.length
390
+ : Math.min(text.length, start + Math.max(containerWindow, budget.remaining))
391
+ // Never before the opener: a closed container may already have carried the
392
+ // value past its first line.
393
+ const unclosed = (open: number, end: number): number => Math.max(open, Math.min(end, bound))
394
+ // A durable container first reads its own line. A pretty-printer only
395
+ // continues one on the next line after the opener or a member's comma
396
+ // (`apiKey: {`, `credentials: { a: 1,`), so only then does the scan read on
397
+ // through the window.
398
+ const container = (open: number): number => {
399
+ if (scope.diagnostic) return skipContainer(text, open, window)
400
+ const end = skipContainer(text, open, bound)
401
+ if (lastClosed || !/[[{(,]\s*$/.test(text.slice(open, bound))) return end
402
+ const past = skipContainer(text, open, window)
403
+ budget.remaining -= past - open
404
+ return past
405
+ }
406
+ let end = start
407
+ // The value's own first token is never the next name: in
408
+ // `api_key=lowercase-secret:end` the value only looks like a `name:` pair.
409
+ let limit = nextName(text, start + 1, scope.header)
410
+ // A header value that is one container ends with it: `"cookie":["sid=a"],`.
411
+ if (scope.header && closers[text[start]!] !== undefined) {
412
+ end = container(start)
413
+ if (!/^[^\s,;"'`\\)\]}]/.test(text[end] ?? " ")) return lastClosed ? end : unclosed(start, end)
414
+ }
415
+ while (end < text.length) {
416
+ if (end >= limit) {
417
+ if (end === limit) break
418
+ limit = nextName(text, end, scope.header)
419
+ continue
420
+ }
421
+ const char = text[end]!
422
+ if (closers[char] !== undefined) {
423
+ const open = end
424
+ end = container(open)
425
+ // An unbalanced container runs on, spaces included.
426
+ if (!lastClosed) return unclosed(open, end)
427
+ continue
428
+ }
429
+ if (char === "<") {
430
+ angleClose.lastIndex = end
431
+ const close = angleClose.exec(text)?.index
432
+ if (close !== undefined && text[close] === ">") {
433
+ end = close + 1
434
+ continue
435
+ }
436
+ }
437
+ let depth = 0
438
+ while (text[end + depth] === "\\") depth++
439
+ const quote = text[end + depth]
440
+ if (isQuote(quote)) {
441
+ // A quote at the enclosing string's depth or shallower closes it,
442
+ // whatever precedes it (`Basic abc=`), unless a credential name and
443
+ // separator precede it (`credential:"`). Inside a bracket, a field's
444
+ // value ends at a quote (`{\"token\":abc\"}`). Any other quote opens a
445
+ // quoted part of the value (`username="admin"`, `it's`).
446
+ const closesString = inner !== undefined && quote === inner.close &&
447
+ depth % (2 * (inner.depth! + 1)) <= inner.depth! &&
448
+ !nameBefore.test(text.slice(Math.max(start, end - 256), end))
449
+ if (closesString || (!scope.header && inner === undefined && stack.length > 0)) break
450
+ // A quote between two word characters is an apostrophe (`it's`).
451
+ if (depth === 0 && /\w/.test(text[end - 1] ?? "") && /\w/.test(text[end + 1] ?? "")) {
452
+ end++
453
+ continue
454
+ }
455
+ const open = end
456
+ end = skipQuoted(text, end + depth, depth, 2 * (depth + 1), bound)
457
+ if (!lastClosed) return unclosed(open, end)
458
+ continue
459
+ }
460
+ if (char === "\r" || char === "\n") break
461
+ // Inside a bracket a `,` or `;` separates members; in raw text it does
462
+ // when a space or another name follows.
463
+ if (
464
+ !scope.header &&
465
+ ((char === "&" && separatesPairs(text, end)) ||
466
+ ((char === "," || char === ";") && (stack.length > 0 || separatesPairs(text, end))))
467
+ ) break
468
+ if (!scope.header && !scope.diagnostic && (char === " " || char === "\t")) {
469
+ const next = continuesAcrossSpace(text, start, end)
470
+ if (next === undefined) break
471
+ end = next
472
+ continue
473
+ }
474
+ if (closesEnclosing(text, end, stack)) break
475
+ end++
476
+ }
477
+ while (end > start && /\s/.test(text[end - 1]!)) end--
478
+ return end
479
+ }
480
+
481
+ /**
482
+ * Whether a name ending in `key` or `keys` is not a credential's: it counts
483
+ * only where {@link isSensitiveKey} agrees, as it does for the same name as an
484
+ * object key (`apiKeys` counts; `keys`, `sortKeys`, `idempotencyKey` and
485
+ * `monkey` do not).
486
+ */
487
+ const plainKeyName = (name: string): boolean => /keys?$/i.test(name) && !isSensitiveKey(name)
488
+
489
+ /**
490
+ * The end of a credential that is a URL's password (`//x-access-token:secret@`):
491
+ * the `@` that closes the userinfo, so the host and path stay readable. Any
492
+ * other bare value keeps its end.
493
+ */
494
+ const userinfoEnd = (text: string, start: number, end: number): number => {
495
+ if (!/\/\/[^\s/@?#]*[:=]$/.test(text.slice(Math.max(0, start - 128), start))) return end
496
+ const value = text.slice(start, end)
497
+ const authority = value.search(/[/?#]/)
498
+ const at = value.lastIndexOf("@", authority < 0 ? value.length : authority)
499
+ return at > 0 ? start + at : end
500
+ }
501
+
502
+ /**
503
+ * Whether a name that matched a credential word names a credential: not a
504
+ * {@link plainKeyName}, and not a count under a plural `tokens` name
505
+ * (`max_tokens: 4096`), which is accounting.
506
+ */
507
+ const namesCredential = (name: string, value: string): boolean =>
508
+ !plainKeyName(name) &&
509
+ !(/tokens$/i.test(name) && /^["'`]?\d+(?![\w.])/.test(value))
510
+
511
+ /** The `>` that closes an inspect marker, or the line end that means there is none. */
512
+ const angleClose = /[>\r\n]/g
513
+
514
+ /**
515
+ * The `+` with which `util.inspect` continues a long string on the next line,
516
+ * its newline raw or escaped (`\\n`) when the inspected text was itself
517
+ * written into a string.
518
+ */
519
+ const continuation = /(?:\s|\\+[nrt])*\+(?:\s|\\+[nrt])*/y
520
+
521
+ /** A value an earlier pass already replaced. */
522
+ const alreadyRedacted = /^\[REDACTED\]$/
523
+
524
+ /**
525
+ * Redacts the value after each name `names` matches. A quoted value is
526
+ * consumed whole at any string-escape depth, with the pieces `util.inspect`
527
+ * joins with `+` across lines, and its quotes are kept around the
528
+ * placeholder; a bare value is consumed as a run of tokens. A name that ends
529
+ * in `key` counts only where {@link isSensitiveKey} agrees, so `sortKey` and
530
+ * `idempotencyKey` keep their values, and a count under a plural `tokens`
531
+ * name, `max_tokens: 4096`, is accounting and is kept too.
532
+ */
533
+ const redactValues = (text: string, names: RegExp, scope: Scope): string => {
534
+ const keys = new RegExp(names.source, names.flags)
535
+ let output = ""
536
+ let position = 0
537
+ // What is open before the current value. Values are skipped, so a bracket
538
+ // or quote inside a credential never counts.
539
+ const stack: Array<Open> = []
540
+ const budget: Budget = { remaining: containerBudget * text.length }
541
+ let scanned = 0
542
+ for (let match = keys.exec(text); match !== null; match = keys.exec(text)) {
543
+ const name = match[1]!
544
+ if (!scope.header && plainKeyName(name)) continue
545
+ track(stack, text, scanned, keys.lastIndex)
546
+ scanned = keys.lastIndex
547
+ // A call's `key=` naming a function (`sorted(xs, key=lambda m: m[0])`)
548
+ // is code: a literal credential there would be quoted.
549
+ if (
550
+ !scope.diagnostic && name === "key" && text[keys.lastIndex - 1] === "=" &&
551
+ stack.at(-1)?.close === ")" && stack.at(-1)?.depth === undefined &&
552
+ /^[A-Za-z_][\w.]*(?=[\s(),])/.test(text.slice(keys.lastIndex, keys.lastIndex + 256))
553
+ ) continue
554
+ let start = keys.lastIndex
555
+ let depth = 0
556
+ while (text[start + depth] === "\\") depth++
557
+ const opener = text[start + depth]
558
+ const quote = isQuote(opener) ? opener! : undefined
559
+ let end: number
560
+ if (quote !== undefined) {
561
+ start += depth
562
+ const inner = stack[innermostString(stack)]
563
+ if (inner !== undefined) {
564
+ // Inside a string written with another quote character, every
565
+ // backslash is doubled again: `inspect` renders `"a\"b"` as
566
+ // `'"a\\"b"'`.
567
+ end = skipQuoted(text, start, depth, (inner.close === quote ? 1 : 2 * (inner.depth! + 1)) * 2 * (depth + 1))
568
+ } else {
569
+ // No enclosing string is visible: raw text, or a string `track` cannot
570
+ // see. Close no earlier than a doubled string would, but never past the
571
+ // next credential name: at the undoubled close when only separators
572
+ // precede that name (`"abc\\", password=`), else at the name.
573
+ const undoubled = skipQuoted(text, start, depth)
574
+ end = skipQuoted(text, start, depth, Math.max(4, 2 * (depth + 1)))
575
+ const next = nextName(text, undoubled, false)
576
+ if (next < end) end = /^[\s,;&]*$/.test(text.slice(undoubled, next)) ? undoubled : next
577
+ }
578
+ const closed = end - start > 1 && text[end - 1] === quote
579
+ if (!closed && !scope.diagnostic) end = Math.min(end, lineEnd(text, start))
580
+ // `util.inspect` continues a long string on the next line with `+`.
581
+ if (depth === 0) {
582
+ for (continuation.lastIndex = end; continuation.test(text); continuation.lastIndex = end) {
583
+ const piece = continuation.lastIndex
584
+ if (!isQuote(text[piece])) break
585
+ end = skipQuoted(text, piece, 0)
586
+ }
587
+ }
588
+ if (alreadyRedacted.test(text.slice(start + 1, end - (text[end - 1] === quote ? 1 + depth : 0)))) continue
589
+ } else {
590
+ end = bareValueEnd(text, start, scope, stack, budget)
591
+ end = userinfoEnd(text, start, end)
592
+ // In a journal row a placeholder then a space is a value an earlier pass
593
+ // already bounded: what follows it is the next part of the line,
594
+ // `{"statusCode":401}`. A diagnostic value runs over several words, so
595
+ // there the words after a placeholder are still the value.
596
+ const bounded = !scope.diagnostic && text.startsWith(placeholder, start) &&
597
+ /\s/.test(text[start + placeholder.length] ?? "")
598
+ const kept = end === start || bounded || alreadyRedacted.test(text.slice(start, end)) ||
599
+ (/tokens$/i.test(name) && /^\d+(?![\w.])/.test(text.slice(start, end))) ||
600
+ // A Bearer or Basic value the default rules already replaced keeps its scheme.
601
+ (scope.header && /^(?:bearer|basic)\s+\[REDACTED/i.test(text.slice(start, start + 24)))
602
+ if (kept) continue
603
+ }
604
+ const escape = quote === undefined ? "" : "\\".repeat(depth)
605
+ const closed = quote !== undefined && end - start > 1 && text[end - 1] === quote
606
+ output += text.slice(position, keys.lastIndex) + escape + (quote ?? "") + placeholder +
607
+ (closed ? escape + quote : "")
608
+ position = end
609
+ scanned = end
610
+ keys.lastIndex = end
611
+ }
612
+ return output + text.slice(position)
613
+ }
614
+
615
+ /**
616
+ * What separates a flag from its value: whitespace on a command line, or
617
+ * `", "` between two elements of a JSON or inspected array.
618
+ */
619
+ const argumentSeparator = String.raw`(?:\s+|["'\x60]\s*,\s*["'\x60])`
620
+
621
+ /** A credential flag and the separator before its value. */
622
+ const credentialFlag = new RegExp(
623
+ String.raw`(?<![A-Za-z0-9_-])(--?[A-Za-z0-9_-]*${credentialWord})${argumentSeparator}`,
624
+ "gi"
625
+ )
626
+
627
+ /** `-p` and the separator before its value, unless the value is a path or a long option. */
628
+ const shortPasswordFlag = new RegExp(
629
+ String.raw`(?<![^\s"'\x60,[(])-p${argumentSeparator}(?!(?:\.{0,2}|~)\/|--)`,
630
+ "g"
631
+ )
632
+
633
+ /**
634
+ * A flag that always takes a password, and the separator before it: `plink
635
+ * -pw`, openssl's `-pass`, `-passin` and `-passout` (`pass:secret`), `-passwd`.
636
+ */
637
+ const passwordFlag = new RegExp(
638
+ String.raw`(?<![^\s"'\x60,[(])-p(?:w|ass(?:in|out|wd)?)${argumentSeparator}`,
639
+ "g"
640
+ )
641
+
642
+ /** `-p` with a value attached, unless the word is a known single-dash option. */
643
+ const attachedPasswordFlag = new RegExp(
644
+ String
645
+ .raw`(?<![^\s"'\x60,[(])-p(?!(?:rint\w*|rune|erm|ath|threads?|edantic[\w-]*|ipe|ie|g|retty|lain|rogress|rofile|arents|reserve|ass(?:in|out|wd)?|w)(?![^\s"'\x60,\]]))(?=[^\s,\]])`,
646
+ "g"
647
+ )
648
+
649
+ /** `-u` or `--user` and the separator before its value, or `-u` with its value attached (`-uadmin:pw`). */
650
+ const userFlag = new RegExp(
651
+ String.raw`(?<![^\s"'\x60,[(])(?:(?:-u|--user)(?:=|${argumentSeparator})|-u(?=[^\s=-]))`,
652
+ "g"
653
+ )
654
+
655
+ /**
656
+ * A flag that takes a password only under one command, and the separator
657
+ * before its value: `zip -P` (a port to `ssh` and `mysql`) and `redis-cli -a`
658
+ * or `--pass`. The command is looked for at most 256 characters back on the
659
+ * same command line.
660
+ */
661
+ const commandPasswordFlag = new RegExp(
662
+ String
663
+ .raw`\b(?:(?:(?:un)?zip|zipcloak)\b[^\r\n|;&]{0,256}?[\s"'\x60,[(]-P|redis-cli\b[^\r\n|;&]{0,256}?[\s"'\x60,[(](?:-a|--pass))${argumentSeparator}`,
664
+ "g"
665
+ )
666
+
667
+ /**
668
+ * An HTTP header written as a name and value pair of an array
669
+ * (`[['Authorization', 'Token x']]`), the shape `Headers` entries and many
670
+ * clients log, up to the quote that opens the value.
671
+ */
672
+ const headerPair = /(?<![A-Za-z0-9_-])(?:(?:proxy-)?authorization|(?:set-)?cookies?)\\*["'`]\s*,\s*(?=\\*["'`])/gi
673
+
674
+ /** Redacts the quoted value of each {@link headerPair}, keeping its quotes. */
675
+ const redactHeaderPairs = (text: string): string => {
676
+ const pattern = new RegExp(headerPair.source, headerPair.flags)
677
+ let output = ""
678
+ let position = 0
679
+ for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
680
+ let depth = 0
681
+ while (text[pattern.lastIndex + depth] === "\\") depth++
682
+ const open = pattern.lastIndex + depth
683
+ const end = skipQuoted(text, open, depth)
684
+ const close = lastClosed ? end - 1 - depth : end
685
+ if (alreadyRedacted.test(text.slice(open + 1, close))) continue
686
+ output += text.slice(position, open + 1) + placeholder
687
+ position = close
688
+ pattern.lastIndex = end
689
+ }
690
+ return output + text.slice(position)
691
+ }
692
+
693
+ /** The placeholder alone, bare, quoted or escaped: a second pass leaves it alone. */
694
+ const redactedArgument = /^(?:\\*(["'`]))?\[REDACTED\](?:\\*\1)?$/
695
+
696
+ /**
697
+ * The end of the unquoted argument at `start`. It runs to whitespace or a
698
+ * quote, and on through a quoted part written against it (`abc'def'`, which a
699
+ * shell reads as one argument) when that part closes before any whitespace
700
+ * and holds none of `,:{}[]`. Any other quote ends it: the close of a string
701
+ * the command line sits in (`{"cmd":"mysql -p abc","next":1}`).
702
+ */
703
+ const wordEnd = (text: string, start: number): number => {
704
+ let end = start
705
+ while (end < text.length && !/\s/.test(text[end]!)) {
706
+ const quote = text[end]!
707
+ if (!isQuote(quote)) {
708
+ end++
709
+ continue
710
+ }
711
+ let close = end + 1
712
+ while (close < text.length && !/[\s"'`,:{}[\]]/.test(text[close]!)) close++
713
+ if (close === end + 1 || text[close] !== quote) break
714
+ end = close + 1
715
+ }
716
+ return end
717
+ }
718
+
719
+ /**
720
+ * Redacts the value after each flag `flags` matches: a quoted value, or one
721
+ * argv word, which ends at whitespace or a quote, so the same rule reads a
722
+ * command line joined by spaces, a JSON array and an inspected array. A comma
723
+ * or a `]` is part of a password on a command line (`-p abc,def`); in an
724
+ * array the element's closing quote ends it first.
725
+ */
726
+ const redactArguments = (
727
+ text: string,
728
+ flags: RegExp,
729
+ /** Whether this flag and value are a credential at all. */
730
+ accept?: (match: RegExpExecArray, value: string) => boolean
731
+ ): string => {
732
+ const pattern = new RegExp(flags.source, flags.flags)
733
+ let output = ""
734
+ let position = 0
735
+ for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
736
+ const start = pattern.lastIndex
737
+ let depth = 0
738
+ while (text[start + depth] === "\\") depth++
739
+ let end = start
740
+ if (isQuote(text[start + depth])) end = skipQuoted(text, start + depth, depth)
741
+ else end = wordEnd(text, start)
742
+ const value = text.slice(start, end)
743
+ if (end === start || redactedArgument.test(value) || accept?.(match, value) === false) continue
744
+ output += text.slice(position, start) + placeholder
745
+ position = end
746
+ pattern.lastIndex = end
747
+ }
748
+ return output + text.slice(position)
749
+ }
750
+
751
+ const durable: Scope = { header: false, diagnostic: false }
752
+
753
+ /**
754
+ * Best-effort textual rules for credential shapes observed in real reports.
755
+ * Every replacement reaches a fixed point so replaying or exporting an entry
756
+ * cannot mutate it again.
757
+ *
758
+ * @since 0.1.0
759
+ * @category constants
760
+ */
761
+ export const defaultRules: ReadonlyArray<Rule> = [
762
+ {
763
+ id: "private-key-block",
764
+ // Stop an unterminated block at the next header so repeated headers cannot
765
+ // each rescan the remaining input. A valid PEM body contains no headers.
766
+ // A block with no footer is a key a bound or a producer truncated, and its
767
+ // body is as secret as a whole one's, so it runs to the next header or to
768
+ // the end of the text. It runs first: a block inside URL userinfo, once
769
+ // replaced, is userinfo the URL rule then reads whole, so a second pass
770
+ // finds nothing left to change.
771
+ pattern:
772
+ /-----BEGIN[^-]*PRIVATE KEY(?: BLOCK)?-----(?:(?!-----BEGIN)[\s\S])*?(?:-----END[^-]*-----|(?=-----BEGIN)|$)/g
773
+ },
774
+ // Git HTTPS OAuth credentials place the secret in the username. Match
775
+ // before password rewriting removes the x-oauth-basic marker.
776
+ {
777
+ id: "git-oauth-userinfo",
778
+ pattern: /(https?:\/\/)[^\s/@:"'\\]+:x-oauth-basic@/gi,
779
+ replace: "$1[REDACTED]@"
780
+ },
781
+ {
782
+ id: "url-credentials",
783
+ // The scheme is bounded rather than open. `-` is not a word character, so
784
+ // `\b[a-z][a-z0-9+.-]*` starts a fresh scan after every hyphen, and on a
785
+ // long run of that shape the rule rescanned the tail from each one: 400 kB
786
+ // of `aaaaaaaa-` cost 11 seconds, on the path every journal write and every
787
+ // log line takes. A scheme longer than 30 characters is not one this net is
788
+ // for, and the cap makes each start position cost a constant.
789
+ //
790
+ // The username may be empty (`redis://:password@host`), and the password
791
+ // runs to the LAST `@` before the authority ends, as a URL parser reads
792
+ // it: RFC 3986 allows `:` in a password and a raw `@` is common in
793
+ // connection strings. Stopping at the first `:` or `@` left the tail of
794
+ // such a password in the row. Quotes and backslashes end the scan so a
795
+ // URL inside JSON text never swallows the next string.
796
+ pattern: /\b([a-z][a-z0-9+.-]{0,30}:\/\/[^\s:@/]*):(?!\[REDACTED\]@)[^\s/?#"'`\\]*@/gi,
797
+ replace: "$1:[REDACTED]@"
798
+ },
799
+ {
800
+ id: "bearer-token",
801
+ pattern: /\bBearer\s+[A-Za-z0-9._~+/-]{4,}=*/gi,
802
+ replace: "Bearer [REDACTED_TOKEN]"
803
+ },
804
+ {
805
+ id: "basic-authorization",
806
+ // HTTP schemes are case-insensitive. For prose spellings, require an
807
+ // encoded user:password pair so `a basic example` and module imports survive.
808
+ pattern: /\bbasic\s+[A-Za-z0-9+/]{4,}={0,2}/gi,
809
+ rewrite: (text) =>
810
+ text.replace(/\b(basic)\s+([A-Za-z0-9+/]{4,}={0,2})/gi, (match: string, scheme: string, token: string) => {
811
+ if (scheme === "Basic" || scheme === "BASIC") return "Basic [REDACTED_TOKEN]"
812
+ try {
813
+ return atob(token).includes(":") ? "Basic [REDACTED_TOKEN]" : match
814
+ } catch {
815
+ return match
816
+ }
817
+ })
818
+ },
819
+ {
820
+ id: "jwt",
821
+ // Check the three segments once per token before looking for a header.
822
+ // Starting at every `-eyJ` would rescan a malformed token's entire tail.
823
+ // Preserve any prefix so a JWT following a hyphen still gets redacted.
824
+ pattern:
825
+ /(?<![A-Za-z0-9_-])(?=[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-])([A-Za-z0-9_-]*?)\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
826
+ replace: "$1[REDACTED_TOKEN]"
827
+ },
828
+ {
829
+ id: "api-key",
830
+ // Not `\b`, for the reason the assignment rule below gives: an underscore
831
+ // is a word character, so `\bsk` never fires after `ANTHROPIC_` or after
832
+ // Effect's log-span sanitizer folds `token=` into `token_`. The lookbehind
833
+ // excludes only letters and digits, so a key still reads as a key when an
834
+ // underscore or a hyphen runs into it.
835
+ pattern: /(?<![A-Za-z0-9])(?:sk|pk)[-_][A-Za-z0-9][A-Za-z0-9_-]{7,}/g,
836
+ replace: "[REDACTED_API_KEY]"
837
+ },
838
+ {
839
+ id: "github-token",
840
+ pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}(?![A-Za-z0-9])/g,
841
+ replace: "[REDACTED]"
842
+ },
843
+ {
844
+ id: "github-fine-grained-token",
845
+ pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}(?![A-Za-z0-9_])/g,
846
+ replace: "[REDACTED]"
847
+ },
848
+ {
849
+ id: "aws-access-key",
850
+ pattern: /\bAKIA[0-9A-Z]{16}\b/g,
851
+ replace: "[REDACTED]"
852
+ },
853
+ {
854
+ id: "slack-token",
855
+ pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])/g,
856
+ replace: "[REDACTED]"
857
+ },
858
+ {
859
+ id: "google-api-key",
860
+ pattern: /\bAIza[0-9A-Za-z_-]{35,}(?![0-9A-Za-z_-])/g,
861
+ replace: "[REDACTED]"
862
+ },
863
+ {
864
+ id: "gitlab-token",
865
+ pattern: /\bglpat-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/g,
866
+ replace: "[REDACTED]"
867
+ },
868
+ {
869
+ id: "npm-token",
870
+ pattern: /\bnpm_[A-Za-z0-9]{36}(?![A-Za-z0-9])/g,
871
+ replace: "[REDACTED]"
872
+ },
873
+ {
874
+ // The webhook path is the whole credential: anyone holding it can post
875
+ // to the channel. The host stays so a failed delivery is still readable.
876
+ id: "slack-webhook",
877
+ pattern: /(\bhooks\.slack\.com\/services\/)T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g,
878
+ replace: "$1[REDACTED]"
879
+ },
880
+ {
881
+ id: "assignment",
882
+ // A credential name, `:`, `=` or `=>`, and its whole value: quoted at any
883
+ // escape depth, a container, or several bare words. See `redactValues`.
884
+ pattern: credentialNames,
885
+ rewrite: (text) => redactValues(text, credentialNames, durable)
886
+ },
887
+ {
888
+ id: "credential-flag",
889
+ // `--password hunter2`, `--api-key "a b"`, or the same pair as two argv
890
+ // elements. `--token=x` is an assignment above; this is the spelling a
891
+ // command line separates with a space. The next word is the value even
892
+ // when it starts with `-`: a credential flag always takes one.
893
+ pattern: credentialFlag,
894
+ rewrite: (text) =>
895
+ redactArguments(text, credentialFlag, (match, value) => namesCredential(match[1]!.replace(/^-+/, ""), value))
896
+ },
897
+ {
898
+ id: "cookie-session-assignment",
899
+ pattern:
900
+ /(?<![A-Za-z0-9-])((?:COOKIE|SESSION)S?)(\s*=\s*)(?!\[REDACTED\])("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|(?!["'])[^\s;,]+)/gi,
901
+ replace: "$1$2[REDACTED]"
902
+ }
903
+ ]
904
+
905
+ /**
906
+ * The rules for a diagnostic: {@link defaultRules} and the spellings too broad
907
+ * for a durable row.
908
+ *
909
+ * A log line, a stderr message, and an error handed to a remote caller are
910
+ * read once, so a false positive costs a word of context. A journal row is
911
+ * permanent, so the same false positive destroys data. These rules sit on the
912
+ * diagnostic side of that line: an authorization header in any scheme, bare
913
+ * URL userinfo (`https://token@host`), a signed query parameter, and the value
914
+ * of a `-p` flag, which is a password to `mysql` and `sshpass` and a path to
915
+ * `mkdir`. A path, a port and a lowercase word attached to `-p` (`-print`,
916
+ * `-path`) are left alone.
917
+ *
918
+ * @since 1.0.0
919
+ * @category constants
920
+ */
921
+ export const diagnosticRules: ReadonlyArray<Rule> = [
922
+ ...defaultRules.map((rule): Rule =>
923
+ rule.id === "assignment"
924
+ ? {
925
+ id: "assignment",
926
+ pattern: diagnosticNames,
927
+ rewrite: (text) => redactValues(text, diagnosticNames, { header: false, diagnostic: true })
928
+ }
929
+ : rule
930
+ ),
931
+ {
932
+ id: "authorization-header",
933
+ // The header value is a credential whatever its scheme (`Token`, a cookie
934
+ // list, `Digest` with quoted parameters), so the value runs to the end of
935
+ // its line or the close of the string it was written in.
936
+ // A lookbehind-free superset lets the compiled prefilter skip ordinary prose.
937
+ pattern: /(?:proxy-)?authorization|(?:set-)?cookies?/gi,
938
+ rewrite: (text) => redactValues(text, diagnosticHeaderNames, { header: true, diagnostic: true })
939
+ },
940
+ {
941
+ id: "bearer-or-basic",
942
+ // A token shorter than the default rules' minimum. A lowercase `basic` is
943
+ // prose ("a basic example"), so only the scheme's own spellings count.
944
+ pattern: /(\b(?:[Bb]earer|BEARER|Basic|BASIC)\s+)(?!\[REDACTED)[^\s,;"'\\]+/g,
945
+ replace: "$1[REDACTED]"
946
+ },
947
+ {
948
+ id: "password-flag",
949
+ // The whole next argument, a path or a leading `-` included.
950
+ pattern: passwordFlag,
951
+ rewrite: (text) => redactArguments(text, passwordFlag)
952
+ },
953
+ {
954
+ id: "sshpass-password",
955
+ // `sshpass -p` always takes a value, even one that starts with `--`,
956
+ // which `mysql -p --database x` reads as the next option.
957
+ pattern: /(\bsshpass(?:\s+-[^\sp]\S*){0,8}\s+-p\s+)--(?!\[REDACTED\])[^\s"'`]*/g,
958
+ replace: "$1[REDACTED]"
959
+ },
960
+ {
961
+ id: "user-flag",
962
+ // `curl -u user:pass`, `--user=user:pass`, quoted or not: the whole
963
+ // argument, commas included, when it carries a `:`.
964
+ pattern: userFlag,
965
+ rewrite: (text) => redactArguments(text, userFlag, (_match, value) => value.includes(":"))
966
+ },
967
+ {
968
+ id: "header-pair",
969
+ pattern: headerPair,
970
+ rewrite: redactHeaderPairs
971
+ },
972
+ {
973
+ id: "command-password-flag",
974
+ // The whole next argument, whatever it starts with.
975
+ pattern: commandPasswordFlag,
976
+ rewrite: (text) => redactArguments(text, commandPasswordFlag)
977
+ },
978
+ {
979
+ id: "url-userinfo",
980
+ pattern: /(\/\/)(?!\[REDACTED\]@)(?![^/@\s"'\\]*:\[REDACTED\]@)[^/@\s"'\\]+@/g,
981
+ replace: "$1[REDACTED]@"
982
+ },
983
+ {
984
+ id: "signed-query",
985
+ pattern: /([?&][\w.-]*(?:key|sig|signature|auth|credential)=)(?!\[REDACTED\])[^&#\s"'\\]+/gi,
986
+ replace: "$1[REDACTED]"
987
+ },
988
+ {
989
+ id: "short-password-flag",
990
+ // A path is kept, and so is a flag: `mysql -p --database x` prompts for
991
+ // the password rather than taking one.
992
+ pattern: shortPasswordFlag,
993
+ rewrite: (text) => redactArguments(text, shortPasswordFlag)
994
+ },
995
+ {
996
+ id: "attached-password-flag",
997
+ // `-psecret`. The single-dash words that start with `p` and are not a
998
+ // password, `find -print` and the compilers' `-pthread` among them, are kept.
999
+ pattern: attachedPasswordFlag,
1000
+ rewrite: (text) => redactArguments(text, attachedPasswordFlag)
1001
+ }
1002
+ ]
1003
+
1004
+ /**
1005
+ * Redacts one diagnostic value with {@link diagnosticRules}: a log line, a
1006
+ * stderr message, an error handed back to a caller.
1007
+ *
1008
+ * Every diagnostic path shares this one function, and it runs on the value
1009
+ * before anything renders or bounds it. Redacting a rendering line by line, or
1010
+ * after a bound, is how a secret escaped: `util.inspect` splits a long string
1011
+ * over several lines, and a bound cuts a quoted value before its closing
1012
+ * quote. A value past {@link maxDepth} is named rather than thrown.
1013
+ *
1014
+ * @since 1.0.0
1015
+ * @category redaction
1016
+ */
1017
+ export const redactDiagnostic = (value: unknown): unknown =>
1018
+ redact(value, { rules: diagnosticRules, onTooDeep: "name" })
1019
+
1020
+ /**
1021
+ * Credential names this module refuses to persist, matched as suffixes of the
1022
+ * separator-free lowercase form of a key.
1023
+ *
1024
+ * The list is the union of the names `packages/smithers/src/Bug.ts` redacts
1025
+ * structurally, because the journal is the PERMANENT side of that pair: a bug
1026
+ * report is one upload an operator reviews before it leaves the machine, while
1027
+ * `flows_journal_events.payload_json` is replayed verbatim to every sync
1028
+ * subscriber and time-travel consumer forever. The journal redacting less than
1029
+ * the report inverts the risk, and it did: `credential`, `credentials`, `dsn`,
1030
+ * and `connectionString` all round-tripped through a durable row in clear.
1031
+ *
1032
+ * Two families are spelled out rather than reduced to a shorter word, because
1033
+ * these are SUFFIX tests: `connectionString` does not end in `connection`, and
1034
+ * `secretKey` does not end in `secret`. A bare `key` suffix is not on the list
1035
+ * for the opposite reason: it would redact `monkey` and `turkey`.
1036
+ *
1037
+ * `signature` stays, and a field it costs is renamed rather than excused. A
1038
+ * name test cannot tell a MAC computed with a secret from a digest over public
1039
+ * input, and both are called `signature`: `WorkspaceShare` signs its claims
1040
+ * with `ShareSigner.signHmac` and that value IS the share's authorization,
1041
+ * `GrantStore` carries envelope signatures, and the GitHub, Linear and
1042
+ * Telegram webhook readers all verify a header by that name. Against those, a
1043
+ * digest whose whole purpose is to be reconciled costs nothing to rename and
1044
+ * everything to leave unreadable -- see
1045
+ * `AgentEvent.VacuousVerificationObserved.callDigest`, which was `signature`
1046
+ * and reached durable rows as the placeholder.
1047
+ */
1048
+ const sensitiveKeySuffixes = [
1049
+ "auth",
1050
+ "authorization",
1051
+ "cookie",
1052
+ "apikey",
1053
+ "token",
1054
+ "password",
1055
+ "passphrase",
1056
+ "secret",
1057
+ "secretaccesskey",
1058
+ "credential",
1059
+ "dsn",
1060
+ "connection",
1061
+ "connectionstring",
1062
+ "connectionuri",
1063
+ "connectionurl",
1064
+ "secretkey",
1065
+ "privatekey",
1066
+ "sshkey",
1067
+ "signingkey",
1068
+ "signature",
1069
+ "encryptionkey",
1070
+ "session",
1071
+ "sessionkey"
1072
+ ]
1073
+
1074
+ /**
1075
+ * A trailing `key` that is a word of its own.
1076
+ *
1077
+ * Read against the ORIGINAL key, where the separators that make `key` a word
1078
+ * still exist: `key`, `api_key`, `x-api-key`, `signing-key`. This is the shape
1079
+ * `packages/smithers/src/Bug.ts` matches, and stopping here is deliberate. Treating
1080
+ * a camel-case hump as a separator too, `/[a-z0-9]Key$/`, looks equivalent and
1081
+ * is not: it redacted `idempotencyKey`, the durable identity an effect boundary
1082
+ * replays on, out of `@smthrs/engine-store`'s journal rows. A credential-named
1083
+ * key is covered by {@link sensitiveKeySuffixes} instead, where the word before
1084
+ * `key` has to be one that names a secret.
1085
+ */
1086
+ const trailingKeyWord = /(?:^|[^A-Za-z0-9])key$/i
1087
+
1088
+ const canonicalKey = (key: string): string => key.toLowerCase().replace(/[^a-z0-9]/g, "").replace(/s$/, "")
1089
+
1090
+ /** Numeric accounting fields that contain counts, never bearer material. */
1091
+ const tokenCounterKeys: ReadonlySet<string> = new Set([
1092
+ "inputtoken",
1093
+ "outputtoken",
1094
+ "cachedinputtoken",
1095
+ "reasoningtoken",
1096
+ "totaltoken"
1097
+ ])
1098
+
1099
+ /**
1100
+ * Any name ending in a plural `tokens` holds a count too, the rule the textual
1101
+ * pass applies in {@link namesCredential}: `Envelope.budget.tokens` is the
1102
+ * run's token ceiling, and `usage.cacheWriteTokens`, `maxTokens`, and
1103
+ * `contextWindowTokens` are accounting; redacting them erased every journaled
1104
+ * budget and cache-write count (#3846). A bare singular `token` stays bearer
1105
+ * material even when it is numeric.
1106
+ */
1107
+ const isTokenCount = (key: string, value: unknown): boolean =>
1108
+ typeof value === "number" && Number.isSafeInteger(value) && value >= 0 &&
1109
+ (tokenCounterKeys.has(canonicalKey(key)) || /tokens$/i.test(key))
1110
+
1111
+ /**
1112
+ * Whether a field name names a credential.
1113
+ *
1114
+ * Case and separators are ignored, so `api_key`, `apiKey`, and `x-api-key` are
1115
+ * all recognised, one trailing plural `s` is stripped so `credentials` reads as
1116
+ * `credential`, and a trailing `key` counts where it is a word of its own or
1117
+ * where the word before it names a secret.
1118
+ *
1119
+ * The rule is a suffix test, not a substring test. `tokenizer`, `secretary`,
1120
+ * `monkey`, and `idempotencyKey` are ordinary field names, and replacing their
1121
+ * values would destroy data in a permanent row without protecting anything.
1122
+ * That is the one place this rule is deliberately narrower than
1123
+ * `packages/smithers/src/Bug.ts`'s substring form, which can afford the false
1124
+ * positives because its output is a single report an operator reads once.
1125
+ *
1126
+ * @since 0.1.0
1127
+ * @category predicates
1128
+ */
1129
+ export const isSensitiveKey = (key: string): boolean => {
1130
+ if (trailingKeyWord.test(key)) return true
1131
+ const canonical = canonicalKey(key)
1132
+ return sensitiveKeySuffixes.some((suffix) => canonical.endsWith(suffix))
1133
+ }
1134
+
1135
+ const redactMember = (
1136
+ key: string,
1137
+ value: unknown,
1138
+ walk: (value: unknown) => unknown
1139
+ ): unknown => isSensitiveKey(key) && !isTokenCount(key, value) ? placeholder : walk(value)
1140
+
1141
+ /**
1142
+ * A field name with a credential in it replaced outright, not rewritten in place.
1143
+ *
1144
+ * Redacting part of a key changes what the key reads as. `secret=sk-` rewrites
1145
+ * to `secret=[REDACTED]`, which now ENDS in a sensitive name, so a second
1146
+ * application would replace a value the first one left alone and redaction
1147
+ * would stop being a fixed point. Naming the whole key holds the verdict still:
1148
+ * `[REDACTED]` matches no rule and names no credential. Two such keys collapse
1149
+ * into one and the later member wins, which is the fidelity trade every other
1150
+ * marker here makes.
1151
+ */
1152
+ const redactKey = (key: string, rules: ReadonlyArray<Rule>): string => {
1153
+ const redacted = redactString(key, rules)
1154
+ return redacted === key ? key : placeholder
1155
+ }
1156
+
1157
+ /**
1158
+ * How many times {@link redactString} re-applies the rules to reach a fixed
1159
+ * point. Rules feed each other: an assignment redacted inside URL userinfo
1160
+ * leaves userinfo the URL rule only then matches. Text no rule touches costs
1161
+ * one pass, and the default rules settle within three. Text that has not
1162
+ * settled after the last pass is replaced whole.
1163
+ */
1164
+ const fixedPointPasses = 8
1165
+
1166
+ /**
1167
+ * A copy of `pattern` that matches wherever `pattern` does, with no
1168
+ * lookbehind, or `null`. JavaScriptCore runs a pattern that has a lookbehind
1169
+ * in its interpreter, 30 to 70 times slower than compiled: 40 kB of prose cost
1170
+ * a Bun process 300 ms per diagnostic, where Node took 1 ms. Text the copy
1171
+ * never matches is text the rule cannot change, so the rule is skipped.
1172
+ *
1173
+ * Only a one-character negative lookbehind that starts the pattern is
1174
+ * rewritten, as a character the copy consumes, which keeps a name scan
1175
+ * starting once per identifier. Anywhere else, after `\b` or inside a
1176
+ * repeated group, the consumed character would make the copy stricter than
1177
+ * the rule, so any other lookbehind or a backreference leaves the rule
1178
+ * unfiltered.
1179
+ */
1180
+ const candidate = (pattern: RegExp): RegExp | null => {
1181
+ const cached = candidates.get(pattern)
1182
+ if (cached !== undefined) return cached
1183
+ const leading = /^\(\?<!\[(\^?)((?:\\.|[^\]\\])*)\]\)/.exec(pattern.source)
1184
+ const rest = leading === null ? pattern.source : pattern.source.slice(leading[0].length)
1185
+ const compiled = /\(\?<[!=]|\\(?:[1-9]|k<)/.test(rest)
1186
+ ? null
1187
+ : new RegExp(
1188
+ leading === null ? rest : `(?:^|[${leading[1] === "" ? "^" : ""}${leading[2]}])${rest}`,
1189
+ pattern.flags.replace(/[gy]/g, "")
1190
+ )
1191
+ candidates.set(pattern, compiled)
1192
+ return compiled
1193
+ }
1194
+
1195
+ const candidates = new WeakMap<RegExp, RegExp | null>()
1196
+
1197
+ const applyRule = (text: string, rule: Rule): string => {
1198
+ if (candidate(rule.pattern)?.test(text) === false) return text
1199
+ return rule.rewrite === undefined ? text.replace(rule.pattern, rule.replace ?? placeholder) : rule.rewrite(text)
1200
+ }
1201
+
1202
+ const redactString = (value: string, rules: ReadonlyArray<Rule>): string => {
1203
+ let text = value
1204
+ for (let pass = 0; pass < fixedPointPasses; pass++) {
1205
+ const next = rules.reduce(applyRule, text)
1206
+ if (next === text) return text
1207
+ text = next
1208
+ }
1209
+ // Rules that never settle would let an exported row keep changing, and
1210
+ // what they left may still hold a credential. Fail closed.
1211
+ return placeholder
1212
+ }
1213
+
1214
+ /**
1215
+ * Maximum number of container edges traversed from a redaction root.
1216
+ *
1217
+ * Journal event schemas never approach 256 nested containers. This bound is
1218
+ * far above practical payloads while keeping traversal safely below Node's
1219
+ * call-stack limit for hostile input.
1220
+ *
1221
+ * @since 1.0.0
1222
+ * @category constants
1223
+ */
1224
+ export const maxDepth = 256
1225
+
1226
+ /**
1227
+ * A payload nested deeper than {@link maxDepth}, under `onTooDeep: "throw"`.
1228
+ * `code` is always `depth_exceeded`; `maxDepth` is the bound that was crossed.
1229
+ *
1230
+ * @since 1.0.0
1231
+ * @category errors
1232
+ */
1233
+ export class RedactionDepthError extends Schema.TaggedError<RedactionDepthError>()(
1234
+ "@smthrs/journal/RedactionDepthError",
1235
+ { code: Schema.Literal("depth_exceeded"), maxDepth: Schema.Number, message: Schema.String }
1236
+ ) {
1237
+ override readonly name = "RedactionDepthError"
1238
+ }
1239
+
1240
+ /**
1241
+ * Options for {@link redact}.
1242
+ *
1243
+ * @since 0.1.0
1244
+ * @category models
1245
+ */
1246
+ export interface Options {
1247
+ readonly rules?: ReadonlyArray<Rule> | undefined
1248
+ /**
1249
+ * What a value nested past {@link maxDepth} does.
1250
+ *
1251
+ * `"throw"`, the default, is the journal's contract: a payload that deep is a
1252
+ * caller bug, and a durable row quietly truncated to a marker is worse than a
1253
+ * refused write. `"name"` is what a LOGGER wants, because a throw there is
1254
+ * caught one frame up and replaces EVERY argument on the line with
1255
+ * `[Unrenderable]`, so one deep member would cost the operator the whole line.
1256
+ */
1257
+ readonly onTooDeep?: "throw" | "name" | undefined
1258
+ }
1259
+
1260
+ /**
1261
+ * How many bytes a view may hold, and how many own members {@link redact} reads
1262
+ * off it, before it stops reading them.
1263
+ *
1264
+ * Enumerating a view's own properties materialises one pair per byte, so the
1265
+ * walk costs the buffer's size even though the rendering does not. Both halves
1266
+ * of the bound carry load, and neither is a bound on its own. A size alone is
1267
+ * not, because `byteLength` was read as an ordinary property and an ordinary
1268
+ * property can be shadowed: a pooled chunk that reports the bytes it has used
1269
+ * rather than the bytes it holds is a plain pattern, not an adversarial one,
1270
+ * and a 4 MB chunk reporting 12 walked one property per byte anyway. A count
1271
+ * alone is not, because a caller can hang a million properties on a ten-byte
1272
+ * view. So the size is read from the value's own internal slot, where nothing
1273
+ * a caller writes can answer for it, and the members are counted as they are
1274
+ * walked.
1275
+ *
1276
+ * @since 0.1.0
1277
+ * @category redaction
1278
+ */
1279
+ export const binaryWalkLimit = 65_536
1280
+
1281
+ /**
1282
+ * The byte-length getters, taken from the prototypes rather than from a value.
1283
+ *
1284
+ * `%TypedArray%.prototype`, `DataView.prototype` and `ArrayBuffer.prototype`
1285
+ * each define `byteLength` as an accessor over an internal slot, and applying
1286
+ * one to a value that has no such slot throws. Reading the size this way is
1287
+ * therefore a brand check as well as a measurement: a caller's own `byteLength`
1288
+ * property, accessor or not, never answers it.
1289
+ */
1290
+ const byteLengthGetters = [
1291
+ Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype) as object, "byteLength")!.get!,
1292
+ Object.getOwnPropertyDescriptor(DataView.prototype, "byteLength")!.get!,
1293
+ Object.getOwnPropertyDescriptor(ArrayBuffer.prototype, "byteLength")!.get!
1294
+ ] as ReadonlyArray<() => number>
1295
+
1296
+ /** A value's byte length from its own internal slot, or `undefined` when it has none. */
1297
+ const byteLength = (node: object): number | undefined => {
1298
+ for (const getter of byteLengthGetters) {
1299
+ try {
1300
+ return Reflect.apply(getter, node, [])
1301
+ } catch {
1302
+ // Not that kind of view. Another getter answers, or none does and the
1303
+ // bytes are named without the members being read.
1304
+ }
1305
+ }
1306
+ return undefined
1307
+ }
1308
+
1309
+ /** The prototypes every binary view inherits from. */
1310
+ const binaryPrototypes: ReadonlySet<unknown> = new Set([
1311
+ Object.getPrototypeOf(Uint8Array.prototype),
1312
+ DataView.prototype,
1313
+ ArrayBuffer.prototype
1314
+ ])
1315
+
1316
+ /** How many prototypes {@link isBinary} climbs before it stops asking. */
1317
+ const prototypeWalkLimit = 64
1318
+
1319
+ /**
1320
+ * Whether `node` is a binary view, including one held behind a proxy.
1321
+ *
1322
+ * `ArrayBuffer.isView` reads an internal slot, and a proxy has none of its own,
1323
+ * so it answers `false` for a proxy over a view. That sent a proxied 2 MB
1324
+ * buffer to the object branch, which rebuilt it one key per byte: 2,000 ms and
1325
+ * 22.9 million characters for one logged value. A proxy forwards
1326
+ * `getPrototypeOf` to its target, so the prototype chain answers where the
1327
+ * brand check cannot. The climb is capped because a proxy is free to hand back
1328
+ * a fresh object every time it is asked, which is an endless chain.
1329
+ */
1330
+ const isBinary = (node: object): boolean => {
1331
+ if (ArrayBuffer.isView(node) || node instanceof ArrayBuffer) return true
1332
+ try {
1333
+ let prototype = Object.getPrototypeOf(node) as object | null
1334
+ for (let step = 0; prototype !== null && step < prototypeWalkLimit; step++) {
1335
+ if (binaryPrototypes.has(prototype)) return true
1336
+ prototype = Object.getPrototypeOf(prototype) as object | null
1337
+ }
1338
+ } catch {
1339
+ // A revoked proxy refuses to be asked. It is not a view, and the object
1340
+ // branch names it.
1341
+ }
1342
+ return false
1343
+ }
1344
+
1345
+ /** Own keys of a binary view that name one of its bytes rather than a property. */
1346
+ const indexKey = /^(?:0|[1-9][0-9]*)$/
1347
+
1348
+ /** `Uint8Array 1024 bytes`, or the bare marker when the value will not say. */
1349
+ const describeBinary = (node: object, size: number | undefined): string => {
1350
+ if (size === undefined) return binaryMarker
1351
+ try {
1352
+ return `${node.constructor.name} ${size} bytes`
1353
+ } catch {
1354
+ return binaryMarker
1355
+ }
1356
+ }
1357
+
1358
+ /**
1359
+ * The key {@link redact} files a binary view's size under.
1360
+ *
1361
+ * @since 0.1.0
1362
+ * @category redaction
1363
+ */
1364
+ export const binaryMarker = "[Binary]"
1365
+
1366
+ /**
1367
+ * What {@link redact} writes in place of a function or a class object.
1368
+ *
1369
+ * @since 0.1.0
1370
+ * @category redaction
1371
+ */
1372
+ export const functionMarker = "[Function]"
1373
+
1374
+ /**
1375
+ * What {@link redact} writes in place of a symbol.
1376
+ *
1377
+ * @since 0.1.0
1378
+ * @category redaction
1379
+ */
1380
+ export const symbolMarker = "[Symbol]"
1381
+
1382
+ /**
1383
+ * What {@link redact} writes past {@link maxDepth} under `onTooDeep: "name"`.
1384
+ *
1385
+ * @since 0.1.0
1386
+ * @category redaction
1387
+ */
1388
+ export const depthMarker = "[Deep]"
1389
+
1390
+ /**
1391
+ * Returns `value` with credentials removed.
1392
+ *
1393
+ * Objects and arrays are rebuilt: a field whose name {@link isSensitiveKey}
1394
+ * is replaced wholesale, every other string is run through the textual rules,
1395
+ * and a cycle is collapsed to `"[Circular]"` so the result always encodes.
1396
+ * A number, a boolean, `null` and `undefined` are returned untouched, because
1397
+ * redacting one destroys data without protecting anything. A function and a
1398
+ * symbol are NAMED, {@link functionMarker} and {@link symbolMarker}: a body, an
1399
+ * own property and a description are all text a renderer prints, and none of it
1400
+ * can be rewritten in place.
1401
+ *
1402
+ * Traversal accepts at most {@link maxDepth} container edges. A deeper value
1403
+ * throws by default, so the journal boundary can report a typed `invalid_event`
1404
+ * instead of overflowing the runtime stack. {@link Options.onTooDeep} set to
1405
+ * `"name"` writes {@link depthMarker} in its place instead, which is what a
1406
+ * logger wants.
1407
+ *
1408
+ * @since 0.1.0
1409
+ * @category redaction
1410
+ */
1411
+ export const redact = (value: unknown, options?: Options): unknown => {
1412
+ const onTooDeep = options?.onTooDeep ?? "throw"
1413
+ const rules = globalRules(options?.rules ?? defaultRules)
1414
+ /**
1415
+ * A binary view named by its type and size, with its own properties walked.
1416
+ *
1417
+ * Its bytes are not text the rules can read, and rebuilding it from its
1418
+ * entries wrote one key per byte: a 100 kB buffer rendered 1.4 MB. Handing
1419
+ * the view back untouched is not the answer either, because `redact` is the
1420
+ * journal's own write path, so a caller's `apiKey` property hung on a buffer
1421
+ * went into a durable row in clear. Name the bytes, keep walking the text.
1422
+ */
1423
+ const binary = (node: object, ancestors: WeakSet<object>, depth: number): unknown => {
1424
+ const size = byteLength(node)
1425
+ // The description is text read off the value, so it meets the rules like
1426
+ // any other text: a class name is caller data, and a view whose
1427
+ // constructor is named after a credential wrote it into a durable row.
1428
+ const entries: Array<[string, unknown]> = [[binaryMarker, redactString(describeBinary(node, size), rules)]]
1429
+ // `Object.entries` on a view materialises one pair per byte before the
1430
+ // index filter can discard them, which cost 312 ms for 1 MB on the journal
1431
+ // write path. Past the bound the bytes are named and nothing else is read,
1432
+ // so a member a caller hung on a large view is dropped rather than shown.
1433
+ // A value that will not answer from its internal slot, such as a proxy over
1434
+ // a view, is named and never enumerated at all.
1435
+ if (size !== undefined && size <= binaryWalkLimit) {
1436
+ let walked = 0
1437
+ for (const [key, field] of Object.entries(node as Record<string, unknown>)) {
1438
+ // An index is one of the bytes just named, not a property a caller set.
1439
+ if (indexKey.test(key)) continue
1440
+ // The size bounds the bytes, not the properties: a caller can hang a
1441
+ // million members on a ten-byte view, and each one costs three rule
1442
+ // scans over its name and a walk of its value.
1443
+ if (walked >= binaryWalkLimit) break
1444
+ walked++
1445
+ entries.push([
1446
+ redactKey(key, rules),
1447
+ redactMember(key, field, (value) => walk(value, ancestors, depth + 1, key))
1448
+ ])
1449
+ }
1450
+ }
1451
+ // `Object.fromEntries`, not `named[key] = …`, for the reason the object
1452
+ // branch below gives: a literal `__proto__` key would route through the
1453
+ // inherited setter and the member would vanish from the row.
1454
+ return Object.fromEntries(entries)
1455
+ }
1456
+
1457
+ const walk = (node: unknown, ancestors: WeakSet<object>, depth: number, key: string): unknown => {
1458
+ if (depth > maxDepth) {
1459
+ if (onTooDeep === "name") return depthMarker
1460
+ throw new RedactionDepthError({
1461
+ code: "depth_exceeded",
1462
+ maxDepth,
1463
+ message: `redaction depth exceeds ${maxDepth}`
1464
+ })
1465
+ }
1466
+ if (typeof node === "string") return redactString(node, rules)
1467
+ // A function, a class object or a symbol carries text a walk never reaches
1468
+ // (own properties, a description, a body), and the renderer prints it. None
1469
+ // of it can be redacted in place, so the value is named instead.
1470
+ if (typeof node === "function") return functionMarker
1471
+ if (typeof node === "symbol") return symbolMarker
1472
+ if (node === null || typeof node !== "object") return node
1473
+ if (isBinary(node)) return binary(node, ancestors, depth)
1474
+ if (ancestors.has(node)) return "[Circular]"
1475
+ // A journal row is bounded by its schema, but a LOGGED value is arbitrary:
1476
+ // the logger sends every non-Error value here, and a chain deep enough to
1477
+ // exhaust the stack would throw while the line is rendering, killing the
1478
+ // run the line describes. Past the cap the value is named, the way a cycle
1479
+ // is named.
1480
+ ancestors.add(node)
1481
+ try {
1482
+ const toJSON = (node as { toJSON?: unknown }).toJSON
1483
+ // JSON.stringify passes the containing key (or "" at the root) to toJSON.
1484
+ // Reuse it when walking the replacement; siblings may share this object.
1485
+ if (typeof toJSON === "function") return walk(toJSON.call(node, key), ancestors, depth, key)
1486
+ if (Array.isArray(node)) {
1487
+ // `map` invokes the input's species constructor, which can restore
1488
+ // credential fields and inspection hooks after the elements are walked.
1489
+ // Rebuild a plain array, preserving the original length and holes.
1490
+ const length = node.length
1491
+ const result = new Array<unknown>(length)
1492
+ const elements = new Array<unknown>(length)
1493
+ for (let index = 0; index < length; index++) {
1494
+ if (!(index in node)) continue
1495
+ elements[index] = node[index]
1496
+ result[index] = walk(elements[index], ancestors, depth + 1, String(index))
1497
+ }
1498
+ // An argv keeps a flag and its value in two elements, so no rule sees
1499
+ // `--password hunter2` whole. The element after a flag is a credential
1500
+ // when its name says so (`--token=x` carries its own, and a count under
1501
+ // `--max-tokens` is kept), or when the active rules redact it read
1502
+ // after the flag and the elements before it (`-p`, `-pw`, `-passin`,
1503
+ // `sshpass -p`) differently than alone.
1504
+ for (let index = 0; index + 1 < length; index++) {
1505
+ // The values the first loop read, never a second read: a proxy may
1506
+ // answer a second `get` differently.
1507
+ const flag = elements[index]
1508
+ const value = elements[index + 1]
1509
+ if (typeof flag !== "string" || typeof value !== "string" || !/^-[^=\s]+$/.test(flag)) continue
1510
+ const name = flag.replace(/^-+/, "")
1511
+ const before = elements.slice(Math.max(0, index - 3), index + 1).filter((element) =>
1512
+ typeof element === "string"
1513
+ ).join(" ")
1514
+ const consumes = (isSensitiveKey(name) && namesCredential(name, value)) ||
1515
+ redactString(`${before} ${value}`, rules) !== `${redactString(before, rules)} ${redactString(value, rules)}`
1516
+ if (consumes) result[index + 1] = placeholder
1517
+ }
1518
+ return result
1519
+ }
1520
+ // `result[key] = …` routes a literal `__proto__` key through the
1521
+ // inherited setter, so the field would silently become the result's
1522
+ // prototype instead of a member: the payload loses data and redaction
1523
+ // stops being a fixed point. `Object.fromEntries` defines own data
1524
+ // properties and has no such hole.
1525
+ return Object.fromEntries(
1526
+ Object.entries(node as Record<string, unknown>).map((
1527
+ [key, field]
1528
+ ) => [
1529
+ // The KEY is text too. Rewriting only values let a credential used as
1530
+ // a log annotation key reach the operator, since Effect renders an
1531
+ // annotation as `key=value`, and become an OTLP span attribute name.
1532
+ redactKey(key, rules),
1533
+ redactMember(key, field, (value) => walk(value, ancestors, depth + 1, key))
1534
+ ])
1535
+ )
1536
+ } finally {
1537
+ ancestors.delete(node)
1538
+ }
1539
+ }
1540
+ return walk(value, new WeakSet(), 0, "")
1541
+ }
1542
+
1543
+ /**
1544
+ * A redaction function, as the journal consumes it.
1545
+ *
1546
+ * @since 0.1.0
1547
+ * @category models
1548
+ */
1549
+ export type Redactor = (value: unknown) => unknown
1550
+
1551
+ /**
1552
+ * Builds a redactor over a rule set.
1553
+ *
1554
+ * @since 0.1.0
1555
+ * @category constructors
1556
+ */
1557
+ export const make = (options?: Options): Redactor => (value) => redact(value, options)
1558
+
1559
+ /**
1560
+ * Applies a redactor to an already-encoded JSON string, returning the
1561
+ * re-encoded result.
1562
+ *
1563
+ * For export and display surfaces that hold a column verbatim, a rendered
1564
+ * `state_json`, a support bundle, where the value is already encoded and must
1565
+ * not be decoded into the executable path. A string that does not parse is
1566
+ * returned untouched: validation is the caller's, and rejecting here would
1567
+ * turn a redaction concern into a schema error. Once parsing succeeds, a
1568
+ * throwing redactor or an encoding failure returns the valid JSON string
1569
+ * `"[REDACTED]"`; the original parsed text is never returned.
1570
+ *
1571
+ * @since 0.1.0
1572
+ * @category redaction
1573
+ */
1574
+ export const redactJsonString = (json: string, redactor: Redactor): string => {
1575
+ const decoded = Schema.decodeUnknownResult(UnknownFromJsonString)(json)
1576
+ if (Result.isFailure(decoded)) return json
1577
+ const attempted = Result.try(() => Schema.encodeUnknownResult(UnknownFromJsonString)(redactor(decoded.success)))
1578
+ if (Result.isFailure(attempted)) return JSON.stringify(placeholder)
1579
+ return Result.isSuccess(attempted.success) ? attempted.success.success : JSON.stringify(placeholder)
1580
+ }
1581
+
1582
+ /**
1583
+ * Redacts a stream one line at a time.
1584
+ *
1585
+ * @since 1.0.0
1586
+ * @category models
1587
+ */
1588
+ export interface LineRedactor {
1589
+ /**
1590
+ * Takes the rest of the current line, without its newline, and returns the
1591
+ * lines now safe to emit: none while a value is still open.
1592
+ */
1593
+ readonly line: (line: string) => ReadonlyArray<string>
1594
+ /**
1595
+ * Takes part of a line whose newline has not arrived. A line longer than
1596
+ * {@link maxPartialLine} is never emitted: {@link omittedLine} stands for it.
1597
+ */
1598
+ readonly part: (text: string) => void
1599
+ /** What {@link LineRedactor.flush} would emit now, without ending the stream: for a rendered snapshot. */
1600
+ readonly peek: () => ReadonlyArray<string>
1601
+ /** Ends the stream and returns whatever is still held, redacted as one block. */
1602
+ readonly flush: () => ReadonlyArray<string>
1603
+ }
1604
+
1605
+ /**
1606
+ * Lines a {@link lineRedactor} holds for one open value. Past this, or past
1607
+ * 64 KiB, it stops holding: it emits what it held, redacted, and withholds
1608
+ * every later line until the stream ends, when one placeholder stands for
1609
+ * them. Dropping lines from the middle instead changed which brackets and
1610
+ * quotes were open, and released a later secret in clear.
1611
+ *
1612
+ * @since 1.0.0
1613
+ * @category constants
1614
+ */
1615
+ export const maxHeldLines = 256
1616
+
1617
+ const maxHeldBytes = 64 * 1024
1618
+
1619
+ /** Held lines a {@link lineRedactor} asks about one by one before it asks only as the block grows by half. */
1620
+ const eagerHeldLines = 16
1621
+
1622
+ /**
1623
+ * The most brackets and strings the dropped middle of an overlong line may
1624
+ * leave open before a {@link lineRedactor} stops reading it and treats the
1625
+ * line as leaving a value open. Without it the middle's state grew by one
1626
+ * entry per bracket: 32 MiB of `[` held 1.7 GB (#3088).
1627
+ */
1628
+ const maxDroppedDepth = 1024
1629
+
1630
+ /**
1631
+ * The longest line a {@link lineRedactor} reads whole. A longer line keeps
1632
+ * its first and last 16 KiB; its middle is scanned for what it leaves open
1633
+ * and dropped.
1634
+ *
1635
+ * @since 1.0.0
1636
+ * @category constants
1637
+ */
1638
+ export const maxPartialLine = 32 * 1024
1639
+
1640
+ /**
1641
+ * What a {@link lineRedactor} emits in place of a line longer than
1642
+ * {@link maxPartialLine}.
1643
+ *
1644
+ * @since 1.0.0
1645
+ * @category constants
1646
+ */
1647
+ export const omittedLine = "[overlong line omitted]"
1648
+
1649
+ /**
1650
+ * A next line no rule redacts alone, which an open value swallows. The value
1651
+ * is open when the redacted text no longer ENDS with it: text before it may
1652
+ * contain the same word.
1653
+ */
1654
+ const continuationProbe = "\n'probe'"
1655
+
1656
+ /** Rules with the global flag each rule needs to replace every match. */
1657
+ const globalRules = (rules: ReadonlyArray<Rule>): ReadonlyArray<Rule> =>
1658
+ rules.map((rule) =>
1659
+ rule.pattern.flags.includes("g")
1660
+ ? rule
1661
+ : { ...rule, pattern: new RegExp(rule.pattern.source, `${rule.pattern.flags}g`) }
1662
+ )
1663
+
1664
+ /**
1665
+ * A redactor for a stream that must be emitted line by line: a live build
1666
+ * log, a child's stderr.
1667
+ *
1668
+ * Redacting each line alone is the flaw that leaked a private key's body, and
1669
+ * the tail of every string `util.inspect` split over several lines: only the
1670
+ * line holding the name was redacted. This one asks the rules themselves
1671
+ * whether a line leaves a value open, by checking whether the value swallows
1672
+ * a probe placed on the next line, and holds lines until it closes. The held
1673
+ * block is then redacted whole, exactly as {@link redact} redacts a string.
1674
+ *
1675
+ * A line longer than {@link maxPartialLine} is read as its first and last
1676
+ * 16 KiB. Its middle is dropped, but a bracket, quote or key block the middle
1677
+ * leaves open would have opened a value the kept ends cannot show, so then
1678
+ * the rest of the stream is withheld. Such a line is never emitted, only
1679
+ * {@link omittedLine}, and neither is any block it was held in.
1680
+ *
1681
+ * Its state is bounded whatever the stream does: the line still arriving is
1682
+ * a 16 KiB head, a 16 KiB tail and at most 1024 open brackets or strings of
1683
+ * its middle, a middle nested deeper counting as one left open; the held
1684
+ * block is bounded by {@link maxHeldLines} and 64 KiB. Its cost is linear:
1685
+ * past the first 16 held lines the block is re-read only once it has grown
1686
+ * by half, on Node and on Bun alike (#3088).
1687
+ *
1688
+ * `rules` defaults to {@link diagnosticRules}. The array is read on every
1689
+ * line, so a caller may add a rule, a session secret, as the stream runs.
1690
+ *
1691
+ * @since 1.0.0
1692
+ * @category constructors
1693
+ */
1694
+ export const lineRedactor = (rules: ReadonlyArray<Rule> = diagnosticRules): LineRedactor => {
1695
+ const held: Array<string> = []
1696
+ let heldBytes = 0
1697
+ let askAt = 0
1698
+ let heldOverlong = false
1699
+ let withheld = false
1700
+ // The line still arriving: whole up to the bound, then a head, a rolling
1701
+ // tail, and what the dropped middle leaves open.
1702
+ const edge = maxPartialLine / 2
1703
+ let head = ""
1704
+ let tail = ""
1705
+ let overlong = false
1706
+ let middle: Array<Open> = []
1707
+ let middleDeep = false
1708
+ let middleKey = false
1709
+ let carry = ""
1710
+ const resetPartial = () => {
1711
+ head = ""
1712
+ tail = ""
1713
+ overlong = false
1714
+ middle = []
1715
+ middleDeep = false
1716
+ middleKey = false
1717
+ carry = ""
1718
+ }
1719
+ const scanDropped = (dropped: string) => {
1720
+ // What the middle leaves open is read in slices, and once it is nested
1721
+ // past `maxDroppedDepth` it is not read at all: the line is then already
1722
+ // risky, and the stack held one entry per bracket of a line of any length.
1723
+ for (let from = 0; from < dropped.length && !middleDeep; from += edge) {
1724
+ track(middle, dropped, from, Math.min(dropped.length, from + edge))
1725
+ if (middle.length > maxDroppedDepth) {
1726
+ middleDeep = true
1727
+ middle = []
1728
+ }
1729
+ }
1730
+ const seen = carry + dropped
1731
+ const begin = seen.search(/-----BEGIN[^-]*PRIVATE KEY/)
1732
+ const lastBegin = seen.lastIndexOf("-----BEGIN")
1733
+ const lastEnd = seen.lastIndexOf("-----END")
1734
+ if (begin !== -1 || lastEnd !== -1) middleKey = lastBegin > lastEnd
1735
+ carry = seen.slice(-64)
1736
+ }
1737
+ const redacted = (text: string) => redactString(text, globalRules(rules))
1738
+ const release = (): ReadonlyArray<string> => {
1739
+ const text = redacted(held.join("\n"))
1740
+ const overlongBlock = heldOverlong
1741
+ held.length = 0
1742
+ heldBytes = 0
1743
+ askAt = 0
1744
+ heldOverlong = false
1745
+ return overlongBlock ? [omittedLine] : text.split("\n")
1746
+ }
1747
+ const part = (text: string): void => {
1748
+ if (withheld) return
1749
+ if (!overlong) {
1750
+ head += text
1751
+ if (head.length <= maxPartialLine) return
1752
+ overlong = true
1753
+ tail = head.slice(edge)
1754
+ head = head.slice(0, edge)
1755
+ } else tail += text
1756
+ if (tail.length > edge) {
1757
+ scanDropped(tail.slice(0, tail.length - edge))
1758
+ tail = tail.slice(-edge)
1759
+ }
1760
+ }
1761
+ const line = (rest: string): ReadonlyArray<string> => {
1762
+ if (withheld) {
1763
+ resetPartial()
1764
+ return []
1765
+ }
1766
+ part(rest)
1767
+ let text = head
1768
+ if (overlong) {
1769
+ const risky = middle.length > 0 || middleDeep || middleKey
1770
+ text = `${head} ${tail}`
1771
+ resetPartial()
1772
+ if (risky) {
1773
+ const before = held.length === 0 ? [] : [placeholder]
1774
+ held.length = 0
1775
+ heldBytes = 0
1776
+ askAt = 0
1777
+ heldOverlong = false
1778
+ withheld = true
1779
+ return [...before, omittedLine]
1780
+ }
1781
+ heldOverlong = true
1782
+ } else resetPartial()
1783
+ held.push(text)
1784
+ heldBytes += text.length + 1
1785
+ // Asking after every line re-redacted the whole block per line, so a
1786
+ // block of n bytes cost n² (#3088). Past the first lines the question is
1787
+ // asked again only once the block has grown by half, which keeps the
1788
+ // cost linear; a block that closed in between is released with the
1789
+ // lines after it, redacted as one block, which hides no less.
1790
+ if (held.length <= eagerHeldLines || heldBytes >= askAt) {
1791
+ if (redacted(held.join("\n") + continuationProbe).endsWith(continuationProbe)) return release()
1792
+ askAt = heldBytes + (heldBytes >> 1)
1793
+ }
1794
+ if (held.length <= maxHeldLines && heldBytes <= maxHeldBytes) return []
1795
+ withheld = true
1796
+ return release()
1797
+ }
1798
+ const peek = (): ReadonlyArray<string> => {
1799
+ if (withheld) return [placeholder]
1800
+ const pending = overlong ? [omittedLine] : head === "" ? [] : [head]
1801
+ if (heldOverlong) return [omittedLine]
1802
+ const text = [...held, ...(overlong ? [] : pending)]
1803
+ const out = text.length === 0 ? [] : redacted(text.join("\n")).split("\n")
1804
+ return overlong ? [...out, omittedLine] : out
1805
+ }
1806
+ return {
1807
+ line,
1808
+ part,
1809
+ peek,
1810
+ flush: () => {
1811
+ const out = head !== "" || overlong ? [...line("")] : []
1812
+ if (withheld) {
1813
+ withheld = false
1814
+ return [...out, placeholder]
1815
+ }
1816
+ return held.length === 0 ? out : [...out, ...release()]
1817
+ }
1818
+ }
1819
+ }
1820
+
1821
+ /**
1822
+ * The identity redactor, for a caller that persists payloads verbatim by
1823
+ * choice: a trusted single-tenant store, or a suite asserting on raw input.
1824
+ *
1825
+ * @since 0.1.0
1826
+ * @category constructors
1827
+ */
1828
+ export const makeNoop = (): Redactor => (value) => value