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
package/README.md CHANGED
@@ -16,24 +16,29 @@
16
16
  - 🛡️ **8 anonymization strategies** — mask, redact, pseudonymize, hash (SHA-256), generalize, tokenize, encrypt (AES-GCM), synthesize
17
17
  - 🔁 **Reversible tokenization** — `tokenize()` / `detokenize()` for round-trip fidelity
18
18
  - 🤖 **LLM pipeline helpers** — `sanitizeForLLM()` / `restoreFromLLM()` for safe prompt injection with reversible tokens
19
- - 📋 **Compliance presets** — built-in `gdpr`, `hipaa`, `ccpa`, `pci-dss`, `sox`, and `ferpa` presets
20
- - 🌍 **Locale-aware detection** — locale flags for US, UK, EU, CA, AU, BR, IN, CN, JP, KR, ZA, and global
19
+ - 📋 **Compliance presets** — built-in `gdpr`, `lgpd`, `pipeda`, `hipaa`, `ccpa`, `pci-dss`, `sox` and `ferpa` presets
20
+ - 🌍 **International identifiers** — national IDs, tax IDs, passports, licence plates and company registrations of many countries, detected without configuration
21
21
  - ⚡ **Batch processing** — `anonymizeBatch()`, `anonymizeBatchAsync()`, `tokenizeBatch()`, `detectBatch()`
22
22
  - 🌊 **Streaming support** — WHATWG `TransformStream` wrappers (`createAnonymizeStream()`, `createTokenizeStream()`)
23
23
  - 🎯 **Field-level record anonymization** — dot-notation paths for nested objects
24
24
  - 🌳 **Deep object anonymization** — `anonymizeObject()` recursively cleans entire JSON trees
25
25
  - ✅ **PII presence check** — `hasPII()` with early-exit for fast gating
26
26
  - 🔎 **Aggressive mode** — expanded, permissive patterns for obfuscated PII
27
- - 🧩 **Custom patterns & detectors** — inject ad-hoc `RegExp` patterns or fully replace per-category detectors
27
+ - 🧩 **Custom patterns & detectors** — inject ad-hoc `RegExp` patterns, fully replace per-category detectors, or define detectors for your own categories
28
28
  - 🚫 **Allowlist support** — skip known-safe values by exact string or `RegExp` pattern
29
29
  - 🔢 **Confidence threshold** — filter out low-confidence matches
30
- - 🔌 **Plugin architecture** — extend detectors, strategies, and validators via `AnonymaPlugin`
31
30
  - 🔒 **Encryption** — reversible AES-GCM `encrypt()` / `decrypt()` strategy (Web Crypto API)
32
31
  - 🎭 **Synthesis** — format-preserving synthetic data replacement (deterministic, seeded)
33
32
  - ✔️ **Checksum validators** — `luhn`, `verhoeff`, `nhsMod11`, `cpfChecksum`, `vinChecksum`, `deaChecksum`, `ibanMod97`, `ninoValid`, `aadhaarFormat` via `"anonyma/validators"`
34
33
  - ⚡ **Zero runtime dependencies** — Zod is an optional peer dependency
35
34
  - 🌲 **Tree-shakeable** — import only what you use
36
35
  - 🤖 **AI-ready** — OpenAI/MCP tool definitions and Zod schemas included
36
+ - 🧵 **Span engine** — compiled pipelines that leave no detected character in the output, validating detectors for email, SSN, IBAN, IP addresses and payment cards, and streams that catch values split across chunks (`"anonyma/engine"`)
37
+ - 🔑 **Keyed tokenization** — session, keyed and sealed tokenizers, a versioned key ring with rotation, and erasure by deleting a record or shredding a key (`"anonyma/vault"`)
38
+ - 🧾 **Audit trail without personal data** — hash-chained records of what was replaced, and chain verification (`"anonyma/audit"`)
39
+ - ⚖️ **Regulation profiles** — GDPR, LGPD, PIPEDA, CCPA/CPRA, HIPAA and PCI DSS mapped to their provisions, with policy documents checked against them (`"anonyma/compliance"`)
40
+ - 💬 **LLM guard** — chat messages and JSON sanitized with reversible tokens, restored in complete and streamed model output (`"anonyma/ai"`)
41
+ - 🔌 **MCP server and HTTP middleware** — a dependency-free Model Context Protocol server, and payload scrubbing for Express, Hono and Fetch handlers (`"anonyma/mcp"`, `"anonyma/middleware"`)
37
42
  - 📦 **Dual ESM + CJS** — works everywhere Node.js ≥ 18 runs
38
43
  - 🔒 **Strict TypeScript** — no `any`, full declaration files
39
44
 
@@ -61,10 +66,20 @@ npm install zod
61
66
 
