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,629 @@
1
+ import { P as PiiCategory, E as EncryptOptions, C as CompliancePreset, S as StrategyOptions } from './types-EJTj_BKY.cjs';
2
+
3
+ /**
4
+ * @module vault/types
5
+ * @description Contracts for deterministic tokenization, key management and
6
+ * token vaults exposed as `"anonyma/vault"`. This module contains types only —
7
+ * it has no runtime code.
8
+ */
9
+ /**
10
+ * A value that may be returned directly or through a promise. Implementations
11
+ * backed by the Web Crypto API or by remote storage return promises; purely
12
+ * in-memory implementations may return plain values.
13
+ */
14
+ type MaybePromise<T> = T | Promise<T>;
15
+ /**
16
+ * Context of the value being tokenized.
17
+ */
18
+ interface TokenContext {
19
+ /** Category label of the value (e.g. `"email"`). */
20
+ readonly category: string;
21
+ /**
22
+ * Optional reference to the data subject the value belongs to. It is never
23
+ * stored in clear: vault-backed providers keep only a keyed digest of it, so
24
+ * that all tokens of one subject can later be erased.
25
+ */
26
+ readonly subject?: string;
27
+ }
28
+ /**
29
+ * Outcome of restoring the tokens found in a text.
30
+ */
31
+ interface RestoreResult {
32
+ /** The text with every resolvable token replaced by its original value. */
33
+ readonly text: string;
34
+ /** Number of token occurrences that were restored. */
35
+ readonly restored: number;
36
+ /** Token occurrences that could not be resolved, in document order. */
37
+ readonly unresolved: readonly string[];
38
+ }
39
+ /**
40
+ * Replaces values with tokens and, when the scheme is reversible, resolves
41
+ * tokens back to values.
42
+ *
43
+ * A provider is deterministic within its scope: the same category and value
44
+ * always yield the same token for the lifetime of a session provider, and for
45
+ * the lifetime of a key version for keyed providers.
46
+ */
47
+ interface TokenizationProvider {
48
+ /** Identifier of the scheme, recorded in audit events (e.g. `"session"`, `"keyed"`, `"sealed"`). */
49
+ readonly scheme: string;
50
+ /** Whether {@link TokenizationProvider.detokenize} can recover original values. */
51
+ readonly reversible: boolean;
52
+ /**
53
+ * A global regular expression that matches every token this provider can
54
+ * emit and nothing shorter than a whole token.
55
+ */
56
+ readonly tokenPattern: RegExp;
57
+ /**
58
+ * A regular expression that matches, anchored at the end of a string, any
59
+ * proper prefix of a token (for example `[EMAIL_00`). Stream restoration
60
+ * uses it to hold back an incomplete token until the rest arrives. When it
61
+ * is absent, streams hold back the last `maxTokenLength - 1` characters.
62
+ */
63
+ readonly partialTokenPattern?: RegExp;
64
+ /**
65
+ * Replace every token found in `text`. A provider implements it when it
66
+ * accepts more spellings of a token than `tokenPattern` matches (a session
67
+ * in lenient mode, for example); whole-text and stream restoration then go
68
+ * through it, so both accept the same spellings.
69
+ */
70
+ readonly restore?: (text: string) => MaybePromise<RestoreResult>;
71
+ /** Upper bound on the length of a token, used for stream hold-back. */
72
+ readonly maxTokenLength: number;
73
+ /** Return the token for `value`, creating it if necessary. */
74
+ readonly tokenize: (value: string, context: TokenContext) => MaybePromise<string>;
75
+ /**
76
+ * Resolve one token. Returns `undefined` when the token is unknown, erased,
77
+ * expired, fails authentication, or the scheme is irreversible.
78
+ */
79
+ readonly detokenize: (token: string) => MaybePromise<string | undefined>;
80
+ }
81
+ /**
82
+ * What a derived key is used for. Every purpose gets an independent key, so a
83
+ * key is never used for two different algorithms.
84
+ *
85
+ * - `"token-id"`: HMAC-SHA-256 key that derives deterministic token identifiers.
86
+ * - `"token-seal"`: AES-256-GCM key that encrypts original values.
87
+ * - `"subject-tag"`: HMAC-SHA-256 key that derives data-subject tags.
88
+ * - `"audit-mac"`: HMAC-SHA-256 key that authenticates audit records.
89
+ *
90
+ * Every key of a version is gone once the version is destroyed. An audit log
91
+ * must stay verifiable after data keys are shredded, so take its `audit-mac`
92
+ * key from a key ring of its own, whose versions are retired but not destroyed.
93
+ */
94
+ type KeyPurpose = "token-id" | "token-seal" | "subject-tag" | "audit-mac";
95
+ /**
96
+ * Lifecycle state of a key version.
97
+ *
98
+ * - `"active"`: used for new tokens and for decryption. Exactly one version is active.
99
+ * - `"retired"`: no longer used for new tokens; still available for decryption and verification.
100
+ * - `"destroyed"`: the key material has been discarded. Everything sealed under
101
+ * this version is permanently unrecoverable (crypto-shredding).
102
+ */
103
+ type KeyState = "active" | "retired" | "destroyed";
104
+ /**
105
+ * Secret input from which the keys of one version are derived.
106
+ */
107
+ type KeyMaterial = {
108
+ /** High-entropy secret bytes (at least 32). Used as HKDF input keying material. */
109
+ readonly kind: "raw";
110
+ readonly bytes: Uint8Array;
111
+ } | {
112
+ /** A passphrase, stretched with PBKDF2-HMAC-SHA-256 before HKDF. */
113
+ readonly kind: "passphrase";
114
+ readonly passphrase: string;
115
+ /** PBKDF2 iteration count. Defaults to 600,000 and may not be lower than 100,000. */
116
+ readonly iterations?: number;
117
+ };
118
+ /**
119
+ * Non-secret description of one key version. Safe to store next to the data.
120
+ */
121
+ interface KeyVersionInfo {
122
+ /** Version identifier: 1–16 characters from `[A-Za-z0-9]`. Embedded in tokens. */
123
+ readonly id: string;
124
+ /** Lifecycle state. */
125
+ readonly state: KeyState;
126
+ /** Creation time, milliseconds since the Unix epoch. */
127
+ readonly createdAt: number;
128
+ /** Key-derivation function applied to the material before HKDF. */
129
+ readonly kdf: "hkdf" | "pbkdf2-hkdf";
130
+ /** Salt for this version, base64url. Random, at least 16 bytes, not secret. */
131
+ readonly salt: string;
132
+ /** PBKDF2 iteration count, present when `kdf` is `"pbkdf2-hkdf"`. */
133
+ readonly iterations?: number;
134
+ }
135
+ /**
136
+ * Non-secret description of a key ring. Together with the secret material of
137
+ * each live version it is sufficient to reconstruct the ring.
138
+ */
139
+ interface KeyRingManifest {
140
+ /** Manifest format version. */
141
+ readonly v: 1;
142
+ /**
143
+ * Domain-separation label mixed into every derived key (tenant, dataset or
144
+ * environment). Two rings with different namespaces never produce the same
145
+ * token for the same value, even from identical material.
146
+ */
147
+ readonly namespace: string;
148
+ /** Identifier of the active version. */
149
+ readonly activeKeyId: string;
150
+ /** All versions, oldest first. */
151
+ readonly versions: readonly KeyVersionInfo[];
152
+ /**
153
+ * HMAC-SHA-256 (base64url) under a key of the active version. It covers the
154
+ * namespace, the active version, and every version's identifier, creation
155
+ * time, derivation parameters and salt. A manifest whose MAC does not verify
156
+ * is refused.
157
+ */
158
+ readonly mac: string;
159
+ }
160
+ /**
161
+ * A set of versioned secrets with independent, purpose-bound derived keys.
162
+ *
163
+ * A key ring is a stateful object: {@link KeyRing.rotate} and
164
+ * {@link KeyRing.destroy} change it in place.
165
+ */
166
+ interface KeyRing {
167
+ /** Identifier of the version used for new tokens. */
168
+ readonly activeKeyId: () => string;
169
+ /** The current non-secret manifest. */
170
+ readonly manifest: () => KeyRingManifest;
171
+ /**
172
+ * Derive the key of a version for a purpose. Derived keys are cached and
173
+ * non-extractable.
174
+ *
175
+ * @throws KeyManagementError When the version is unknown or destroyed.
176
+ */
177
+ readonly deriveKey: (keyId: string, purpose: KeyPurpose) => Promise<CryptoKey>;
178
+ /**
179
+ * Add a new version and make it active. The previously active version
180
+ * becomes `"retired"`.
181
+ *
182
+ * @throws KeyManagementError When `id` is already in use or malformed.
183
+ */
184
+ readonly rotate: (version: {
185
+ readonly id: string;
186
+ readonly material: KeyMaterial;
187
+ }) => Promise<void>;
188
+ /**
189
+ * Discard the material of a retired version.
190
+ *
191
+ * @throws KeyManagementError When the version is unknown or is the active version.
192
+ */
193
+ readonly destroy: (keyId: string) => void;
194
+ }
195
+ /**
196
+ * One vault entry. It holds no plaintext: the original value is sealed with
197
+ * AES-256-GCM under the `token-seal` key of `keyId`.
198
+ */
199
+ interface VaultRecord {
200
+ /** The token this record resolves. Primary key. */
201
+ readonly token: string;
202
+ /** Category label of the original value. */
203
+ readonly category: string;
204
+ /** Key version whose `token-seal` key sealed `sealed`. */
205
+ readonly keyId: string;
206
+ /** base64url of `iv (12 bytes) ‖ ciphertext ‖ tag (16 bytes)`. The token is bound as additional authenticated data. */
207
+ readonly sealed: string;
208
+ /**
209
+ * Keyed digest of the category and original value. It lets a provider tell
210
+ * a repeated value from an identifier collision without unsealing the record.
211
+ */
212
+ readonly check?: string;
213
+ /**
214
+ * The data subjects this value was tokenized for. A value shared by several
215
+ * subjects has one record and one entry per subject; erasing any of them
216
+ * deletes the record.
217
+ */
218
+ readonly subjects?: readonly SubjectReference[];
219
+ /** Creation time, milliseconds since the Unix epoch. Bound to `sealed`. */
220
+ readonly createdAt: number;
221
+ /**
222
+ * Expiry time, milliseconds since the Unix epoch. Expired records do not
223
+ * resolve. Bound to `sealed`: a record whose expiry was changed or removed
224
+ * no longer resolves.
225
+ */
226
+ readonly expiresAt?: number;
227
+ }
228
+ /**
229
+ * One data subject of a vault record. It holds no plaintext.
230
+ */
231
+ interface SubjectReference {
232
+ /** Keyed digest of the data-subject reference under the `subject-tag` key of the record's `keyId`. */
233
+ readonly tag: string;
234
+ /**
235
+ * The data-subject reference sealed under the `token-seal` key of the
236
+ * record's `keyId`. Key rotation unseals it to recompute `tag` under the new
237
+ * version, so erasure by subject keeps working after old versions are destroyed.
238
+ */
239
+ readonly sealed: string;
240
+ }
241
+ /**
242
+ * Storage for {@link VaultRecord}s. Implement this interface to keep the
243
+ * vault in Redis, a SQL table, a KV store, and so on.
244
+ */
245
+ interface TokenVault {
246
+ /** Fetch the record of a token. */
247
+ readonly get: (token: string) => MaybePromise<VaultRecord | undefined>;
248
+ /**
249
+ * Store `record` unless a record with the same token already exists.
250
+ * Returns the record that is stored after the call (the existing one or the new one).
251
+ */
252
+ readonly putIfAbsent: (record: VaultRecord) => MaybePromise<VaultRecord>;
253
+ /**
254
+ * Overwrite the record of `record.token`, but only while the stored record
255
+ * still is `expected` (same `keyId`, `sealed` and `subjects`). Returns
256
+ * `false`, and stores nothing, when the record was deleted or changed in the
257
+ * meantime. It never creates a record: an erasure that runs at the same time
258
+ * as a key rotation must win.
259
+ */
260
+ readonly replace: (record: VaultRecord, expected: VaultRecord) => MaybePromise<boolean>;
261
+ /** Delete the record of a token. Returns `true` when a record was deleted. */
262
+ readonly delete: (token: string) => MaybePromise<boolean>;
263
+ /** Enumerate all records. Required for key rotation and erasure by subject. */
264
+ readonly list: () => AsyncIterable<VaultRecord> | Iterable<VaultRecord>;
265
+ }
266
+ /**
267
+ * Proof that an erasure request was executed. It contains no personal data and
268
+ * is meant to be written to the audit log.
269
+ */
270
+ interface ErasureReceipt {
271
+ /** How the erasure was carried out. */
272
+ readonly method: "vault-delete" | "crypto-shred";
273
+ /** Number of vault records removed (`vault-delete`) or rendered unrecoverable (`crypto-shred`). */
274
+ readonly erased: number;
275
+ /** Key versions involved. */
276
+ readonly keyIds: readonly string[];
277
+ /** Keyed digest of the data-subject reference, for `vault-delete` by subject. */
278
+ readonly subjectTag?: string;
279
+ /** Completion time, milliseconds since the Unix epoch. */
280
+ readonly completedAt: number;
281
+ }
282
+
283
+ /**
284
+ * @module engine/types
285
+ * @description Contracts of the span-based anonymization engine exposed as
286
+ * `"anonyma/engine"`. This module contains types only — it has no runtime code.
287
+ *
288
+ * The engine works on **spans** (offsets into the scanned text) rather than on
289
+ * copied substrings: detectors report hits through a callback, overlap
290
+ * resolution runs on offsets, and the output is assembled in a single
291
+ * left-to-right pass.
292
+ */
293
+
294
+ /**
295
+ * A PII category label. Built-in categories autocomplete; any other string is
296
+ * accepted so that custom detectors can introduce their own categories.
297
+ */
298
+ type Category = PiiCategory | (string & {});
299
+ /**
300
+ * Callback through which a detector reports one hit.
301
+ *
302
+ * @param start - Zero-based UTF-16 offset of the first character of the hit.
303
+ * @param end - Exclusive end offset. Must be greater than `start`.
304
+ * @param confidence - Score in the range [0, 1].
305
+ */
306
+ type EmitSpan = (start: number, end: number, confidence: number) => void;
307
+ /**
308
+ * A detector for the span engine.
309
+ *
310
+ * Detectors are plain objects so that each one can be imported on its own and
311
+ * unused ones are dropped by bundlers. A detector must be pure: the same text
312
+ * always produces the same hits, and it must not keep a reference to the text.
313
+ *
314
+ * @example
315
+ * ```ts
316
+ * import { defineRegexDetector } from "anonyma/engine";
317
+ *
318
+ * export const orderIdDetector = defineRegexDetector({
319
+ * category: "order-id",
320
+ * pattern: /\bACME-\d{6}\b/g,
321
+ * confidence: 0.9,
322
+ * requires: ["ACME-"],
323
+ * });
324
+ * ```
325
+ */
326
+ interface SpanDetector {
327
+ /** Stable identifier, unique within a pipeline (e.g. `"email"`, `"acme/order-id"`). */
328
+ readonly id: string;
329
+ /** Category attached to every span this detector reports. */
330
+ readonly category: Category;
331
+ /**
332
+ * Scan `text` and report every hit through `emit`. Hits may be reported in
333
+ * any order and may overlap; the pipeline resolves overlaps.
334
+ */
335
+ readonly scan: (text: string, emit: EmitSpan) => void;
336
+ /**
337
+ * Optional cheap gate. When present and it returns `false`, `scan` is not
338
+ * called for that text. It must never return `false` for a text in which
339
+ * `scan` would report a hit.
340
+ */
341
+ readonly prefilter?: (text: string) => boolean;
342
+ /**
343
+ * Upper bound, in UTF-16 units, on the length of a hit including any
344
+ * look-around the detector needs. The chunked scanner uses it to size its
345
+ * hold-back window. Detectors without a bound fall back to the window
346
+ * configured on the stream.
347
+ */
348
+ readonly maxMatchLength?: number;
349
+ }
350
+ /**
351
+ * A resolved detection. It carries offsets only — never the matched text — so
352
+ * a list of spans is safe to log.
353
+ */
354
+ interface DetectedSpan {
355
+ /** Zero-based UTF-16 start offset in the scanned text. */
356
+ readonly start: number;
357
+ /** Exclusive end offset in the scanned text. */
358
+ readonly end: number;
359
+ /** Category of the detector that produced the span. */
360
+ readonly category: Category;
361
+ /** Confidence score in [0, 1]. */
362
+ readonly confidence: number;
363
+ /** `id` of the detector that produced the span. */
364
+ readonly detector: string;
365
+ /**
366
+ * `true` when this span is the part of a lower-priority detection that was
367
+ * left uncovered after a higher-priority overlapping detection was accepted.
368
+ */
369
+ readonly residual: boolean;
370
+ }
371
+ /**
372
+ * How overlapping detections are resolved.
373
+ *
374
+ * - `"cover"` (default): detections are accepted by priority (higher
375
+ * confidence, then longer, then earlier, then detector order). The parts of
376
+ * a losing detection that no accepted detection covers are kept as
377
+ * `residual` spans, so no detected character is ever left in the output.
378
+ * - `"legacy"`: the 1.x rule — earliest start wins, ties go to the higher
379
+ * confidence, and losing detections are dropped entirely.
380
+ */
381
+ type OverlapPolicy = "cover" | "legacy";
382
+ /**
383
+ * A rule that exempts a detected value from replacement.
384
+ *
385
+ * - `string`: the whole value must equal the string (case-insensitive unless
386
+ * `allowCaseSensitive` is set).
387
+ * - `RegExp`: tested against the value. The `g` and `y` flags are ignored.
388
+ * - function: called with the value and its span.
389
+ */
390
+ type AllowRule = string | RegExp | ((value: string, span: DetectedSpan) => boolean);
391
+ /**
392
+ * Information passed to a {@link Replacer} about the span being replaced.
393
+ */
394
+ interface ReplaceContext {
395
+ /** Category of the span. */
396
+ readonly category: Category;
397
+ /** `id` of the detector that produced the span. */
398
+ readonly detector: string;
399
+ /** Confidence score in [0, 1]. */
400
+ readonly confidence: number;
401
+ /** Start offset of the span in the input text. */
402
+ readonly start: number;
403
+ /** Exclusive end offset of the span in the input text. */
404
+ readonly end: number;
405
+ /** Zero-based position of the span among the replaced spans, in document order. */
406
+ readonly ordinal: number;
407
+ /** See {@link DetectedSpan.residual}. */
408
+ readonly residual: boolean;
409
+ }
410
+ /**
411
+ * Produces the replacement for one detected value. Replacers are always
412
+ * invoked in document order. A replacer that returns a promise can only be
413
+ * used with the asynchronous entry points.
414
+ */
415
+ type Replacer = (value: string, context: ReplaceContext) => string | Promise<string>;
416
+ /**
417
+ * Which replacer handles which category.
418
+ */
419
+ interface ReplacementPlan {
420
+ /** Replacer for every category that has no entry in `byCategory`. */
421
+ readonly fallback: Replacer;
422
+ /** Per-category replacers, keyed by category label. */
423
+ readonly byCategory?: Readonly<Record<string, Replacer>>;
424
+ }
425
+ /**
426
+ * Configuration accepted by `createPipeline()`.
427
+ */
428
+ interface PipelineOptions {
429
+ /** Detectors to run, in priority order for otherwise equal detections. */
430
+ readonly detectors: readonly SpanDetector[];
431
+ /** Replacement plan. */
432
+ readonly replace: ReplacementPlan;
433
+ /** Detections below this confidence are discarded before overlap resolution. Defaults to `0`. */
434
+ readonly minConfidence?: number;
435
+ /** Values that must be left untouched. */
436
+ readonly allow?: readonly AllowRule[];
437
+ /** When `true`, string allow rules are compared case-sensitively. Defaults to `false`. */
438
+ readonly allowCaseSensitive?: boolean;
439
+ /** Overlap resolution policy. Defaults to `"cover"`. */
440
+ readonly overlap?: OverlapPolicy;
441
+ }
442
+ /**
443
+ * A span that was replaced, with its position in the output.
444
+ */
445
+ interface AppliedSpan extends DetectedSpan {
446
+ /** Start offset of the replacement in the output text. */
447
+ readonly outStart: number;
448
+ /** Exclusive end offset of the replacement in the output text. */
449
+ readonly outEnd: number;
450
+ }
451
+ /**
452
+ * Result of a pipeline transform.
453
+ */
454
+ interface TransformResult {
455
+ /** The transformed text. */
456
+ readonly text: string;
457
+ /** Every replaced span in document order. Contains no matched text. */
458
+ readonly spans: readonly AppliedSpan[];
459
+ }
460
+ /**
461
+ * A compiled, reusable detection-and-replacement pipeline. Instances are
462
+ * immutable and safe to share between calls.
463
+ */
464
+ interface Pipeline {
465
+ /** The detectors this pipeline runs. */
466
+ readonly detectors: readonly SpanDetector[];
467
+ /**
468
+ * Detect, filter and resolve. Returns the spans that a transform would
469
+ * replace, in document order.
470
+ */
471
+ readonly scan: (text: string) => DetectedSpan[];
472
+ /** `true` when at least one span would be replaced. */
473
+ readonly test: (text: string) => boolean;
474
+ /**
475
+ * Run the replacer configured for `context.category` on one value. This is
476
+ * the building block for callers that assemble output themselves, such as
477
+ * the chunked transformer and the JSON sanitizers.
478
+ */
479
+ readonly replace: (value: string, context: ReplaceContext) => string | Promise<string>;
480
+ /**
481
+ * Transform synchronously.
482
+ *
483
+ * @throws AsyncStrategyError When a replacer returns a promise.
484
+ */
485
+ readonly transform: (text: string) => TransformResult;
486
+ /** Transform, awaiting replacers one at a time in document order. */
487
+ readonly transformAsync: (text: string) => Promise<TransformResult>;
488
+ }
489
+ /**
490
+ * Options for the chunk-boundary-safe transformer and stream.
491
+ */
492
+ interface ChunkOptions {
493
+ /**
494
+ * Hold-back window in UTF-16 units: the amount of trailing text kept
495
+ * unemitted until more input arrives, so that PII split across chunk
496
+ * boundaries is still detected. Defaults to the largest `maxMatchLength`
497
+ * among the pipeline's detectors, and to `256` for detectors without one.
498
+ */
499
+ readonly window?: number;
500
+ /**
501
+ * How many characters of new input to accumulate before scanning again.
502
+ * Larger values raise throughput when input arrives in small chunks; smaller
503
+ * values shorten the delay before output appears. Defaults to `4096`. Use
504
+ * `0` to scan on every push, as an interactive stream needs.
505
+ */
506
+ readonly batch?: number;
507
+ /**
508
+ * Longest unbroken run of printable ASCII characters that is held back
509
+ * whole. A key or a token that arrives in pieces cannot be recognised from
510
+ * its beginning, so no part of such a run is emitted before it ends.
511
+ * Defaults to `8192`; `0` turns the rule off.
512
+ */
513
+ readonly tokenLimit?: number;
514
+ }
515
+ /**
516
+ * Push-style transformer that accepts text in arbitrary chunks and returns
517
+ * transformed text as soon as it is settled.
518
+ */
519
+ interface ChunkTransformer {
520
+ /** Feed the next chunk; returns the output that is now final (possibly empty). */
521
+ readonly push: (chunk: string) => string;
522
+ /** Signal end of input; returns the remaining output. */
523
+ readonly flush: () => string;
524
+ }
525
+ /**
526
+ * Asynchronous counterpart of {@link ChunkTransformer} for pipelines with
527
+ * asynchronous replacers.
528
+ */
529
+ interface AsyncChunkTransformer {
530
+ /** Feed the next chunk; resolves to the output that is now final (possibly empty). */
531
+ readonly push: (chunk: string) => Promise<string>;
532
+ /** Signal end of input; resolves to the remaining output. */
533
+ readonly flush: () => Promise<string>;
534
+ }
535
+ /**
536
+ * A strategy in JSON-serialisable form. Secrets are never part of a spec: the
537
+ * `tokenize` and `encrypt` strategies take their provider or key from
538
+ * {@link CompileDependencies}.
539
+ */
540
+ type StrategySpec = Exclude<StrategyOptions, {
541
+ strategy: "tokenize";
542
+ } | {
543
+ strategy: "encrypt";
544
+ }> | {
545
+ readonly strategy: "tokenize";
546
+ } | {
547
+ readonly strategy: "encrypt";
548
+ };
549
+ /**
550
+ * A custom regular-expression pattern in JSON-serialisable form.
551
+ */
552
+ interface PatternSpec {
553
+ /** Regular-expression source. */
554
+ readonly source: string;
555
+ /** Regular-expression flags. The `g` flag is implied. */
556
+ readonly flags?: string;
557
+ /** Category label for matches. */
558
+ readonly category: string;
559
+ /** Confidence score in [0, 1]. Defaults to `0.85`. */
560
+ readonly confidence?: number;
561
+ }
562
+ /**
563
+ * A complete pipeline described as plain data. Because it contains no
564
+ * functions it can be stored in a configuration file, sent to a worker thread
565
+ * or passed as a tool argument, and compiled with `compilePipeline()`.
566
+ */
567
+ interface PipelineSpec {
568
+ /**
569
+ * A built-in compliance preset to start from. Its categories and strategies
570
+ * apply unless `categories`, `defaultStrategy` or `rules` override them.
571
+ */
572
+ readonly preset?: CompliancePreset;
573
+ /**
574
+ * Built-in categories to detect. Defaults to the categories of `preset`, or
575
+ * to all built-in categories when no preset is given.
576
+ */
577
+ readonly categories?: readonly PiiCategory[];
578
+ /** Use the aggressive variant of the built-in detectors. Defaults to `false`. */
579
+ readonly aggressive?: boolean;
580
+ /**
581
+ * Which built-in detectors to use.
582
+ *
583
+ * - `"precise"` (default): the validating detectors for email, SSN, IBAN,
584
+ * IPv4, IPv6 and payment cards, and the 1.x detectors for the other
585
+ * categories.
586
+ * - `"legacy"`: the 1.x detectors for every category.
587
+ */
588
+ readonly detection?: "precise" | "legacy";
589
+ /** Additional regular-expression detectors. */
590
+ readonly patterns?: readonly PatternSpec[];
591
+ /**
592
+ * Strategy for categories without a rule. Defaults to the default strategy
593
+ * of `preset`, or to `{ strategy: "redact" }` when no preset is given.
594
+ */
595
+ readonly defaultStrategy?: StrategySpec;
596
+ /** Per-category strategies, keyed by category label. They take precedence over those of `preset`. */
597
+ readonly rules?: Readonly<Record<string, StrategySpec>>;
598
+ /** See {@link PipelineOptions.minConfidence}. */
599
+ readonly minConfidence?: number;
600
+ /** Exact values to leave untouched. */
601
+ readonly allow?: readonly string[];
602
+ /** See {@link PipelineOptions.allowCaseSensitive}. */
603
+ readonly allowCaseSensitive?: boolean;
604
+ /** See {@link PipelineOptions.overlap}. */
605
+ readonly overlap?: OverlapPolicy;
606
+ }
607
+ /**
608
+ * Runtime collaborators a {@link PipelineSpec} may need but cannot carry.
609
+ */
610
+ interface CompileDependencies {
611
+ /** Provider backing the `tokenize` strategy. */
612
+ readonly tokenization?: TokenizationProvider;
613
+ /** Key material backing the `encrypt` strategy. */
614
+ readonly encryption?: EncryptOptions;
615
+ /**
616
+ * Secrets for strategies whose spec leaves them out, so that they never
617
+ * have to be written into a configuration file.
618
+ */
619
+ readonly secrets?: {
620
+ /** Pepper for `hash` strategies without one. */
621
+ readonly hashPepper?: string;
622
+ /** Seed for `pseudonymize` strategies without one. */
623
+ readonly pseudonymizeSeed?: string;
624
+ /** Seed for `synthesize` strategies without one. */
625
+ readonly synthesizeSeed?: string;
626
+ };
627
+ }
628
+
629
+ export type { AsyncChunkTransformer as A, Category as C, DetectedSpan as D, ErasureReceipt as E, KeyMaterial as K, MaybePromise as M, OverlapPolicy as O, PatternSpec as P, RestoreResult as R, StrategySpec as S, TokenizationProvider as T, VaultRecord as V, TokenContext as a, Pipeline as b, PipelineSpec as c, AppliedSpan as d, KeyRingManifest as e, KeyRing as f, TokenVault as g, Replacer as h, KeyPurpose as i, KeyState as j, KeyVersionInfo as k, SpanDetector as l, PipelineOptions as m, CompileDependencies as n, ChunkOptions as o, ChunkTransformer as p, AllowRule as q, EmitSpan as r, ReplaceContext as s, ReplacementPlan as t, TransformResult as u };