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.
- package/CHANGELOG.md +273 -144
- package/README.md +427 -143
- package/dist/ai/index.cjs +522 -0
- package/dist/ai/index.cjs.map +1 -0
- package/dist/ai/index.d.cts +322 -0
- package/dist/ai/index.d.ts +322 -0
- package/dist/ai/index.js +505 -0
- package/dist/ai/index.js.map +1 -0
- package/dist/audit/index.cjs +359 -0
- package/dist/audit/index.cjs.map +1 -0
- package/dist/audit/index.d.cts +287 -0
- package/dist/audit/index.d.ts +287 -0
- package/dist/audit/index.js +340 -0
- package/dist/audit/index.js.map +1 -0
- package/dist/chunk-26IHMQHL.cjs +662 -0
- package/dist/chunk-26IHMQHL.cjs.map +1 -0
- package/dist/chunk-2F2GWGTB.js +174 -0
- package/dist/chunk-2F2GWGTB.js.map +1 -0
- package/dist/chunk-2NNMJ55L.cjs +45 -0
- package/dist/chunk-2NNMJ55L.cjs.map +1 -0
- package/dist/chunk-2YG7R4KJ.cjs +114 -0
- package/dist/chunk-2YG7R4KJ.cjs.map +1 -0
- package/dist/chunk-2ZZHLCEJ.js +237 -0
- package/dist/chunk-2ZZHLCEJ.js.map +1 -0
- package/dist/chunk-3CY6ATKS.cjs +308 -0
- package/dist/chunk-3CY6ATKS.cjs.map +1 -0
- package/dist/chunk-3D5ZCJ7R.js +268 -0
- package/dist/chunk-3D5ZCJ7R.js.map +1 -0
- package/dist/chunk-6LDAIJBL.js +103 -0
- package/dist/chunk-6LDAIJBL.js.map +1 -0
- package/dist/chunk-7HK2V5Q4.js +111 -0
- package/dist/chunk-7HK2V5Q4.js.map +1 -0
- package/dist/chunk-AAP472NG.js +177 -0
- package/dist/chunk-AAP472NG.js.map +1 -0
- package/dist/chunk-AP4JIUNW.js +42 -0
- package/dist/chunk-AP4JIUNW.js.map +1 -0
- package/dist/chunk-BBJPQPGP.js +457 -0
- package/dist/chunk-BBJPQPGP.js.map +1 -0
- package/dist/chunk-CRXRJZEV.cjs +82 -0
- package/dist/chunk-CRXRJZEV.cjs.map +1 -0
- package/dist/chunk-E3PICZYI.js +20 -0
- package/dist/chunk-E3PICZYI.js.map +1 -0
- package/dist/chunk-F7O2FA3F.cjs +1255 -0
- package/dist/chunk-F7O2FA3F.cjs.map +1 -0
- package/dist/chunk-FB56NAAH.cjs +243 -0
- package/dist/chunk-FB56NAAH.cjs.map +1 -0
- package/dist/chunk-G4AN7FND.js +1063 -0
- package/dist/chunk-G4AN7FND.js.map +1 -0
- package/dist/chunk-GS3FRH4K.js +294 -0
- package/dist/chunk-GS3FRH4K.js.map +1 -0
- package/dist/chunk-GYMG5OI3.cjs +186 -0
- package/dist/chunk-GYMG5OI3.cjs.map +1 -0
- package/dist/chunk-IHEIYZPL.cjs +301 -0
- package/dist/chunk-IHEIYZPL.cjs.map +1 -0
- package/dist/chunk-IJAMLYOT.cjs +1087 -0
- package/dist/chunk-IJAMLYOT.cjs.map +1 -0
- package/dist/chunk-ISL5B4LU.cjs +181 -0
- package/dist/chunk-ISL5B4LU.cjs.map +1 -0
- package/dist/chunk-JKW36IPT.js +179 -0
- package/dist/chunk-JKW36IPT.js.map +1 -0
- package/dist/chunk-KOCQBDI4.cjs +179 -0
- package/dist/chunk-KOCQBDI4.cjs.map +1 -0
- package/dist/chunk-OGNLB2KA.js +79 -0
- package/dist/chunk-OGNLB2KA.js.map +1 -0
- package/dist/chunk-PKHZ7CVI.js +28 -0
- package/dist/chunk-PKHZ7CVI.js.map +1 -0
- package/dist/chunk-QYD4F6T7.cjs +114 -0
- package/dist/chunk-QYD4F6T7.cjs.map +1 -0
- package/dist/chunk-RCW5IPPR.js +1288 -0
- package/dist/chunk-RCW5IPPR.js.map +1 -0
- package/dist/chunk-RMMKYHUN.cjs +35 -0
- package/dist/chunk-RMMKYHUN.cjs.map +1 -0
- package/dist/chunk-S4BJ2ADB.cjs +22 -0
- package/dist/chunk-S4BJ2ADB.cjs.map +1 -0
- package/dist/chunk-S7NH6CHY.cjs +462 -0
- package/dist/chunk-S7NH6CHY.cjs.map +1 -0
- package/dist/chunk-SIHPDZXA.js +176 -0
- package/dist/chunk-SIHPDZXA.js.map +1 -0
- package/dist/chunk-TW7PM3UJ.cjs +30 -0
- package/dist/chunk-TW7PM3UJ.cjs.map +1 -0
- package/dist/chunk-UA3EOFBS.cjs +1322 -0
- package/dist/chunk-UA3EOFBS.cjs.map +1 -0
- package/dist/chunk-VE4CCW7W.js +32 -0
- package/dist/chunk-VE4CCW7W.js.map +1 -0
- package/dist/chunk-W6RBCHYF.js +651 -0
- package/dist/chunk-W6RBCHYF.js.map +1 -0
- package/dist/chunk-WLJN7GIS.cjs +189 -0
- package/dist/chunk-WLJN7GIS.cjs.map +1 -0
- package/dist/chunk-YMLR375Z.js +1244 -0
- package/dist/chunk-YMLR375Z.js.map +1 -0
- package/dist/compliance/index.cjs +88 -0
- package/dist/compliance/index.cjs.map +1 -0
- package/dist/compliance/index.d.cts +277 -0
- package/dist/compliance/index.d.ts +277 -0
- package/dist/compliance/index.js +47 -0
- package/dist/compliance/index.js.map +1 -0
- package/dist/crypto.cjs +12 -136
- package/dist/crypto.cjs.map +1 -1
- package/dist/crypto.d.cts +4 -3
- package/dist/crypto.d.ts +4 -3
- package/dist/crypto.js +3 -137
- package/dist/crypto.js.map +1 -1
- package/dist/detectors/index.cjs +146 -1483
- package/dist/detectors/index.cjs.map +1 -1
- package/dist/detectors/index.d.cts +1 -1
- package/dist/detectors/index.d.ts +1 -1
- package/dist/detectors/index.js +3 -1449
- package/dist/detectors/index.js.map +1 -1
- package/dist/engine/index.cjs +441 -0
- package/dist/engine/index.cjs.map +1 -0
- package/dist/engine/index.d.cts +728 -0
- package/dist/engine/index.d.ts +728 -0
- package/dist/engine/index.js +189 -0
- package/dist/engine/index.js.map +1 -0
- package/dist/hash-2PSYNDMM.cjs +14 -0
- package/dist/hash-2PSYNDMM.cjs.map +1 -0
- package/dist/hash-CELLDNKN.js +5 -0
- package/dist/hash-CELLDNKN.js.map +1 -0
- package/dist/index.cjs +153 -2816
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +93 -11
- package/dist/index.d.ts +93 -11
- package/dist/index.js +13 -2791
- package/dist/index.js.map +1 -1
- package/dist/json-CKDvlRtl.d.ts +147 -0
- package/dist/json-s8ny-RCo.d.cts +147 -0
- package/dist/mcp/index.cjs +751 -0
- package/dist/mcp/index.cjs.map +1 -0
- package/dist/mcp/index.d.cts +226 -0
- package/dist/mcp/index.d.ts +226 -0
- package/dist/mcp/index.js +744 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/middleware/express.cjs +93 -0
- package/dist/middleware/express.cjs.map +1 -0
- package/dist/middleware/express.d.cts +90 -0
- package/dist/middleware/express.d.ts +90 -0
- package/dist/middleware/express.js +91 -0
- package/dist/middleware/express.js.map +1 -0
- package/dist/middleware/hono.cjs +58 -0
- package/dist/middleware/hono.cjs.map +1 -0
- package/dist/middleware/hono.d.cts +75 -0
- package/dist/middleware/hono.d.ts +75 -0
- package/dist/middleware/hono.js +56 -0
- package/dist/middleware/hono.js.map +1 -0
- package/dist/middleware/index.cjs +24 -0
- package/dist/middleware/index.cjs.map +1 -0
- package/dist/middleware/index.d.cts +106 -0
- package/dist/middleware/index.d.ts +106 -0
- package/dist/middleware/index.js +15 -0
- package/dist/middleware/index.js.map +1 -0
- package/dist/schemas.cjs +5 -5
- package/dist/schemas.cjs.map +1 -1
- package/dist/schemas.d.cts +20 -10
- package/dist/schemas.d.ts +20 -10
- package/dist/schemas.js +5 -5
- package/dist/schemas.js.map +1 -1
- package/dist/session-BdRftyZ5.d.cts +102 -0
- package/dist/session-Cs2zlNQp.d.ts +102 -0
- package/dist/stream.cjs +13 -2262
- package/dist/stream.cjs.map +1 -1
- package/dist/stream.d.cts +1 -1
- package/dist/stream.d.ts +1 -1
- package/dist/stream.js +6 -2255
- package/dist/stream.js.map +1 -1
- package/dist/types--tPm_AjY.d.ts +199 -0
- package/dist/types-0BJH_wqc.d.cts +199 -0
- package/dist/types-CPUhjvl8.d.cts +629 -0
- package/dist/types-Dtht33aq.d.ts +629 -0
- package/dist/{types-D-9HzVuy.d.cts → types-EJTj_BKY.d.cts} +38 -7
- package/dist/{types-D-9HzVuy.d.ts → types-EJTj_BKY.d.ts} +38 -7
- package/dist/types-Zt_bZvwS.d.cts +182 -0
- package/dist/types-Zt_bZvwS.d.ts +182 -0
- package/dist/validators.cjs +39 -181
- package/dist/validators.cjs.map +1 -1
- package/dist/validators.js +1 -174
- package/dist/validators.js.map +1 -1
- package/dist/vault/index.cjs +688 -0
- package/dist/vault/index.cjs.map +1 -0
- package/dist/vault/index.d.cts +385 -0
- package/dist/vault/index.d.ts +385 -0
- package/dist/vault/index.js +669 -0
- package/dist/vault/index.js.map +1 -0
- 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 };
|