anonyma 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/CHANGELOG.md +273 -144
  2. package/README.md +427 -143
  3. package/dist/ai/index.cjs +522 -0
  4. package/dist/ai/index.cjs.map +1 -0
  5. package/dist/ai/index.d.cts +322 -0
  6. package/dist/ai/index.d.ts +322 -0
  7. package/dist/ai/index.js +505 -0
  8. package/dist/ai/index.js.map +1 -0
  9. package/dist/audit/index.cjs +359 -0
  10. package/dist/audit/index.cjs.map +1 -0
  11. package/dist/audit/index.d.cts +287 -0
  12. package/dist/audit/index.d.ts +287 -0
  13. package/dist/audit/index.js +340 -0
  14. package/dist/audit/index.js.map +1 -0
  15. package/dist/chunk-26IHMQHL.cjs +662 -0
  16. package/dist/chunk-26IHMQHL.cjs.map +1 -0
  17. package/dist/chunk-2F2GWGTB.js +174 -0
  18. package/dist/chunk-2F2GWGTB.js.map +1 -0
  19. package/dist/chunk-2NNMJ55L.cjs +45 -0
  20. package/dist/chunk-2NNMJ55L.cjs.map +1 -0
  21. package/dist/chunk-2YG7R4KJ.cjs +114 -0
  22. package/dist/chunk-2YG7R4KJ.cjs.map +1 -0
  23. package/dist/chunk-2ZZHLCEJ.js +237 -0
  24. package/dist/chunk-2ZZHLCEJ.js.map +1 -0
  25. package/dist/chunk-3CY6ATKS.cjs +308 -0
  26. package/dist/chunk-3CY6ATKS.cjs.map +1 -0
  27. package/dist/chunk-3D5ZCJ7R.js +268 -0
  28. package/dist/chunk-3D5ZCJ7R.js.map +1 -0
  29. package/dist/chunk-6LDAIJBL.js +103 -0
  30. package/dist/chunk-6LDAIJBL.js.map +1 -0
  31. package/dist/chunk-7HK2V5Q4.js +111 -0
  32. package/dist/chunk-7HK2V5Q4.js.map +1 -0
  33. package/dist/chunk-AAP472NG.js +177 -0
  34. package/dist/chunk-AAP472NG.js.map +1 -0
  35. package/dist/chunk-AP4JIUNW.js +42 -0
  36. package/dist/chunk-AP4JIUNW.js.map +1 -0
  37. package/dist/chunk-BBJPQPGP.js +457 -0
  38. package/dist/chunk-BBJPQPGP.js.map +1 -0
  39. package/dist/chunk-CRXRJZEV.cjs +82 -0
  40. package/dist/chunk-CRXRJZEV.cjs.map +1 -0
  41. package/dist/chunk-E3PICZYI.js +20 -0
  42. package/dist/chunk-E3PICZYI.js.map +1 -0
  43. package/dist/chunk-F7O2FA3F.cjs +1255 -0
  44. package/dist/chunk-F7O2FA3F.cjs.map +1 -0
  45. package/dist/chunk-FB56NAAH.cjs +243 -0
  46. package/dist/chunk-FB56NAAH.cjs.map +1 -0
  47. package/dist/chunk-G4AN7FND.js +1063 -0
  48. package/dist/chunk-G4AN7FND.js.map +1 -0
  49. package/dist/chunk-GS3FRH4K.js +294 -0
  50. package/dist/chunk-GS3FRH4K.js.map +1 -0
  51. package/dist/chunk-GYMG5OI3.cjs +186 -0
  52. package/dist/chunk-GYMG5OI3.cjs.map +1 -0
  53. package/dist/chunk-IHEIYZPL.cjs +301 -0
  54. package/dist/chunk-IHEIYZPL.cjs.map +1 -0
  55. package/dist/chunk-IJAMLYOT.cjs +1087 -0
  56. package/dist/chunk-IJAMLYOT.cjs.map +1 -0
  57. package/dist/chunk-ISL5B4LU.cjs +181 -0
  58. package/dist/chunk-ISL5B4LU.cjs.map +1 -0
  59. package/dist/chunk-JKW36IPT.js +179 -0
  60. package/dist/chunk-JKW36IPT.js.map +1 -0
  61. package/dist/chunk-KOCQBDI4.cjs +179 -0
  62. package/dist/chunk-KOCQBDI4.cjs.map +1 -0
  63. package/dist/chunk-OGNLB2KA.js +79 -0
  64. package/dist/chunk-OGNLB2KA.js.map +1 -0
  65. package/dist/chunk-PKHZ7CVI.js +28 -0
  66. package/dist/chunk-PKHZ7CVI.js.map +1 -0
  67. package/dist/chunk-QYD4F6T7.cjs +114 -0
  68. package/dist/chunk-QYD4F6T7.cjs.map +1 -0
  69. package/dist/chunk-RCW5IPPR.js +1288 -0
  70. package/dist/chunk-RCW5IPPR.js.map +1 -0
  71. package/dist/chunk-RMMKYHUN.cjs +35 -0
  72. package/dist/chunk-RMMKYHUN.cjs.map +1 -0
  73. package/dist/chunk-S4BJ2ADB.cjs +22 -0
  74. package/dist/chunk-S4BJ2ADB.cjs.map +1 -0
  75. package/dist/chunk-S7NH6CHY.cjs +462 -0
  76. package/dist/chunk-S7NH6CHY.cjs.map +1 -0
  77. package/dist/chunk-SIHPDZXA.js +176 -0
  78. package/dist/chunk-SIHPDZXA.js.map +1 -0
  79. package/dist/chunk-TW7PM3UJ.cjs +30 -0
  80. package/dist/chunk-TW7PM3UJ.cjs.map +1 -0
  81. package/dist/chunk-UA3EOFBS.cjs +1322 -0
  82. package/dist/chunk-UA3EOFBS.cjs.map +1 -0
  83. package/dist/chunk-VE4CCW7W.js +32 -0
  84. package/dist/chunk-VE4CCW7W.js.map +1 -0
  85. package/dist/chunk-W6RBCHYF.js +651 -0
  86. package/dist/chunk-W6RBCHYF.js.map +1 -0
  87. package/dist/chunk-WLJN7GIS.cjs +189 -0
  88. package/dist/chunk-WLJN7GIS.cjs.map +1 -0
  89. package/dist/chunk-YMLR375Z.js +1244 -0
  90. package/dist/chunk-YMLR375Z.js.map +1 -0
  91. package/dist/compliance/index.cjs +88 -0
  92. package/dist/compliance/index.cjs.map +1 -0
  93. package/dist/compliance/index.d.cts +277 -0
  94. package/dist/compliance/index.d.ts +277 -0
  95. package/dist/compliance/index.js +47 -0
  96. package/dist/compliance/index.js.map +1 -0
  97. package/dist/crypto.cjs +12 -136
  98. package/dist/crypto.cjs.map +1 -1
  99. package/dist/crypto.d.cts +4 -3
  100. package/dist/crypto.d.ts +4 -3
  101. package/dist/crypto.js +3 -137
  102. package/dist/crypto.js.map +1 -1
  103. package/dist/detectors/index.cjs +146 -1483
  104. package/dist/detectors/index.cjs.map +1 -1
  105. package/dist/detectors/index.d.cts +1 -1
  106. package/dist/detectors/index.d.ts +1 -1
  107. package/dist/detectors/index.js +3 -1449
  108. package/dist/detectors/index.js.map +1 -1
  109. package/dist/engine/index.cjs +441 -0
  110. package/dist/engine/index.cjs.map +1 -0
  111. package/dist/engine/index.d.cts +728 -0
  112. package/dist/engine/index.d.ts +728 -0
  113. package/dist/engine/index.js +189 -0
  114. package/dist/engine/index.js.map +1 -0
  115. package/dist/hash-2PSYNDMM.cjs +14 -0
  116. package/dist/hash-2PSYNDMM.cjs.map +1 -0
  117. package/dist/hash-CELLDNKN.js +5 -0
  118. package/dist/hash-CELLDNKN.js.map +1 -0
  119. package/dist/index.cjs +153 -2816
  120. package/dist/index.cjs.map +1 -1
  121. package/dist/index.d.cts +93 -11
  122. package/dist/index.d.ts +93 -11
  123. package/dist/index.js +13 -2791
  124. package/dist/index.js.map +1 -1
  125. package/dist/json-CKDvlRtl.d.ts +147 -0
  126. package/dist/json-s8ny-RCo.d.cts +147 -0
  127. package/dist/mcp/index.cjs +751 -0
  128. package/dist/mcp/index.cjs.map +1 -0
  129. package/dist/mcp/index.d.cts +226 -0
  130. package/dist/mcp/index.d.ts +226 -0
  131. package/dist/mcp/index.js +744 -0
  132. package/dist/mcp/index.js.map +1 -0
  133. package/dist/middleware/express.cjs +93 -0
  134. package/dist/middleware/express.cjs.map +1 -0
  135. package/dist/middleware/express.d.cts +90 -0
  136. package/dist/middleware/express.d.ts +90 -0
  137. package/dist/middleware/express.js +91 -0
  138. package/dist/middleware/express.js.map +1 -0
  139. package/dist/middleware/hono.cjs +58 -0
  140. package/dist/middleware/hono.cjs.map +1 -0
  141. package/dist/middleware/hono.d.cts +75 -0
  142. package/dist/middleware/hono.d.ts +75 -0
  143. package/dist/middleware/hono.js +56 -0
  144. package/dist/middleware/hono.js.map +1 -0
  145. package/dist/middleware/index.cjs +24 -0
  146. package/dist/middleware/index.cjs.map +1 -0
  147. package/dist/middleware/index.d.cts +106 -0
  148. package/dist/middleware/index.d.ts +106 -0
  149. package/dist/middleware/index.js +15 -0
  150. package/dist/middleware/index.js.map +1 -0
  151. package/dist/schemas.cjs +5 -5
  152. package/dist/schemas.cjs.map +1 -1
  153. package/dist/schemas.d.cts +20 -10
  154. package/dist/schemas.d.ts +20 -10
  155. package/dist/schemas.js +5 -5
  156. package/dist/schemas.js.map +1 -1
  157. package/dist/session-BdRftyZ5.d.cts +102 -0
  158. package/dist/session-Cs2zlNQp.d.ts +102 -0
  159. package/dist/stream.cjs +13 -2262
  160. package/dist/stream.cjs.map +1 -1
  161. package/dist/stream.d.cts +1 -1
  162. package/dist/stream.d.ts +1 -1
  163. package/dist/stream.js +6 -2255
  164. package/dist/stream.js.map +1 -1
  165. package/dist/types--tPm_AjY.d.ts +199 -0
  166. package/dist/types-0BJH_wqc.d.cts +199 -0
  167. package/dist/types-CPUhjvl8.d.cts +629 -0
  168. package/dist/types-Dtht33aq.d.ts +629 -0
  169. package/dist/{types-D-9HzVuy.d.cts → types-EJTj_BKY.d.cts} +38 -7
  170. package/dist/{types-D-9HzVuy.d.ts → types-EJTj_BKY.d.ts} +38 -7
  171. package/dist/types-Zt_bZvwS.d.cts +182 -0
  172. package/dist/types-Zt_bZvwS.d.ts +182 -0
  173. package/dist/validators.cjs +39 -181
  174. package/dist/validators.cjs.map +1 -1
  175. package/dist/validators.js +1 -174
  176. package/dist/validators.js.map +1 -1
  177. package/dist/vault/index.cjs +688 -0
  178. package/dist/vault/index.cjs.map +1 -0
  179. package/dist/vault/index.d.cts +385 -0
  180. package/dist/vault/index.d.ts +385 -0
  181. package/dist/vault/index.js +669 -0
  182. package/dist/vault/index.js.map +1 -0
  183. package/package.json +128 -11