62
67
  ```ts
63
68
  import {
64
- anonymize, anonymizeAsync, detect, hasPII,
65
- anonymizeObject, anonymizeRecord, createAnonymizer,
66
- tokenize, tokenizeAsync, detokenize, sanitizeForLLM, restoreFromLLM,
67
- anonymizeBatch, anonymizeBatchAsync,
69
+ anonymize,
70
+ anonymizeAsync,
71
+ detect,
72
+ hasPII,
73
+ anonymizeObject,
74
+ anonymizeRecord,
75
+ createAnonymizer,
76
+ tokenize,
77
+ tokenizeAsync,
78
+ detokenize,
79
+ sanitizeForLLM,
80
+ restoreFromLLM,
81
+ anonymizeBatch,
82
+ anonymizeBatchAsync,
68
83
  } from "anonyma";
69
84
 
70
85
  // ── Detect PII ─────────────────────────────────────────────────────────────
@@ -87,7 +102,7 @@ const { text } = anonymize("Contact alice@example.com or call 555-867-5309.");
87
102
  const { text: hashed } = await anonymizeAsync("alice@example.com", {
88
103
  defaultStrategy: { strategy: "hash", pepper: "my-pepper" },
89
104
  });
90
- // "5f3e4b3a9c1d8f2a"
105
+ // "e2a233272b2a9f2b"
91
106
 
92
107
  // ── Consistent token mapping ───────────────────────────────────────────────
93
108
  anonymize("From alice@example.com (alice@example.com)", { consistentTokens: true }).text;
@@ -115,17 +130,17 @@ anonymizeObject({
115
130
  });
116
131
  // {
117
132
  // user: { email: "[REDACTED]", phone: "[REDACTED]" },
118
- // notes: ["Call later", "[REDACTED]"],
133
+ // notes: ["Call later", "IP: [REDACTED]"],
119
134
  // }
120
135
 
121
136
  // ── Custom strategy per category ───────────────────────────────────────────
122
137
  const { text: masked } = anonymize("alice@example.com and 192.168.1.1", {
123
138
  rules: [
124
139
  { category: "email", strategy: { strategy: "mask", keepLeading: 1, keepTrailing: 3 } },
125
- { category: "ipv4", strategy: { strategy: "redact", label: "[IP REMOVED]" } },
140
+ { category: "ipv4", strategy: { strategy: "redact", label: "[IP REMOVED]" } },
126
141
  ],
127
142
  });
128
- // "a***************com and [IP REMOVED]"
143
+ // "a*************com and [IP REMOVED]"
129
144
 
130
145
  // ── Format-preserving mask ─────────────────────────────────────────────────
131
146
  anonymize("123-45-6789", {
@@ -151,19 +166,19 @@ anonymize("maybe a name here", { confidenceThreshold: 0.8 }).text;
151
166
 
152
167
  // ── Compliance presets ─────────────────────────────────────────────────────
153
168
  anonymize(medicalNote, { preset: "hipaa" }).text;
154
- anonymize(userData, { preset: "gdpr" }).text;
169
+ anonymize(userData, { preset: "gdpr" }).text;
155
170
 
156
- // ── Locale-aware detection ─────────────────────────────────────────────────
157
- anonymize("NHS: 943 476 5919", { locales: ["uk"] }).text;
158
- // "[REDACTED]"
171
+ // ── International identifiers ──────────────────────────────────────────────
172
+ anonymize("NHS: 943 476 5919").text;
173
+ // "NHS: [REDACTED]"
159
174
 
160
175
  // ── Anonymize object fields ─────────────────────────────────────────────────
161
176
  anonymizeRecord(
162
177
  { name: "Alice", email: "alice@example.com", age: "27" },
163
178
  {
164
179
  email: { strategy: { strategy: "redact" } },
165
- age: { strategy: { strategy: "generalize" } }, // 27 → "20-29"
166
- }
180
+ age: { strategy: { strategy: "generalize" } }, // 27 → "20-29"
181
+ },
167
182
  );
168
183
  // { name: "Alice", email: "[REDACTED]", age: "20-29" }
169
184
 
@@ -171,10 +186,9 @@ anonymizeRecord(
171
186
  const anonymizer = createAnonymizer({
172
187
  categories: ["email", "phone"],
173
188
  defaultStrategy: { strategy: "pseudonymize", seed: "my-secret" },
174
- consistentTokens: true,
175
189
  });
176
190
  anonymizer.anonymize("alice@example.com").text;
177
- // "id_3a7f1c2b9e4d0f1a"
191
+ // "id_a908a815c8327f0b"
178
192
  anonymizer.hasPII("no pii here"); // false
179
193
 
180
194
  // ── Reversible tokenization ────────────────────────────────────────────────
@@ -184,7 +198,9 @@ const { text: restored } = detokenize(tokenized, mapping);
184
198
  // "alice@example.com called 555-867-5309"
185
199
 
186
200
  // ── LLM pipeline — sanitize then restore ──────────────────────────────────
187
- const { text: sanitized, mapping: llmMapping } = sanitizeForLLM("Send invoice to alice@example.com");
201
+ const { text: sanitized, mapping: llmMapping } = sanitizeForLLM(
202
+ "Send invoice to alice@example.com",
203
+ );
188
204
  // "Send invoice to [EMAIL_0001]"
189
205
  const llmResponse = await callLLM(sanitized);
190
206
  const final = restoreFromLLM(llmResponse, llmMapping);
@@ -205,89 +221,98 @@ const original = await decrypt(ciphertext, { passphrase: "s3cr3t" });
205
221
  // "alice@example.com"
206
222
 
207
223
  // ── Synthetic data replacement ────────────────────────────────────────────
208
- anonymize("alice@example.com", {
209
- defaultStrategy: { strategy: "synthesize", seed: "project-x" },
210
- }).text;
211
- // "carol.smith42@example.com" (deterministic, structurally valid)
224
+ import { synthesize } from "anonyma";
225
+ synthesize("alice@example.com", "email", { seed: "project-y" });
226
+ // "olivia.williams47@example.com" (deterministic, structurally valid)
212
227
  ```
213
228
 
214
229
  ---
215
230
 
216
231
  ## Strategies
217
232
 
218
- | Strategy | Description | Async | Deterministic | Reversible |
219
- |----------------|---------------------------------------------------------------------|:-----:|:-------------:|:----------:|
220
- | `redact` | Replace with `[REDACTED]` label (customizable) | ❌ | ✅ | ❌ |
221
- | `mask` | Replace inner chars with `*`; optional format-preserving mode | ❌ | ✅ | ❌ |
222
- | `pseudonymize` | Replace with a hex pseudonym (seeded or random) | ❌ | ✅† | ❌ |
223
- | `hash` | SHA-256 one-way hash with optional pepper (Web Crypto) | ✅ | ✅ | ❌ |
224
- | `generalize` | Replace numbers with a bucket range (e.g. `27` → `20-29`) | ❌ | ✅ | ❌ |
225
- | `tokenize` | Replace with a reversible placeholder token | ❌ | ✅ | ✅ |
226
- | `encrypt` | AES-256-GCM encryption via passphrase or raw key (Web Crypto) | ✅ | ❌‡ | ✅ |
227
- | `synthesize` | Format-preserving synthetic replacement (seeded, no real PII) | ❌ | ✅† | ❌ |
233
+ | Strategy | Description | Async | Deterministic | Reversible |
234
+ | -------------- | ------------------------------------------------------------- | :---: | :-----------: | :--------: |
235
+ | `redact` | Replace with `[REDACTED]` label (customizable) | ❌ | ✅ | ❌ |
236
+ | `mask` | Replace inner chars with `*`; optional format-preserving mode | ❌ | ✅ | ❌ |
237
+ | `pseudonymize` | Replace with a hex pseudonym (seeded or random) | ❌ | ✅† | ❌ |
238
+ | `hash` | SHA-256 one-way hash with optional pepper (Web Crypto) | ✅ | ✅ | ❌ |
239
+ | `generalize` | Replace numbers with a bucket range (e.g. `27` → `20-29`) | ❌ | ✅ | ❌ |
240
+ | `tokenize` | Replace with a reversible placeholder token | ❌ | ✅ | ✅ |
241
+ | `encrypt` | AES-256-GCM encryption via passphrase or raw key (Web Crypto) | ✅ | ❌‡ | ✅ |
242
+ | `synthesize` | Format-preserving synthetic replacement (seeded, no real PII) | ❌ | ✅† | ❌ |
228
243
 