@@ -0,0 +1,287 @@
1
+ import { D as DetectedSpan, d as AppliedSpan } from '../types-CPUhjvl8.cjs';
2
+ import { A as AuditFieldEntry, b as AuditSink, c as AuditHead, a as AuditLogger, d as AuditRecord, e as AuditVerification } from '../types-Zt_bZvwS.cjs';
3
+ export { f as AuditChecksums, g as AuditEvent, h as AuditFailure, i as AuditOperation, j as AuditPolicyRef } from '../types-Zt_bZvwS.cjs';
4
+ import '../types-EJTj_BKY.cjs';
5
+
6
+ /**
7
+ * @module audit/canonical
8
+ * @description Canonical JSON and digests. Two values that are equal as data
9
+ * always serialise to the same string, so a digest of that string identifies
10
+ * the data.
11
+ */
12
+ /**
13
+ * Serialise a JSON value canonically: object members sorted by key, no
14
+ * insignificant whitespace, `undefined` members omitted, array holes written
15
+ * as `null`.
16
+ *
17
+ * @param value - A value made of plain objects, arrays, strings, finite
18
+ * numbers, booleans and `null`.
19
+ * @returns The canonical JSON text.
20
+ * @throws {@link ValidationError} When the value contains a non-finite number, a function,
21
+ * a symbol, a bigint, a cycle, or an object that is not plain data (a `Date`,
22
+ * a `Map`, a class instance): two such objects would otherwise share a text.
23
+ *
24
+ * @example
25
+ * ```ts
26
+ * canonicalize({ b: 1, a: [true, null] }); // '{"a":[true,null],"b":1}'
27
+ * ```
28
+ */
29
+ declare function canonicalize(value: unknown): string;
30
+ /**
31
+ * SHA-256 of a text, as lower-case hex.
32
+ *
33
+ * @param text - The text to digest (encoded as UTF-8).
34
+ * @returns 64 hexadecimal characters.
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * await sha256Hex("abc"); // "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
39
+ * ```
40
+ */
41
+ declare function sha256Hex(text: string): Promise<string>;
42
+ /**
43
+ * HMAC-SHA-256 of a text, as lower-case hex.
44
+ *
45
+ * @param text - The text to authenticate (encoded as UTF-8).
46
+ * @param key - An HMAC-SHA-256 key.
47
+ * @returns 64 hexadecimal characters.
48
+ *
49
+ * @remarks
50
+ * Never call this with the key of an audit chain on text that someone else
51
+ * chooses: the result would be a valid MAC under that key. For the checksum of
52
+ * an input use {@link inputChecksum}, which cannot collide with a record hash.
53
+ *
54
+ * @example
55
+ * ```ts
56
+ * const mac = await hmacSha256Hex("message", key);
57
+ * ```
58
+ */
59
+ declare function hmacSha256Hex(text: string, key: CryptoKey): Promise<string>;
60
+ /**
61
+ * Keyed checksum of an input, for `AuditEvent.checksums.input`. It ties a
62
+ * record to the data it describes without storing the data, and without
63
+ * letting whoever chose the input obtain a MAC that is valid anywhere else.
64
+ *
65
+ * @param text - The input text.
66
+ * @param key - The HMAC-SHA-256 key of the audit chain.
67
+ * @returns 64 hexadecimal characters.
68
+ *
69
+ * @example
70
+ * ```ts
71
+ * await audit.record({
72
+ * operation: "anonymize",
73
+ * fields: [],
74
+ * checksums: { input: await inputChecksum(text, key) },
75
+ * });
76
+ * ```
77
+ */
78
+ declare function inputChecksum(text: string, key: CryptoKey): Promise<string>;
79
+
80
+ /**
81
+ * @module audit/fields
82
+ * @description Helpers that turn engine results into audit field entries.
83
+ */
84
+
85
+ /**
86
+ * Build an RFC 6901 JSON Pointer from path segments.
87
+ *
88
+ * @param segments - Object keys and array indices, outermost first.
89
+ * @returns The pointer; `""` for no segments.
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * jsonPointer(["user", "emails", 0]); // "/user/emails/0"
94
+ * jsonPointer(["a/b", "c~d"]); // "/a~1b/c~0d"
95
+ * ```
96
+ */
97
+ declare function jsonPointer(segments: readonly (string | number)[]): string;
98
+ /**
99
+ * Summarise the spans of one transformed field as audit entries: one entry
100
+ * per category and detector, with the number of replacements. The entries
101
+ * contain no matched text.
102
+ *
103
+ * @param spans - Spans returned by a pipeline for the field.
104
+ * @param options - `path` locates the field (a JSON Pointer, `""` by default);
105
+ * `rule` names the rule applied, fixed or per category.
106
+ * @returns The entries, in order of first appearance.
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * const result = pipeline.transform(text);
111
+ * await audit.record({
112
+ * operation: "anonymize",
113
+ * fields: summarizeSpans(result.spans, { path: "/message", rule: "redact" }),
114
+ * });
115
+ * ```
116
+ */
117
+ declare function summarizeSpans(spans: readonly (DetectedSpan | AppliedSpan)[], options: {
118
+ readonly path?: string;
119
+ readonly rule: string | ((category: string) => string);
120
+ }): AuditFieldEntry[];
121
+
122
+ /**
123
+ * @module audit/logger
124
+ * @description The append-only, hash-chained, zero-PII audit logger.
125
+ *
126
+ * Guarantees
127
+ * - **Zero PII by construction**: an event has no member for values. Every
128
+ * caller-supplied string (actor, source, policy reference, attribute, field
129
+ * path segment, category, detector, rule) is additionally checked by a guard
130
+ * and blanked if it looks like personal data.
131
+ * - **Order**: records are sealed strictly in the order `record()` was called.
132
+ * - **Tamper evidence**: each record's hash covers its content and the hash of
133
+ * its predecessor. With a key the hash is an HMAC, so someone who can rewrite
134
+ * the log but does not hold the key cannot recompute the chain. Without a
135
+ * key, anchor {@link AuditLogger.head} somewhere the log writer cannot reach.
136
+ * - **Fail closed**: if a sink rejects a record, the logger stops accepting
137
+ * records instead of continuing with a gap.
138
+ */
139
+
140
+ /** `prev` of the first record of a chain. */
141
+ declare const GENESIS_HASH: string;
142
+ /**
143
+ * Options accepted by {@link createAuditLogger}.
144
+ */
145
+ interface AuditLoggerOptions {
146
+ /** Where sealed records go. Each sink receives every record, in order. */
147
+ readonly sinks: readonly AuditSink[];
148
+ /**
149
+ * HMAC-SHA-256 key that authenticates the chain, for example
150
+ * `await keyring.deriveKey(keyId, "audit-mac")`. Without it the chain uses
151
+ * plain SHA-256.
152
+ */
153
+ readonly key?: CryptoKey;
154
+ /** Clock. Defaults to `Date.now`. */
155
+ readonly now?: () => number;
156
+ /**
157
+ * Returns `true` for a string that looks like personal data. Defaults to the
158
+ * validating detectors for email addresses, SSNs, IBANs, IP addresses and
159
+ * card numbers.
160
+ */
161
+ readonly guard?: (value: string) => boolean;
162
+ /** Continue an existing chain from its head. */
163
+ readonly resume?: AuditHead;
164
+ }
165
+ /**
166
+ * Create an audit logger.
167
+ *
168
+ * @param options - Sinks, optional chain key, clock, guard and resume point.
169
+ * @returns The {@link AuditLogger}.
170
+ * @throws {@link ValidationError} When no sink is given or `resume` is malformed.
171
+ *
172
+ * @example
173
+ * ```ts
174
+ * import { createAuditLogger, lineSink, summarizeSpans } from "anonyma/audit";
175
+ * import { appendFile } from "node:fs/promises";
176
+ *
177
+ * const audit = createAuditLogger({
178
+ * sinks: [lineSink((line) => appendFile("audit.ndjson", line))],
179
+ * key: await keyring.deriveKey(keyring.activeKeyId(), "audit-mac"),
180
+ * });
181
+ *
182
+ * const result = pipeline.transform(body.message);
183
+ * await audit.record({
184
+ * operation: "anonymize",
185
+ * actor: "support-api",
186
+ * policy: { id: "gdpr" },
187
+ * fields: summarizeSpans(result.spans, { path: "/message", rule: "redact" }),
188
+ * });
189
+ * ```
190
+ */
191
+ declare function createAuditLogger(options: AuditLoggerOptions): AuditLogger;
192
+
193
+ /**
194
+ * @module audit/sinks
195
+ * @description Sinks for sealed audit records.
196
+ */
197
+
198
+ /**
199
+ * An {@link AuditSink} that keeps records in memory.
200
+ */
201
+ interface MemoryAuditSink extends AuditSink {
202
+ /** The records appended so far, in chain order. */
203
+ readonly records: () => readonly AuditRecord[];
204
+ }
205
+ /**
206
+ * Create a sink that keeps records in memory. Useful for tests and for
207
+ * handing a batch of records to another system.
208
+ *
209
+ * @returns The sink.
210
+ *
211
+ * @example
212
+ * ```ts
213
+ * const sink = memorySink();
214
+ * const audit = createAuditLogger({ sinks: [sink] });
215
+ * await audit.record({ operation: "detect", fields: [] });
216
+ * sink.records().length; // 1
217
+ * ```
218
+ */
219
+ declare function memorySink(): MemoryAuditSink;
220
+ /**
221
+ * Create a sink that writes each record as one line of canonical JSON
222
+ * (NDJSON). The `write` function decides where lines go, which keeps this
223
+ * module free of file-system and network code.
224
+ *
225
+ * @param write - Receives one line, including the trailing line feed. It must only append.
226
+ * @returns The sink.
227
+ *
228
+ * @example
229
+ * ```ts
230
+ * import { appendFile } from "node:fs/promises";
231
+ *
232
+ * const sink = lineSink((line) => appendFile("/var/log/anonyma/audit.ndjson", line));
233
+ * ```
234
+ */
235
+ declare function lineSink(write: (line: string) => void | Promise<void>): AuditSink;
236
+ /**
237
+ * Parse an NDJSON audit log into records for {@link verifyAuditChain}. Blank
238
+ * lines are skipped. A line that is not valid JSON, or not the canonical JSON
239
+ * the logger writes (reordered or duplicate members, extra whitespace),
240
+ * becomes `null`, which the verifier reports as malformed at that position:
241
+ * the stored text must say exactly what the verified record says.
242
+ *
243
+ * @param text - The log text.
244
+ * @returns One entry per non-blank line.
245
+ *
246
+ * @example
247
+ * ```ts
248
+ * const result = await verifyAuditChain(parseAuditLog(await readFile("audit.ndjson", "utf8")));
249
+ * ```
250
+ */
251
+ declare function parseAuditLog(text: string): unknown[];
252
+
253
+ /**
254
+ * @module audit/verify
255
+ * @description Verification of an audit chain.
256
+ */
257
+
258
+ /**
259
+ * Options accepted by {@link verifyAuditChain}.
260
+ */
261
+ interface VerifyOptions {
262
+ /** The HMAC key of the chain, when the logger had one. */
263
+ readonly key?: CryptoKey;
264
+ /** The head the records are expected to continue from. Defaults to an empty chain. */
265
+ readonly after?: AuditHead;
266
+ /**
267
+ * The head the chain is expected to end at, taken from a trusted place.
268
+ * Detects truncation and wholesale replacement of the log.
269
+ */
270
+ readonly expectedHead?: AuditHead;
271
+ }
272
+ /**
273
+ * Verify a chain of audit records: sequence numbers, links and hashes.
274
+ *
275
+ * @param records - The records, in order. Entries may come from untrusted storage.
276
+ * @param options - Chain key and expected boundaries.
277
+ * @returns Whether the chain is intact and, if not, where and why it breaks.
278
+ *
279
+ * @example
280
+ * ```ts
281
+ * const result = await verifyAuditChain(sink.records(), { key, expectedHead: audit.head() });
282
+ * if (!result.ok) throw new Error(`audit log broken at record ${result.index}: ${result.reason}`);
283
+ * ```
284
+ */
285
+ declare function verifyAuditChain(records: Iterable<unknown> | AsyncIterable<unknown>, options?: VerifyOptions): Promise<AuditVerification>;
286
+
287
+ export { AuditFieldEntry, AuditHead, AuditLogger, type AuditLoggerOptions, AuditRecord, AuditSink, AuditVerification, GENESIS_HASH, type MemoryAuditSink, type VerifyOptions, canonicalize, createAuditLogger, hmacSha256Hex, inputChecksum, jsonPointer, lineSink, memorySink, parseAuditLog, sha256Hex, summarizeSpans, verifyAuditChain };
@@ -0,0 +1,287 @@
1
+ import { D as DetectedSpan, d as AppliedSpan } from '../types-Dtht33aq.js';
2
+ import { A as AuditFieldEntry, b as AuditSink, c as AuditHead, a as AuditLogger, d as AuditRecord, e as AuditVerification } from '../types-Zt_bZvwS.js';
3
+ export { f as AuditChecksums, g as AuditEvent, h as AuditFailure, i as AuditOperation, j as AuditPolicyRef } from '../types-Zt_bZvwS.js';
4
+ import '../types-EJTj_BKY.js';
5
+
6
+ /**
7
+ * @module audit/canonical
8
+ * @description Canonical JSON and digests. Two values that are equal as data
9
+ * always serialise to the same string, so a digest of that string identifies
10
+ * the data.
11
+ */
12
+ /**
13
+ * Serialise a JSON value canonically: object members sorted by key, no
14
+ * insignificant whitespace, `undefined` members omitted, array holes written
15
+ * as `null`.
16
+ *
17
+ * @param value - A value made of plain objects, arrays, strings, finite
18
+ * numbers, booleans and `null`.
19
+ * @returns The canonical JSON text.
20
+ * @throws {@link ValidationError} When the value contains a non-finite number, a function,
21
+ * a symbol, a bigint, a cycle, or an object that is not plain data (a `Date`,
22
+ * a `Map`, a class instance): two such objects would otherwise share a text.
23
+ *
24
+ * @example
25
+ * ```ts
26
+ * canonicalize({ b: 1, a: [true, null] }); // '{"a":[true,null],"b":1}'
27
+ * ```
28
+ */
29
+ declare function canonicalize(value: unknown): string;
30
+ /**
31
+ * SHA-256 of a text, as lower-case hex.
32
+ *
33
+ * @param text - The text to digest (encoded as UTF-8).
34
+ * @returns 64 hexadecimal characters.
35
+ *
36
+ * @example
37
+ * ```ts
38
+ * await sha256Hex("abc"); // "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
39
+ * ```
40
+ */
41
+ declare function sha256Hex(text: string): Promise<string>;
42
+ /**
43
+ * HMAC-SHA-256 of a text, as lower-case hex.
44
+ *
45
+ * @param text - The text to authenticate (encoded as UTF-8).
46
+ * @param key - An HMAC-SHA-256 key.
47
+ * @returns 64 hexadecimal characters.
48
+ *
49
+ * @remarks
50
+ * Never call this with the key of an audit chain on text that someone else
51
+ * chooses: the result would be a valid MAC under that key. For the checksum of
52
+ * an input use {@link inputChecksum}, which cannot collide with a record hash.
53
+ *
54
+ * @example
55
+ * ```ts
56
+ * const mac = await hmacSha256Hex("message", key);
57
+ * ```
58
+ */
59
+ declare function hmacSha256Hex(text: string, key: CryptoKey): Promise<string>;
60
+ /**
61
+ * Keyed checksum of an input, for `AuditEvent.checksums.input`. It ties a
62
+ * record to the data it describes without storing the data, and without
63
+ * letting whoever chose the input obtain a MAC that is valid anywhere else.
64
+ *
65
+ * @param text - The input text.
66
+ * @param key - The HMAC-SHA-256 key of the audit chain.
67
+ * @returns 64 hexadecimal characters.
68
+ *
69
+ * @example
70
+ * ```ts
71
+ * await audit.record({
72
+ * operation: "anonymize",
73
+ * fields: [],
74
+ * checksums: { input: await inputChecksum(text, key) },
75
+ * });
76
+ * ```
77
+ */
78
+ declare function inputChecksum(text: string, key: CryptoKey): Promise<string>;
79
+
80
+ /**
81
+ * @module audit/fields
82
+ * @description Helpers that turn engine results into audit field entries.
83
+ */
84
+
85
+ /**
86
+ * Build an RFC 6901 JSON Pointer from path segments.
87
+ *
88
+ * @param segments - Object keys and array indices, outermost first.
89
+ * @returns The pointer; `""` for no segments.
90
+ *
91
+ * @example
92
+ * ```ts
93
+ * jsonPointer(["user", "emails", 0]); // "/user/emails/0"
94
+ * jsonPointer(["a/b", "c~d"]); // "/a~1b/c~0d"
95
+ * ```
96
+ */
97
+ declare function jsonPointer(segments: readonly (string | number)[]): string;
98
+ /**
99
+ * Summarise the spans of one transformed field as audit entries: one entry
100
+ * per category and detector, with the number of replacements. The entries
101
+ * contain no matched text.
102
+ *
103
+ * @param spans - Spans returned by a pipeline for the field.
104
+ * @param options - `path` locates the field (a JSON Pointer, `""` by default);
105
+ * `rule` names the rule applied, fixed or per category.
106
+ * @returns The entries, in order of first appearance.
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * const result = pipeline.transform(text);
111
+ * await audit.record({
112
+ * operation: "anonymize",
113
+ * fields: summarizeSpans(result.spans, { path: "/message", rule: "redact" }),
114
+ * });
115
+ * ```
116
+ */
117
+ declare function summarizeSpans(spans: readonly (DetectedSpan | AppliedSpan)[], options: {
118
+ readonly path?: string;
119
+ readonly rule: string | ((category: string) => string);
120
+ }): AuditFieldEntry[];
121
+
122
+ /**
123
+ * @module audit/logger
124
+ * @description The append-only, hash-chained, zero-PII audit logger.
125
+ *
126
+ * Guarantees
127
+ * - **Zero PII by construction**: an event has no member for values. Every
128
+ * caller-supplied string (actor, source, policy reference, attribute, field
129
+ * path segment, category, detector, rule) is additionally checked by a guard
130
+ * and blanked if it looks like personal data.
131
+ * - **Order**: records are sealed strictly in the order `record()` was called.
132
+ * - **Tamper evidence**: each record's hash covers its content and the hash of
133
+ * its predecessor. With a key the hash is an HMAC, so someone who can rewrite
134
+ * the log but does not hold the key cannot recompute the chain. Without a
135
+ * key, anchor {@link AuditLogger.head} somewhere the log writer cannot reach.
136
+ * - **Fail closed**: if a sink rejects a record, the logger stops accepting
137
+ * records instead of continuing with a gap.
138
+ */
139
+
140
+ /** `prev` of the first record of a chain. */
141
+ declare const GENESIS_HASH: string;
142
+ /**
143
+ * Options accepted by {@link createAuditLogger}.
144
+ */
145
+ interface AuditLoggerOptions {
146
+ /** Where sealed records go. Each sink receives every record, in order. */
147
+ readonly sinks: readonly AuditSink[];
148
+ /**
149
+ * HMAC-SHA-256 key that authenticates the chain, for example
150
+ * `await keyring.deriveKey(keyId, "audit-mac")`. Without it the chain uses
151
+ * plain SHA-256.
152
+ */
153
+ readonly key?: CryptoKey;
154
+ /** Clock. Defaults to `Date.now`. */
155
+ readonly now?: () => number;
156
+ /**
157
+ * Returns `true` for a string that looks like personal data. Defaults to the
158
+ * validating detectors for email addresses, SSNs, IBANs, IP addresses and
159
+ * card numbers.
160
+ */
161
+ readonly guard?: (value: string) => boolean;
162
+ /** Continue an existing chain from its head. */
163
+ readonly resume?: AuditHead;
164
+ }
165
+ /**
166
+ * Create an audit logger.
167
+ *
168
+ * @param options - Sinks, optional chain key, clock, guard and resume point.
169
+ * @returns The {@link AuditLogger}.
170
+ * @throws {@link ValidationError} When no sink is given or `resume` is malformed.
171
+ *
172
+ * @example
173
+ * ```ts
174
+ * import { createAuditLogger, lineSink, summarizeSpans } from "anonyma/audit";
175
+ * import { appendFile } from "node:fs/promises";
176
+ *
177
+ * const audit = createAuditLogger({
178
+ * sinks: [lineSink((line) => appendFile("audit.ndjson", line))],
179
+ * key: await keyring.deriveKey(keyring.activeKeyId(), "audit-mac"),
180
+ * });
181
+ *
182
+ * const result = pipeline.transform(body.message);
183
+ * await audit.record({
184
+ * operation: "anonymize",
185
+ * actor: "support-api",
186
+ * policy: { id: "gdpr" },
187
+ * fields: summarizeSpans(result.spans, { path: "/message", rule: "redact" }),
188
+ * });
189
+ * ```
190
+ */
191
+ declare function createAuditLogger(options: AuditLoggerOptions): AuditLogger;
192
+
193
+ /**
194
+ * @module audit/sinks
195
+ * @description Sinks for sealed audit records.
196
+ */
197
+
198
+ /**
199
+ * An {@link AuditSink} that keeps records in memory.
200
+ */
201
+ interface MemoryAuditSink extends AuditSink {
202
+ /** The records appended so far, in chain order. */
203
+ readonly records: () => readonly AuditRecord[];
204
+ }
205
+ /**
206
+ * Create a sink that keeps records in memory. Useful for tests and for
207
+ * handing a batch of records to another system.
208
+ *
209
+ * @returns The sink.
210
+ *
211
+ * @example
212
+ * ```ts
213
+ * const sink = memorySink();
214
+ * const audit = createAuditLogger({ sinks: [sink] });
215
+ * await audit.record({ operation: "detect", fields: [] });
216
+ * sink.records().length; // 1
217
+ * ```
218
+ */
219
+ declare function memorySink(): MemoryAuditSink;
220
+ /**
221
+ * Create a sink that writes each record as one line of canonical JSON
222
+ * (NDJSON). The `write` function decides where lines go, which keeps this
223
+ * module free of file-system and network code.
224
+ *
225
+ * @param write - Receives one line, including the trailing line feed. It must only append.
226
+ * @returns The sink.
227
+ *
228
+ * @example
229
+ * ```ts
230
+ * import { appendFile } from "node:fs/promises";
231
+ *
232
+ * const sink = lineSink((line) => appendFile("/var/log/anonyma/audit.ndjson", line));
233
+ * ```
234
+ */
235
+ declare function lineSink(write: (line: string) => void | Promise<void>): AuditSink;
236
+ /**
237
+ * Parse an NDJSON audit log into records for {@link verifyAuditChain}. Blank
238
+ * lines are skipped. A line that is not valid JSON, or not the canonical JSON
239
+ * the logger writes (reordered or duplicate members, extra whitespace),
240
+ * becomes `null`, which the verifier reports as malformed at that position:
241
+ * the stored text must say exactly what the verified record says.
242
+ *
243
+ * @param text - The log text.
244
+ * @returns One entry per non-blank line.
245
+ *
246
+ * @example
247
+ * ```ts
248
+ * const result = await verifyAuditChain(parseAuditLog(await readFile("audit.ndjson", "utf8")));
249
+ * ```
250
+ */
251
+ declare function parseAuditLog(text: string): unknown[];
252
+
253
+ /**
254
+ * @module audit/verify
255
+ * @description Verification of an audit chain.
256
+ */
257
+
258
+ /**
259
+ * Options accepted by {@link verifyAuditChain}.
260
+ */
261
+ interface VerifyOptions {
262
+ /** The HMAC key of the chain, when the logger had one. */
263
+ readonly key?: CryptoKey;
264
+ /** The head the records are expected to continue from. Defaults to an empty chain. */
265
+ readonly after?: AuditHead;
266
+ /**
267
+ * The head the chain is expected to end at, taken from a trusted place.
268
+ * Detects truncation and wholesale replacement of the log.
269
+ */
270
+ readonly expectedHead?: AuditHead;
271
+ }
272
+ /**
273
+ * Verify a chain of audit records: sequence numbers, links and hashes.
274
+ *
275
+ * @param records - The records, in order. Entries may come from untrusted storage.
276
+ * @param options - Chain key and expected boundaries.
277
+ * @returns Whether the chain is intact and, if not, where and why it breaks.
278
+ *
279
+ * @example
280
+ * ```ts
281
+ * const result = await verifyAuditChain(sink.records(), { key, expectedHead: audit.head() });
282
+ * if (!result.ok) throw new Error(`audit log broken at record ${result.index}: ${result.reason}`);
283
+ * ```
284
+ */
285
+ declare function verifyAuditChain(records: Iterable<unknown> | AsyncIterable<unknown>, options?: VerifyOptions): Promise<AuditVerification>;
286
+
287
+ export { AuditFieldEntry, AuditHead, AuditLogger, type AuditLoggerOptions, AuditRecord, AuditSink, AuditVerification, GENESIS_HASH, type MemoryAuditSink, type VerifyOptions, canonicalize, createAuditLogger, hmacSha256Hex, inputChecksum, jsonPointer, lineSink, memorySink, parseAuditLog, sha256Hex, summarizeSpans, verifyAuditChain };