229
244
  † Deterministic when `seed` is provided. ‡ Random IV per encryption; decryptable with the same key.
230
245
 
246
+ The strategy functions (`mask()`, `hash()`, `encrypt()`, `synthesize()`, …) implement every
247
+ strategy. As rules of `anonymize()`, `anonymizeAsync()` and the helpers built on them
248
+ (`anonymizeObject()`, `anonymizeRecord()`, `createAnonymizer()`, the batch and stream functions),
249
+ `redact`, `mask`, `pseudonymize` and `generalize` apply everywhere, and `hash` applies in the
250
+ asynchronous functions; the synchronous ones replace a hashed value with a seeded pseudonym
251
+ (`hsh_…`). Values whose rule is `tokenize`, `encrypt` or `synthesize` are redacted, with a
252
+ warning. Use `tokenize()` or `sanitizeForLLM()` for reversible tokens, and a pipeline from
253
+ `"anonyma/engine"` to apply any of the eight strategies to text
254
+ ([Span engine](#span-engine-anonymaengine)).
255
+
231
256
  ---
232
257
 
233
258
  ## Detected PII Categories
234
259
 
235
260
  ### Personal Information
236
261
 
237
- | Category | Examples | Validator / Notes |
238
- |-------------------|---------------------------------------------|-------------------------------------|
239
- | `email` | `alice@example.com` | RFC 5321 regex |
240
- | `phone` | `+1 (555) 867-5309`, `415.555.2671` | Multi-format regex |
241
- | `ssn` | `123-45-6789` | Regex + exclusions |
242
- | `name` | `Dear Alice Smith`, `Patient: John Doe` | Heuristic (greeting/title context) |
243
- | `date-of-birth` | `1990-04-15`, `April 15, 1990` | Multi-format regex |
244
- | `address` | `123 Main St, Springfield, IL 62701` | Pattern + keyword heuristic |
245
- | `passport` | `A12345678`, `P1234567` | Country-specific patterns |
246
- | `drivers-license` | `D123-4567-8901`, `F123-456-78-910-1` | Multi-state/country patterns |
247
- | `national-id` | Aadhaar, NHS number, NINO, CPF, etc. | Country-specific patterns |
262
+ | Category | Examples | Validator / Notes |
263
+ | ----------------- | --------------------------------------- | ---------------------------------- |
264
+ | `email` | `alice@example.com` | RFC 5321 regex |
265
+ | `phone` | `+1 (555) 867-5309`, `415.555.2671` | Multi-format regex |
266
+ | `ssn` | `123-45-6789` | Regex + exclusions |
267
+ | `name` | `Dear Alice Smith`, `Patient: John Doe` | Heuristic (greeting/title context) |
268
+ | `date-of-birth` | `1990-04-15`, `April 15, 1990` | Multi-format regex |
269
+ | `address` | `123 Main St, Springfield, IL 62701` | Pattern + keyword heuristic |
270
+ | `passport` | `A12345678`, `P1234567` | Country-specific patterns |
271
+ | `drivers-license` | `D123-4567-8901`, `F123-456-78-910-1` | Multi-state/country patterns |
272
+ | `national-id` | Aadhaar, NHS number, NINO, CPF, etc. | Country-specific patterns |
248
273
 
249
274
  ### Financial
250
275
 
251
- | Category | Examples | Validator / Notes |
252
- |--------------------|-------------------------------------------|-------------------------------------|
253
- | `credit-card` | `4111 1111 1111 1111` | Luhn algorithm |
254
- | `iban` | `GB82 WEST 1234 5698 7654 32` | MOD-97 (ISO 13616) |
255
- | `bank-account` | Routing + account number pairs | Pattern regex |
256
- | `cryptocurrency` | BTC, ETH, XRP wallet addresses | Format regex per chain |
257
- | `tax-id` | EIN `12-3456789`, VAT `GB123456789` | Multi-country patterns |
276
+ | Category | Examples | Validator / Notes |
277
+ | ---------------- | ----------------------------------- | ---------------------- |
278
+ | `credit-card` | `4111 1111 1111 1111` | Luhn algorithm |
279
+ | `iban` | `GB82 WEST 1234 5698 7654 32` | MOD-97 (ISO 13616) |
280
+ | `bank-account` | Routing + account number pairs | Pattern regex |
281
+ | `cryptocurrency` | BTC, ETH, XRP wallet addresses | Format regex per chain |
282
+ | `tax-id` | EIN `12-3456789`, VAT `GB123456789` | Multi-country patterns |
258
283
 
259
284
  ### Healthcare
260
285
 
261
- | Category | Examples | Validator / Notes |
262
- |-------------------|---------------------------------------------|-------------------------------------|
263
- | `medical-record` | `MRN: 1234567`, `MR#00456789` | Keyword + pattern |
264
- | `health-insurance`| `Subscriber ID`, `Group/Member #` | Pattern regex |
265
- | `prescription` | `Rx# 1234567`, DEA numbers | Pattern + DEA checksum |
286
+ | Category | Examples | Validator / Notes |
287
+ | ------------------ | --------------------------------- | ---------------------- |
288
+ | `medical-record` | `MRN: 1234567`, `MR#00456789` | Keyword + pattern |
289
+ | `health-insurance` | `Subscriber ID`, `Group/Member #` | Pattern regex |
290
+ | `prescription` | `Rx# 1234567`, DEA numbers | Pattern + DEA checksum |
266
291
 
267
292
  ### Digital Identity
268
293
 
269
- | Category | Examples | Validator / Notes |
270
- |----------------|------------------------------------------------|------------------------------|
271
- | `ipv4` | `192.168.1.1`, `10.0.0.0/8` | Octet-range regex |
272
- | `ipv6` | `2001:0db8::8a2e:0370:7334` | Regex |
273
- | `url` | `https://example.com/path?q=1` | http/https (scheme-required) |
274
- | `api-key` | Bearer tokens, AWS keys, GitHub PATs, etc. | Pattern regex per provider |
275
- | `social-media` | `@username`, profile URLs, handles | Pattern regex |
294
+ | Category | Examples | Validator / Notes |
295
+ | -------------- | ------------------------------------------ | ---------------------------- |
296
+ | `ipv4` | `192.168.1.1`, `10.0.0.0/8` | Octet-range regex |
297
+ | `ipv6` | `2001:0db8::8a2e:0370:7334` | Regex |
298
+ | `url` | `https://example.com/path?q=1` | http/https (scheme-required) |
299
+ | `api-key` | Bearer tokens, AWS keys, GitHub PATs, etc. | Pattern regex per provider |
300
+ | `social-media` | `@username`, profile URLs, handles | Pattern regex |
276
301
 
277
302
  ### Vehicles & Transportation
278
303
 
279
- | Category | Examples | Validator / Notes |
280
- |-------------------|---------------------------------------|------------------------------|
281
- | `vin` | `1HGCM82633A004352` | VIN checksum (pos 9) |
282
- | `license-plate` | `ABC-1234`, `AB12CDE` | Multi-country patterns |
283
- | `tracking-number` | FedEx, UPS, USPS, DHL tracking codes | Pattern regex per carrier |
304
+ | Category | Examples | Validator / Notes |
305
+ | ----------------- | ------------------------------------ | ------------------------- |
306
+ | `vin` | `1HGCM82633A004352` | VIN checksum (pos 9) |
307
+ | `license-plate` | `ABC-1234`, `AB12CDE` | Multi-country patterns |
308
+ | `tracking-number` | FedEx, UPS, USPS, DHL tracking codes | Pattern regex per carrier |
284
309
 
285
310
  ### Government & Legal
286
311
 
287
- | Category | Examples | Validator / Notes |
288
- |-----------------------|---------------------------------------|------------------------------|
289
- | `case-number` | `2023-CV-001234`, `CR-2022-5678` | Pattern regex |
290
- | `company-registration`| EIN, CRN, SIREN, ABN, etc. | Multi-country patterns |
312
+ | Category | Examples | Validator / Notes |
313
+ | ---------------------- | -------------------------------- | ---------------------- |
314
+ | `case-number` | `2023-CV-001234`, `CR-2022-5678` | Pattern regex |
315
+ | `company-registration` | EIN, CRN, SIREN, ABN, etc. | Multi-country patterns |
291
316
 
292
317
  ---
293
318
 
@@ -295,14 +320,21 @@ anonymize("alice@example.com", {
295
320
 
296
321
  Built-in presets pre-configure which categories are detected and which default strategy is applied.
297
322
 
298
- | Preset | Categories Covered | Default Strategy |
299
- |------------|--------------------------------------------------------------------------|-------------------|
300
- | `gdpr` | All personal, financial, healthcare, and digital identity categories | `pseudonymize` |
301
- | `hipaa` | All 18 HIPAA Safe Harbor PHI identifiers | `redact` |
302
- | `ccpa` | Consumer identifiers, financial data, online activity | `redact` |
303
- | `pci-dss` | Credit card, cardholder name, bank account, address | `mask` (last 4) |
304
- | `sox` | Financial identifiers for audit trails | `redact` |
305
- | `ferpa` | Student PII — name, SSN, DOB, address | `redact` |
323
+ | Preset | Categories Covered | Default Strategy |
324
+ | --------- | -------------------------------------------------------------------------- | -------------------------------------------------- |
325
+ | `gdpr` | Personal, financial, health and online identifiers (EU GDPR) | `pseudonymize` |
326
+ | `lgpd` | Personal data, including the CPF (Brazil, LGPD) | `redact` |
327
+ | `pipeda` | Personal information, including the Social Insurance Number (Canada) | `redact` |
328
+ | `hipaa` | The HIPAA Safe Harbor identifiers that can be detected in text | `redact` |
329
+ | `ccpa` | Consumer identifiers, financial and health data, online activity, API keys | `redact` |
330
+ | `pci-dss` | Card and bank account numbers, cardholder name and contact details | `redact`; card and account numbers keep the last 4 |
331
+ | `sox` | Financial and corporate officer identifiers for audit trails | `redact` |
332
+ | `ferpa` | Student PII — name, contact details, date of birth, SSN, national ID | `redact` |
333
+
334
+ A preset selects what the library can detect. Some data that a regulation names has no detector —
335
+ for HIPAA, ZIP codes, dates other than birth dates, device identifiers and photographs; for PCI DSS,
336
+ card verification codes. `REGULATIONS[id].gaps` from `"anonyma/compliance"` lists them, with the
337
+ provision that names each one.
306
338
 
307
339
  ```ts
308
340
  import { anonymize, getPreset, PRESET_REGISTRY } from "anonyma";
@@ -310,12 +342,23 @@ import { anonymize, getPreset, PRESET_REGISTRY } from "anonyma";
310
342
  // Apply a preset
311
343
  anonymize(text, { preset: "hipaa" });
312
344
 
313
- // Extend a preset — add API key detection on top of GDPR
314
- anonymize(text, { preset: "gdpr", enabledCategories: { "api-key": true } });
315
-
316
345
  // Inspect a preset's configuration
317
346
  const hipaa = getPreset("hipaa");
318
- console.log(hipaa.categories); // [...18 categories...]
347
+ console.log(hipaa.categories); // ["name", "address", "date-of-birth", "phone", ...]
348
+ ```
349
+
350
+ To add a category to a preset, compile a pipeline from `"anonyma/engine"` with the preset's
351
+ categories and yours — `anonymize()` uses the preset's categories when `preset` is set:
352
+
353
+ ```ts
354
+ import { compilePipeline } from "anonyma/engine";
355
+
356
+ const gdprWithKeys = compilePipeline({
357
+ preset: "gdpr",
358
+ categories: [...getPreset("gdpr").categories, "api-key"],
359
+ });
360
+ gdprWithKeys.transform("Key AKIAIOSFODNN7EXAMPLE, mail alice@example.com").text;
361
+ // "Key id_…, mail id_…" — random pseudonyms, since the preset sets no seed
319
362
  ```
320
363
 
321
364
  ---
@@ -328,10 +371,8 @@ console.log(hipaa.categories); // [...18 categories...]
328
371
  import { tokenize, detokenize } from "anonyma";
329
372
 
330
373
  const { text, mapping, tokens } = tokenize("alice@example.com called 555-867-5309", {
331
- format: "bracket", // "[EMAIL_0001]", "[PHONE_0001]" (default)
332
- // format: "angle", // "<Email_1>", "<Phone_1>" (LLM-friendly)
333
- // format: "custom", tokenTemplate: (cat, n) => `{{${cat}_${n}}}`,
334
- deterministic: true, // same value → same token (default: true)
374
+ format: "bracket", // "[EMAIL_0001]", "[PHONE_0001]" (default)
375
+ // format: "angle", // "<EMAIL_1>", "<PHONE_1>" (LLM-friendly)
335
376
  });
336
377
  // text: "[EMAIL_0001] called [PHONE_0001]"
337
378
 
@@ -339,6 +380,9 @@ const { text: restored } = detokenize(text, mapping);
339
380
  // "alice@example.com called 555-867-5309"
340
381
  ```
341
382
 
383
+ Identical values share a token. `TokenizeOptions` also declares `format: "custom"` with
384
+ `tokenTemplate`, `deterministic: false` and `locales`, which `tokenize()` does not apply.
385
+
342
386
  ---
343
387
 
344
388
  ## LLM Pipeline Helpers
@@ -407,7 +451,7 @@ import {
407
451
  // Anonymize line by line
408
452
  const readable = ReadableStream.from(lines);
409
453
  const anonymized = readable.pipeThrough(
410
- createAnonymizeStream({ defaultStrategy: { strategy: "mask" } })
454
+ createAnonymizeStream({ defaultStrategy: { strategy: "mask" } }),
411
455
  );
412
456
  for await (const { text } of anonymized) {
413
457
  process.stdout.write(text + "\n");
@@ -440,10 +484,15 @@ const ct = await encrypt("alice@example.com", { keyBytes: myKeyBytes, encoding:
440
484
  const original = await decrypt(ciphertext, { passphrase: "s3cr3t" });
441
485
  // "alice@example.com"
442
486
 
443
- // Use as a strategy inside anonymize
444
- const { text } = await anonymizeAsync("alice@example.com", {
445
- rules: [{ category: "email", strategy: { strategy: "encrypt", passphrase: "s3cr3t" } }],
446
- });
487
+ // Encrypt what a pipeline detects; the key is passed apart from the specification
488
+ import { compilePipeline } from "anonyma/engine";
489
+
490
+ const pipeline = compilePipeline(
491
+ { rules: { email: { strategy: "encrypt" } } },
492
+ { encryption: { passphrase: "s3cr3t" } },
493
+ );
494
+ const { text } = await pipeline.transformAsync("Mail alice@example.com");
495
+ // "Mail base64:<iv>:<ciphertext>"
447
496
  ```
448
497
 
449
498
  ---
@@ -454,15 +503,15 @@ Replace PII with structurally valid, format-preserving synthetic data. Determini
454
503
 
455
504
  ```ts
456
505
  import { synthesize } from "anonyma";
457
- import { anonymize } from "anonyma";
506
+ import { compilePipeline } from "anonyma/engine";
458
507
 
459
- synthesize("alice@example.com", { category: "email", seed: "project-x" });
460
- // "carol.smith42@example.com"
508
+ synthesize("alice@example.com", "email", { seed: "project-y" });
509
+ // "olivia.williams47@example.com"
461
510
 
462
- anonymize("Call 555-867-5309 or email alice@example.com", {
463
- defaultStrategy: { strategy: "synthesize", seed: "my-seed" },
464
- }).text;
465
- // "Call +1-312-408-7291 or email bob.jones15@test.org"
511
+ compilePipeline({ defaultStrategy: { strategy: "synthesize", seed: "project-z" } }).transform(
512
+ "Call 555-867-5309 or email alice@example.com",
513
+ ).text;
514
+ // "Call +1-297-841-6744 or email wendy.clark9@example.com"
466
515
  ```
467
516
 
468
517
  ---
@@ -473,51 +522,66 @@ Standalone checksum and format validators are exported from `"anonyma/validators
473
522
 
474
523
  ```ts
475
524
  import {
476
- luhn, // Luhn (ISO/IEC 7812) — credit cards
477
- verhoeff, // Verhoeff — Indian Aadhaar
478
- nhsMod11, // NHS mod-11 — UK NHS numbers
479
- cpfChecksum, // CPF — Brazilian tax IDs
480
- vinChecksum, // VIN position-9 check digit
481
- deaChecksum, // DEA number check — US prescriptions
482
- ibanMod97, // MOD-97 — IBAN (ISO 13616)
483
- ninoValid, // NINO format — UK National Insurance
484
- aadhaarFormat,// Aadhaar format — Indian national ID
525
+ luhn, // Luhn (ISO/IEC 7812) — credit cards
526
+ verhoeff, // Verhoeff — Indian Aadhaar
527
+ nhsMod11, // NHS mod-11 — UK NHS numbers
528
+ cpfChecksum, // CPF — Brazilian tax IDs
529
+ vinChecksum, // VIN position-9 check digit
530
+ deaChecksum, // DEA number check — US prescriptions
531
+ ibanMod97, // MOD-97 — IBAN (ISO 13616)
532
+ ninoValid, // NINO format — UK National Insurance
533
+ aadhaarFormat, // Aadhaar format — Indian national ID
485
534
  } from "anonyma/validators";
486
535
 
487
- luhn("4111111111111111"); // true
488
- ibanMod97("GB82WEST12345698765432"); // true
489
- nhsMod11("943-476-5919"); // true
536
+ luhn("4111111111111111"); // true
537
+ ibanMod97("GB82WEST12345698765432"); // true
538
+ nhsMod11("943-476-5919"); // true
490
539
  ```
491
540
 
492
541
  ---
493
542
 
494
- ## Plugin Architecture
543
+ ## Custom Detectors
495
544
 
496
- Extend anonyma with custom detectors, strategies, and validators using `AnonymaPlugin`.
545
+ Replace the detector of a built-in category with `customDetectors`, or catch values of your own
546
+ format with `customPatterns`:
497
547
 
498
548
  ```ts
499
- import { createAnonymizer } from "anonyma";
500
- import type { AnonymaPlugin } from "anonyma";
501
-
502
- const myPlugin: AnonymaPlugin = {
503
- name: "my-plugin",
504
- detectors: {
505
- // Override or add custom category detection
506
- "employee-id": (text) => {
507
- const matches = [];
508
- for (const m of text.matchAll(/\bEMP-\d{6}\b/g)) {
509
- matches.push({ category: "employee-id", value: m[0], start: m.index!, end: m.index! + m[0].length, confidence: 0.95 });
510
- }
511
- return matches;
512
- },
513
- },
514
- };
549
+ import { anonymize } from "anonyma";
550
+
551
+ anonymize("Employee EMP-001234 called.", {
552
+ customPatterns: [{ pattern: /\bEMP-\d{6}\b/g, label: "[EMPLOYEE_ID]" }],
553
+ }).text;
554
+ // "Employee [EMPLOYEE_ID] called."
555
+ ```
556
+
557
+ The span engine takes detectors for categories of your own, each with its own strategy:
515
558
 
516
- const anonymizer = createAnonymizer({ plugins: [myPlugin] });
517
- anonymizer.anonymize("Employee EMP-001234 called.").text;
518
- // "Employee [REDACTED] called."
559
+ ```ts
560
+ import {
561
+ constant,
562
+ createPipeline,
563
+ defineRegexDetector,
564
+ emailDetector,
565
+ redactWith,
566
+ } from "anonyma/engine";
567
+
568
+ const employeeId = defineRegexDetector({
569
+ category: "employee-id",
570
+ pattern: /\bEMP-\d{6}\b/g,
571
+ confidence: 0.95,
572
+ requires: ["EMP-"], // skip texts that cannot contain a hit
573
+ });
574
+ const pipeline = createPipeline({
575
+ detectors: [emailDetector, employeeId],
576
+ replace: { fallback: redactWith(), byCategory: { "employee-id": constant("[EMPLOYEE]") } },
577
+ });
578
+ pipeline.transform("EMP-001234 wrote from alice@example.com").text;
579
+ // "[EMPLOYEE] wrote from [REDACTED]"
519
580
  ```
520
581
 
582
+ `AnonymaPlugin` and the `plugins` option of `createAnonymizer()` are declared in the types, but
583
+ `createAnonymizer()` does not apply plugins.
584
+
521
585
  ---
522
586
 
523
587
  ## AI Integration
@@ -565,18 +629,238 @@ const opts = AnonymizeOptionsSchema.parse(req.body.options);
565
629
  const result = anonymize(req.body.text as string, opts);
566
630
  ```
567
631
 
632
+ The schema covers `rules`, `defaultStrategy`, `customPatterns`, `enabledCategories`,
633
+ `globalReplacement`, `consistentTokens`, `aggressive` and `includeMatches`. `parse()` removes the
634
+ other options, such as `preset`, `allowlist`, `confidenceThreshold` and `locales`. To accept a
635
+ whole pipeline from untrusted input, check a policy document with `parsePolicy()` from
636
+ `"anonyma/compliance"` instead.
637
+
568
638
  ---
569
639
 
570
640
  ## Subpath Imports
571
641
 
572
- | Import path | Contents |
573
- |--------------------------|---------------------------------------------------------------------------|
574
- | `"anonyma"` | Core API — no Zod dependency |
575
- | `"anonyma/detectors"` | All detectors + `DETECTOR_REGISTRY` + `AGGRESSIVE_DETECTOR_REGISTRY` |
576
- | `"anonyma/schemas"` | Zod schemas, JSON schemas, AI/MCP tool definitions (requires `zod`) |
577
- | `"anonyma/validators"` | Standalone checksum validators (Luhn, MOD-97, NHS, VIN, etc.) |
578
- | `"anonyma/stream"` | WHATWG `TransformStream` wrappers (Node ≥ 18 / browsers) |
579
- | `"anonyma/crypto"` | Low-level Web Crypto utilities |
642
+ | Import path | Contents |
643
+ | ---------------------- | ------------------------------------------------------------------------------------------ |
644
+ | `"anonyma"` | Core API — no Zod dependency |
645
+ | `"anonyma/detectors"` | All detectors + `DETECTOR_REGISTRY` + `AGGRESSIVE_DETECTOR_REGISTRY` |
646
+ | `"anonyma/schemas"` | Zod schemas, JSON schemas, AI/MCP tool definitions (requires `zod`) |
647
+ | `"anonyma/validators"` | Standalone checksum validators (Luhn, MOD-97, NHS, VIN, etc.) |
648
+ | `"anonyma/stream"` | WHATWG `TransformStream` wrappers (Node ≥ 18 / browsers) |
649
+ | `"anonyma/crypto"` | Low-level Web Crypto utilities |
650
+ | `"anonyma/engine"` | Span engine: `createPipeline`, `compilePipeline`, detectors, replacers, chunk-safe streams |
651
+ | `"anonyma/vault"` | Session, keyed and sealed tokenizers; key ring with rotation; token vault |
652
+ | `"anonyma/audit"` | Hash-chained audit logger without personal data; chain verification |
653
+ | `"anonyma/compliance"` | Regulation profiles with citations, policy parser, erasure planning |
654
+ | `"anonyma/ai"` | Structure-preserving JSON and chat-message redaction; stream restoration |
655
+ | `"anonyma/mcp"` | MCP tool and resource declarations; dependency-free MCP server |
656
+ | `"anonyma/middleware"` | HTTP payload scrubber; adapters in `/express` and `/hono` |
657
+
658
+ ---
659
+
660
+ ## Span Engine, Tokenization, Audit and AI Modules
661
+
662
+ The subpaths `anonyma/engine`, `anonyma/vault`, `anonyma/audit`, `anonyma/compliance`,
663
+ `anonyma/ai`, `anonyma/mcp` and `anonyma/middleware` were added in 1.1.0. They are a second,
664
+ span-based API next to the functions above, which keep their 1.0 behaviour, and they follow
665
+ semantic versioning like the rest of the package.
666
+
667
+ ### Span engine (`"anonyma/engine"`)
668
+
669
+ A pipeline is compiled once and reused. Detectors report offsets, overlapping detections are
670
+ resolved so that no detected character is left in the output, and the output is assembled in one
671
+ pass. Email addresses, US SSNs, IBANs, IP addresses and card numbers are found by validating
672
+ detectors (checksums, issuer ranges, allocation rules) that reject look-alikes such as version
673
+ strings; the other categories use the 1.0 detectors.
674
+
675
+ ```ts
676
+ import { compilePipeline, createPipelineStream } from "anonyma/engine";
677
+
678
+ const pipeline = compilePipeline({ preset: "hipaa" });
679
+ const { text, spans } = pipeline.transform("Patient jane@example.org, SSN 123-45-6789");
680
+ // text: "Patient [REDACTED], SSN [REDACTED]"
681
+ // spans: offsets, categories and detectors, never the detected text
682
+
683
+ // Text that arrives in arbitrary chunks, with values split between them:
684
+ const scrubbed = source.pipeThrough(createPipelineStream(pipeline));
685
+ ```
686
+
687
+ `compilePipeline()` takes plain data — a preset, categories, strategies, patterns — so a pipeline
688
+ can live in a configuration file; keys and seeds are passed next to it, never inside it.
689
+ `createPipeline()` builds one from detectors and replacers imported one by one, so that bundlers
690
+ keep only those.
691
+
692
+ ### Keyed tokenization (`"anonyma/vault"`)
693
+
694
+ | Tokenizer | Reversible | Same value, same token | Token |
695
+ | ---------------------------------------- | ---------------------- | ----------------------------------- | ------------------------- |
696
+ | `createSessionTokenizer()` | within the session | within the session | `[EMAIL_0001]` |
697
+ | `createKeyedTokenizer()` with a vault | through the vault | across calls and processes, per key | `[EMAIL_k1_7ZK3M9QW2ABC]` |
698
+ | `createKeyedTokenizer()` without a vault | no | across calls and processes, per key | `[EMAIL_k1_7ZK3M9QW2ABC]` |
699
+ | `createSealedTokenizer()` | with the key, no vault | across calls and processes, per key | `[EMAIL_k1.5wq…]` |
700
+
701
+ ```ts
702
+ import { compilePipeline } from "anonyma/engine";
703
+ import {
704
+ createKeyedTokenizer,
705
+ createKeyRing,
706
+ createMemoryVault,
707
+ createSessionTokenizer,
708
+ generateKeyMaterial,
709
+ restoreTokens,
710
+ } from "anonyma/vault";
711
+
712
+ // One conversation: tokens that only this session can restore
713
+ const session = createSessionTokenizer();
714
+ const tokenizing = compilePipeline(
715
+ { defaultStrategy: { strategy: "tokenize" } },
716
+ { tokenization: session },
717
+ );
718
+ tokenizing.transform("Email alice@example.com").text; // "Email [EMAIL_0001]"
719
+ session.restore("Sent to [EMAIL_0001].").text; // "Sent to alice@example.com."
720
+
721
+ // Stable tokens across processes, restorable through a vault
722
+ const keyring = await createKeyRing({
723
+ namespace: "crm",
724
+ keys: [{ id: "k1", material: await generateKeyMaterial() }],
725
+ });
726
+ const keyed = createKeyedTokenizer({ keyring, vault: createMemoryVault() });
727
+ const crm = compilePipeline({ defaultStrategy: { strategy: "tokenize" } }, { tokenization: keyed });
728
+ const { text } = await crm.transformAsync("Mail alice@example.com"); // "Mail [EMAIL_k1_Y5DMH9ED2DTF]"
729
+ (await restoreTokens(text, keyed)).text; // "Mail alice@example.com"
730
+ ```
731
+
732
+ Keys are versioned and derived per purpose with HKDF. `keyring.rotate()` adds a version,
733
+ `rewrapVault()` re-seals the vault under it without changing any token, and `shredKey()` destroys a
734
+ version so that nothing sealed under it can be recovered, not even from a backup of the vault.
735
+ `forgetSubject()` deletes the records of one data subject. `createMemoryVault()` is the reference
736
+ implementation of the `TokenVault` interface; implement it over your own database.
737
+
738
+ ### Audit trail (`"anonyma/audit"`)
739
+
740
+ A record says what was replaced — fields, categories, detectors, rules, counts — and never what the
741
+ data was. Each record's hash covers its predecessor, so removing, reordering or editing a record
742
+ breaks the chain; with a key, the hash is an HMAC. When a sink fails, the logger stops instead of
743
+ leaving a gap.
744
+
745
+ ```ts
746
+ import { createAuditLogger, memorySink, summarizeSpans, verifyAuditChain } from "anonyma/audit";
747
+
748
+ const sink = memorySink();
749
+ const audit = createAuditLogger({ sinks: [sink] });
750
+ await audit.record({
751
+ operation: "anonymize",
752
+ policy: { id: "hipaa" },
753
+ fields: summarizeSpans(spans, { rule: "redact" }),
754
+ });
755
+ (await verifyAuditChain(sink.records())).ok; // true
756
+ ```
757
+
758
+ ### Regulation profiles and policies (`"anonyma/compliance"`)
759
+
760
+ `REGULATIONS` maps GDPR, LGPD, PIPEDA, CCPA/CPRA, HIPAA and PCI DSS to the categories they bring
761
+ into scope, the provision behind each one, the protection a replacement must give, and the data
762
+ they name that no detector covers. A policy document extends regulations and is checked against
763
+ them:
764
+
765
+ ```ts
766
+ import { compilePipeline } from "anonyma/engine";
767
+ import { parsePolicy, policyToSpec } from "anonyma/compliance";
768
+
769
+ const policy = parsePolicy({ version: 1, id: "clinic", extends: ["hipaa", "gdpr"] });
770
+ const clinic = compilePipeline(policyToSpec(policy));
771
+
772
+ parsePolicy({
773
+ version: 1,
774
+ id: "clinic",
775
+ extends: ["hipaa"],
776
+ rules: { email: { strategy: "mask", keepLeading: 3 } },
777
+ });
778
+ // throws PolicyError: /rules/email "mask" is not sufficient for "email" under HIPAA …
779
+ // (45 CFR § 164.514(b)(2)(i)(F))
780
+ ```
781
+
782
+ The profiles describe technical measures. They are not legal advice, and they do not make a system
783
+ compliant on their own.
784
+
785
+ ### LLM guard and JSON (`"anonyma/ai"`)
786
+
787
+ ```ts
788
+ import { createLlmGuard, sanitizeJson } from "anonyma/ai";
789
+
790
+ const exchange = createLlmGuard().begin();
791
+ const { messages } = exchange.sanitizeMessages([
792
+ { role: "user", content: "Email alice@example.com" },
793
+ ]);
794
+ // messages[0].content: "Email [EMAIL_0001]"; the mapping never leaves the process
795
+ const reply = await callLLM(messages); // "Sent to [EMAIL_0001]."
796
+ exchange.restoreText(reply).text; // "Sent to alice@example.com."
797
+ // Streamed output: stream.pipeThrough(exchange.restoreStream()), tokens split across chunks too
798
+
799
+ sanitizeJson({ user: { email: "alice@example.com" }, id: 7 }, { pipeline }).value;
800
+ // { user: { email: "[REDACTED]" }, id: 7 } — same shape, sanitized strings
801
+ ```
802
+
803
+ `toLanguageModelMiddleware()` adapts a guard to the middleware of the Vercel AI SDK
804
+ (`wrapLanguageModel()`). It is typed structurally and tested against stand-ins for the SDK, so check
805
+ it against the SDK version you use.
806
+
807
+ ### MCP server (`"anonyma/mcp"`)
808
+
809
+ A Model Context Protocol server without dependencies. Its tools are `anonyma_detect`,
810
+ `anonyma_anonymize`, `anonyma_tokenize` and `anonyma_check_policy`, plus `anonyma_detokenize` when
811
+ the operator enables it (`allowDetokenize`). The values behind tokens stay in server memory, and
812
+ `anonyma_detect` reports positions, not the detected text.
813
+
814
+ ```js
815
+ // anonyma-mcp.mjs — register with: claude mcp add anonyma -- node anonyma-mcp.mjs
816
+ import { createMcpServer, serveStdio } from "anonyma/mcp";
817
+
818
+ await serveStdio(createMcpServer(), {
819
+ input: process.stdin,
820
+ write: (line) => void process.stdout.write(line),
821
+ });
822
+ ```
823
+
824
+ ### HTTP middleware (`"anonyma/middleware"`)
825
+
826
+ ```ts
827
+ import express from "express";
828
+ import { anonymaExpress } from "anonyma/middleware/express";
829
+
830
+ const app = express();
831
+ app.use(express.json());
832
+ // Scrubs responses and, with `request: true`, the parsed request bodies
833
+ app.use("/support", anonymaExpress({ spec: { preset: "gdpr" }, request: true }));
834
+ ```
835
+
836
+ `anonymaHono()` from `"anonyma/middleware/hono"` does the same for Hono, on every runtime Hono
837
+ supports. `createScrubber()` from `"anonyma/middleware"` scrubs JSON values, text and Fetch API
838
+ responses directly. Neither adapter depends on its framework.
839
+
840
+ ---
841
+
842
+ ## Errors
843
+
844
+ The library's errors are `AnonymaError`s with a machine-readable `code`. The classes are exported
845
+ from `"anonyma"`, including those thrown by the subpaths: `ValidationError`,
846
+ `UnsupportedStrategyError`, `UnknownCategoryError`, `CryptoNotAvailableError`, `EncryptionError`,
847
+ `PresetNotFoundError`, `AllowlistMatchError`, `BatchProcessingError`, `AsyncStrategyError`,
848
+ `KeyManagementError`, `TokenVaultError`, `PolicyError` and `AuditIntegrityError`.
849
+
850
+ ```ts
851
+ import { AnonymaError, PolicyError } from "anonyma";
852
+ import { parsePolicy } from "anonyma/compliance";
853
+
854
+ try {
855
+ parsePolicy(document);
856
+ } catch (error) {
857
+ if (error instanceof PolicyError) {
858
+ for (const issue of error.issues) console.error(issue.path, issue.message);
859
+ } else if (error instanceof AnonymaError) {
860
+ console.error(error.code, error.message);
861
+ }
862
+ }
863
+ ```
580
864
 
581
865
  ---
582
866