anonyma 1.1.0-beta.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 (83) hide show
  1. package/CHANGELOG.md +50 -12
  2. package/README.md +307 -81
  3. package/dist/ai/index.cjs +3 -3
  4. package/dist/ai/index.d.cts +5 -5
  5. package/dist/ai/index.d.ts +5 -5
  6. package/dist/ai/index.js +2 -2
  7. package/dist/audit/index.cjs +3 -3
  8. package/dist/audit/index.d.cts +2 -2
  9. package/dist/audit/index.d.ts +2 -2
  10. package/dist/audit/index.js +2 -2
  11. package/dist/{chunk-NTG222XM.cjs → chunk-26IHMQHL.cjs} +14 -14
  12. package/dist/chunk-26IHMQHL.cjs.map +1 -0
  13. package/dist/{chunk-7Y4X3Z3T.js → chunk-G4AN7FND.js} +3 -3
  14. package/dist/{chunk-7Y4X3Z3T.js.map → chunk-G4AN7FND.js.map} +1 -1
  15. package/dist/{chunk-2NTQ2455.js → chunk-GS3FRH4K.js} +2 -2
  16. package/dist/chunk-GS3FRH4K.js.map +1 -0
  17. package/dist/{chunk-SCWWWJJZ.cjs → chunk-IHEIYZPL.cjs} +2 -2
  18. package/dist/chunk-IHEIYZPL.cjs.map +1 -0
  19. package/dist/{chunk-UHNALA3S.cjs → chunk-IJAMLYOT.cjs} +11 -11
  20. package/dist/{chunk-UHNALA3S.cjs.map → chunk-IJAMLYOT.cjs.map} +1 -1
  21. package/dist/{chunk-IFMYNZQN.cjs → chunk-ISL5B4LU.cjs} +4 -4
  22. package/dist/{chunk-IFMYNZQN.cjs.map → chunk-ISL5B4LU.cjs.map} +1 -1
  23. package/dist/{chunk-O5LRGWLY.js → chunk-JKW36IPT.js} +3 -3
  24. package/dist/{chunk-O5LRGWLY.js.map → chunk-JKW36IPT.js.map} +1 -1
  25. package/dist/{chunk-7GPLMGZ3.js → chunk-W6RBCHYF.js} +5 -5
  26. package/dist/chunk-W6RBCHYF.js.map +1 -0
  27. package/dist/compliance/index.d.cts +5 -198
  28. package/dist/compliance/index.d.ts +5 -198
  29. package/dist/crypto.d.cts +1 -1
  30. package/dist/crypto.d.ts +1 -1
  31. package/dist/detectors/index.d.cts +1 -1
  32. package/dist/detectors/index.d.ts +1 -1
  33. package/dist/engine/index.cjs +25 -25
  34. package/dist/engine/index.d.cts +3 -3
  35. package/dist/engine/index.d.ts +3 -3
  36. package/dist/engine/index.js +2 -2
  37. package/dist/index.cjs +45 -25
  38. package/dist/index.d.cts +80 -5
  39. package/dist/index.d.ts +80 -5
  40. package/dist/index.js +4 -4
  41. package/dist/{json-CBncvuY_.d.ts → json-CKDvlRtl.d.ts} +1 -1
  42. package/dist/{json-CkGYK7l4.d.cts → json-s8ny-RCo.d.cts} +1 -1
  43. package/dist/mcp/index.cjs +8 -8
  44. package/dist/mcp/index.cjs.map +1 -1
  45. package/dist/mcp/index.js +3 -3
  46. package/dist/mcp/index.js.map +1 -1
  47. package/dist/middleware/express.cjs +4 -4
  48. package/dist/middleware/express.d.cts +3 -3
  49. package/dist/middleware/express.d.ts +3 -3
  50. package/dist/middleware/express.js +3 -3
  51. package/dist/middleware/hono.cjs +4 -4
  52. package/dist/middleware/hono.d.cts +3 -3
  53. package/dist/middleware/hono.d.ts +3 -3
  54. package/dist/middleware/hono.js +3 -3
  55. package/dist/middleware/index.cjs +4 -4
  56. package/dist/middleware/index.d.cts +3 -3
  57. package/dist/middleware/index.d.ts +3 -3
  58. package/dist/middleware/index.js +3 -3
  59. package/dist/schemas.cjs +1 -1
  60. package/dist/schemas.cjs.map +1 -1
  61. package/dist/schemas.d.cts +16 -6
  62. package/dist/schemas.d.ts +16 -6
  63. package/dist/schemas.js +1 -1
  64. package/dist/schemas.js.map +1 -1
  65. package/dist/{session-DP66OFAB.d.cts → session-BdRftyZ5.d.cts} +1 -1
  66. package/dist/{session-B4lJTMrN.d.ts → session-Cs2zlNQp.d.ts} +1 -1
  67. package/dist/stream.cjs +5 -5
  68. package/dist/stream.d.cts +1 -1
  69. package/dist/stream.d.ts +1 -1
  70. package/dist/stream.js +2 -2
  71. package/dist/types--tPm_AjY.d.ts +199 -0
  72. package/dist/types-0BJH_wqc.d.cts +199 -0
  73. package/dist/{types-_QrW2-Iq.d.cts → types-CPUhjvl8.d.cts} +2 -2
  74. package/dist/{types-Bf8AbYPJ.d.ts → types-Dtht33aq.d.ts} +2 -2
  75. package/dist/{types-ipG-_Imf.d.ts → types-EJTj_BKY.d.cts} +36 -5
  76. package/dist/{types-ipG-_Imf.d.cts → types-EJTj_BKY.d.ts} +36 -5
  77. package/dist/vault/index.d.cts +4 -4
  78. package/dist/vault/index.d.ts +4 -4
  79. package/package.json +7 -3
  80. package/dist/chunk-2NTQ2455.js.map +0 -1
  81. package/dist/chunk-7GPLMGZ3.js.map +0 -1
  82. package/dist/chunk-NTG222XM.cjs.map +0 -1
  83. package/dist/chunk-SCWWWJJZ.cjs.map +0 -1
package/CHANGELOG.md CHANGED
@@ -11,17 +11,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
11
11
 
12
12
  ---
13
13
 
14
- ## [1.1.0-beta.0] — 2026-10-04
14
+ ## [1.1.0] — 2026-10-05
15
+
16
+ Additive release. The 1.0 functions (`anonymize`, `tokenize`, `anonymizeObject`, the streams,
17
+ `sanitizeForLLM`, …) keep their behaviour, apart from the fixes listed under "Fixed". Text
18
+ processed with the `hipaa` and `ccpa` presets may have more values replaced (see "Changed").
15
19
 
16
- Pre-release, published under the `next` dist-tag: `npm install anonyma@next`.
20
+ The subpath exports `anonyma/engine`, `/vault`, `/audit`, `/compliance`, `/ai`, `/mcp` and
21
+ `/middleware` are new. They were experimental in 1.1.0-beta.0 and are stable from this release:
22
+ they follow semantic versioning like the rest of the package.
17
23
 
18
- Additive modernization. The 1.x functions (`anonymize`, `tokenize`, `anonymizeObject`,
19
- the 1.x streams, `sanitizeForLLM`, …) keep their behaviour, apart from the fixes listed
20
- under "Fixed".
24
+ Changes since 1.1.0-beta.0:
21
25
 
22
- The new subpath exports (`anonyma/engine`, `/vault`, `/audit`, `/compliance`, `/ai`,
23
- `/mcp`, `/middleware`) are **experimental** until 1.1.0 is released: their APIs may
24
- still change between pre-releases.
26
+ - The error classes added in this release are exported from `"anonyma"`. The pre-release did
27
+ not export them from any entry point, so they could not be used with `instanceof`.
28
+ - The subpath exports are no longer experimental.
29
+ - The warnings that `anonymize()` and `anonymizeAsync()` print for a strategy they do not apply
30
+ name the span engine, which applies it, instead of `anonymizeAsync()`, which does not.
31
+ - The README and the TSDoc describe the subpath modules, and say which declared options the 1.x
32
+ functions do not apply (see "Known limitations").
33
+ - Releases are published through npm trusted publishing only, and a stable version only from a
34
+ commit on `main`. The tests also run on Node.js 26.
25
35
 
26
36
  ### Added
27
37
 
@@ -57,7 +67,7 @@ still change between pre-releases.
57
67
  **`"anonyma/middleware/hono"`** — `createScrubber()`, `anonymaExpress()`, `anonymaHono()`.
58
68
  - **Presets `lgpd` and `pipeda`.**
59
69
  - **Error classes** `AsyncStrategyError`, `KeyManagementError`, `TokenVaultError`,
60
- `PolicyError`, `AuditIntegrityError`.
70
+ `PolicyError` and `AuditIntegrityError`, exported from `"anonyma"` like the others.
61
71
  - **`./package.json`** in the export map.
62
72
  - **Benchmark** (`npm run bench`, `bench/`) and labelled detector corpora
63
73
  (`tests/fixtures/corpus/`).
@@ -75,9 +85,9 @@ still change between pre-releases.
75
85
  uses the same class instances, so `instanceof AnonymaError` holds for errors thrown
76
86
  by any subpath. The `dist/` layout gains `chunk-*.js` files.
77
87
  - `PresetNotFoundError` lists the eight presets.
78
- - **Releases** are built and published by GitHub Actions from a version tag, with an npm
79
- provenance attestation, a GitHub build attestation and a CycloneDX SBOM attached to the
80
- GitHub release.
88
+ - **Releases** are built and published by GitHub Actions from a version tag, through npm
89
+ trusted publishing, with an npm provenance attestation, a GitHub build attestation and a
90
+ CycloneDX SBOM attached to the GitHub release.
81
91
  - **Development** needs Node.js 22.22 or newer. The package still supports Node.js 18:
82
92
  every release is installed and exercised on Node.js 18, 20, 22, 24 and 26.
83
93
 
@@ -94,6 +104,32 @@ still change between pre-releases.
94
104
  replaced.
95
105
  - **`synthesize()`** no longer crashes, or returns `[object Undefined]`, for a category
96
106
  named like an `Object.prototype` member (`constructor`, `toString`, …).
107
+ - The warning printed when `anonymize()` or `anonymizeAsync()` redacts a value whose rule is
108
+ `tokenize`, `encrypt` or `synthesize` advised `anonymizeAsync()`, which redacts it too.
109
+
110
+ ### Known limitations
111
+
112
+ The 1.0 documentation described behaviour that the 1.x functions do not have. The
113
+ documentation now describes what they do; the behaviour itself is unchanged:
114
+
115
+ - `anonymize()`, `anonymizeAsync()` and the functions built on them redact a value whose rule
116
+ is `tokenize`, `encrypt` or `synthesize`, with a warning, and the synchronous functions
117
+ replace a `hash` rule with a seeded pseudonym. A pipeline from `"anonyma/engine"` applies
118
+ every strategy.
119
+ - `createAnonymizer()` does not apply `plugins` (`AnonymaPlugin`).
120
+ - With `preset` set, `anonymize()` ignores `enabledCategories`; a pipeline can add categories
121
+ to a preset.
122
+ - `tokenize()` does not apply `format: "custom"` with `tokenTemplate`, nor
123
+ `deterministic: false`, and no function applies `locales`.
124
+ - `AnonymizeOptionsSchema.parse()` removes `preset`, `allowlist`, `confidenceThreshold`,
125
+ `locales` and the other options the schema does not describe.
126
+
127
+ ---
128
+
129
+ ## [1.1.0-beta.0] — 2026-10-04
130
+
131
+ Pre-release of 1.1.0, published under the `next` dist-tag. Its changes are listed under
132
+ [1.1.0], together with the changes made since.
97
133
 
98
134
  ---
99
135
 
@@ -544,5 +580,7 @@ All types are zero-cost, type-only exports (stripped by `tsc`; no runtime overhe
544
580
  - **Prettier** code formatting.
545
581
  - **MIT License**.
546
582
 
583
+ [Unreleased]: https://github.com/izaccavalheiro/anonyma/compare/v1.1.0...HEAD
584
+ [1.1.0]: https://github.com/izaccavalheiro/anonyma/releases/tag/v1.1.0
547
585
  [1.1.0-beta.0]: https://github.com/izaccavalheiro/anonyma/releases/tag/v1.1.0-beta.0
548
586
  [1.0.0]: https://github.com/izaccavalheiro/anonyma/releases/tag/v1.0.0
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
 
@@ -97,7 +102,7 @@ const { text } = anonymize("Contact alice@example.com or call 555-867-5309.");
97
102
  const { text: hashed } = await anonymizeAsync("alice@example.com", {
98
103
  defaultStrategy: { strategy: "hash", pepper: "my-pepper" },
99
104
  });
100
- // "5f3e4b3a9c1d8f2a"
105
+ // "e2a233272b2a9f2b"
101
106
 
102
107
  // ── Consistent token mapping ───────────────────────────────────────────────
103
108
  anonymize("From alice@example.com (alice@example.com)", { consistentTokens: true }).text;
@@ -125,7 +130,7 @@ anonymizeObject({
125
130
  });
126
131
  // {
127
132
  // user: { email: "[REDACTED]", phone: "[REDACTED]" },
128
- // notes: ["Call later", "[REDACTED]"],
133
+ // notes: ["Call later", "IP: [REDACTED]"],
129
134
  // }
130
135
 
131
136
  // ── Custom strategy per category ───────────────────────────────────────────
@@ -135,7 +140,7 @@ const { text: masked } = anonymize("alice@example.com and 192.168.1.1", {
135
140
  { category: "ipv4", strategy: { strategy: "redact", label: "[IP REMOVED]" } },
136
141
  ],
137
142
  });
138
- // "a***************com and [IP REMOVED]"
143
+ // "a*************com and [IP REMOVED]"
139
144
 
140
145
  // ── Format-preserving mask ─────────────────────────────────────────────────
141
146
  anonymize("123-45-6789", {
@@ -163,9 +168,9 @@ anonymize("maybe a name here", { confidenceThreshold: 0.8 }).text;
163
168
  anonymize(medicalNote, { preset: "hipaa" }).text;
164
169
  anonymize(userData, { preset: "gdpr" }).text;
165
170
 
166
- // ── Locale-aware detection ─────────────────────────────────────────────────
167
- anonymize("NHS: 943 476 5919", { locales: ["uk"] }).text;
168
- // "[REDACTED]"
171
+ // ── International identifiers ──────────────────────────────────────────────
172
+ anonymize("NHS: 943 476 5919").text;
173
+ // "NHS: [REDACTED]"
169
174
 
170
175
  // ── Anonymize object fields ─────────────────────────────────────────────────
171
176
  anonymizeRecord(
@@ -181,10 +186,9 @@ anonymizeRecord(
181
186
  const anonymizer = createAnonymizer({
182
187
  categories: ["email", "phone"],
183
188
  defaultStrategy: { strategy: "pseudonymize", seed: "my-secret" },
184
- consistentTokens: true,
185
189
  });
186
190
  anonymizer.anonymize("alice@example.com").text;
187
- // "id_3a7f1c2b9e4d0f1a"
191
+ // "id_a908a815c8327f0b"
188
192
  anonymizer.hasPII("no pii here"); // false
189
193
 
190
194
  // ── Reversible tokenization ────────────────────────────────────────────────
@@ -217,10 +221,9 @@ const original = await decrypt(ciphertext, { passphrase: "s3cr3t" });
217
221
  // "alice@example.com"
218
222
 
219
223
  // ── Synthetic data replacement ────────────────────────────────────────────
220
- anonymize("alice@example.com", {
221
- defaultStrategy: { strategy: "synthesize", seed: "project-x" },
222
- }).text;
223
- // "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)
224
227
  ```
225
228
 
226
229
  ---
@@ -240,6 +243,16 @@ anonymize("alice@example.com", {
240
243
 
241
244
  † Deterministic when `seed` is provided. ‡ Random IV per encryption; decryptable with the same key.
242
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
+
243
256
  ---
244
257
 
245
258
  ## Detected PII Categories
@@ -307,14 +320,21 @@ anonymize("alice@example.com", {
307
320
 
308
321
  Built-in presets pre-configure which categories are detected and which default strategy is applied.
309
322
 
310
- | Preset | Categories Covered | Default Strategy |
311
- | --------- | -------------------------------------------------------------------- | ---------------- |
312
- | `gdpr` | All personal, financial, healthcare, and digital identity categories | `pseudonymize` |
313
- | `hipaa` | All 18 HIPAA Safe Harbor PHI identifiers | `redact` |
314
- | `ccpa` | Consumer identifiers, financial data, online activity | `redact` |
315
- | `pci-dss` | Credit card, cardholder name, bank account, address | `mask` (last 4) |
316
- | `sox` | Financial identifiers for audit trails | `redact` |
317
- | `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.
318
338
 
319
339
  ```ts
320
340
  import { anonymize, getPreset, PRESET_REGISTRY } from "anonyma";
@@ -322,12 +342,23 @@ import { anonymize, getPreset, PRESET_REGISTRY } from "anonyma";
322
342
  // Apply a preset
323
343
  anonymize(text, { preset: "hipaa" });
324
344
 
325
- // Extend a preset — add API key detection on top of GDPR
326
- anonymize(text, { preset: "gdpr", enabledCategories: { "api-key": true } });
327
-
328
345
  // Inspect a preset's configuration
329
346
  const hipaa = getPreset("hipaa");
330
- 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
331
362
  ```
332
363
 
333
364
  ---
@@ -341,9 +372,7 @@ import { tokenize, detokenize } from "anonyma";
341
372
 
342
373
  const { text, mapping, tokens } = tokenize("alice@example.com called 555-867-5309", {
343
374
  format: "bracket", // "[EMAIL_0001]", "[PHONE_0001]" (default)
344
- // format: "angle", // "<Email_1>", "<Phone_1>" (LLM-friendly)
345
- // format: "custom", tokenTemplate: (cat, n) => `{{${cat}_${n}}}`,
346
- deterministic: true, // same value → same token (default: true)
375
+ // format: "angle", // "<EMAIL_1>", "<PHONE_1>" (LLM-friendly)
347
376
  });
348
377
  // text: "[EMAIL_0001] called [PHONE_0001]"
349
378
 
@@ -351,6 +380,9 @@ const { text: restored } = detokenize(text, mapping);
351
380
  // "alice@example.com called 555-867-5309"
352
381
  ```
353
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
+
354
386
  ---
355
387
 
356
388
  ## LLM Pipeline Helpers
@@ -452,10 +484,15 @@ const ct = await encrypt("alice@example.com", { keyBytes: myKeyBytes, encoding:
452
484
  const original = await decrypt(ciphertext, { passphrase: "s3cr3t" });
453
485
  // "alice@example.com"
454
486
 
455
- // Use as a strategy inside anonymize
456
- const { text } = await anonymizeAsync("alice@example.com", {
457
- rules: [{ category: "email", strategy: { strategy: "encrypt", passphrase: "s3cr3t" } }],
458
- });
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>"
459
496
  ```
460
497
 
461
498
  ---
@@ -466,15 +503,15 @@ Replace PII with structurally valid, format-preserving synthetic data. Determini
466
503
 
467
504
  ```ts
468
505
  import { synthesize } from "anonyma";
469
- import { anonymize } from "anonyma";
506
+ import { compilePipeline } from "anonyma/engine";
470
507
 
471
- synthesize("alice@example.com", { category: "email", seed: "project-x" });
472
- // "carol.smith42@example.com"
508
+ synthesize("alice@example.com", "email", { seed: "project-y" });
509
+ // "olivia.williams47@example.com"
473
510
 
474
- anonymize("Call 555-867-5309 or email alice@example.com", {
475
- defaultStrategy: { strategy: "synthesize", seed: "my-seed" },
476
- }).text;
477
- // "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"
478
515
  ```
479
516
 
480
517
  ---
@@ -503,39 +540,48 @@ nhsMod11("943-476-5919"); // true
503
540
 
504
541
  ---
505
542
 
506
- ## Plugin Architecture
543
+ ## Custom Detectors
507
544
 
508
- 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`:
509
547
 
510
548
  ```ts
511
- import { createAnonymizer } from "anonyma";
512
- import type { AnonymaPlugin } from "anonyma";
513
-
514
- const myPlugin: AnonymaPlugin = {
515
- name: "my-plugin",
516
- detectors: {
517
- // Override or add custom category detection
518
- "employee-id": (text) => {
519
- const matches = [];
520
- for (const m of text.matchAll(/\bEMP-\d{6}\b/g)) {
521
- matches.push({
522
- category: "employee-id",
523
- value: m[0],
524
- start: m.index!,
525
- end: m.index! + m[0].length,
526
- confidence: 0.95,
527
- });
528
- }
529
- return matches;
530
- },
531
- },
532
- };
549
+ import { anonymize } from "anonyma";
533
550
 
534
- const anonymizer = createAnonymizer({ plugins: [myPlugin] });
535
- anonymizer.anonymize("Employee EMP-001234 called.").text;
536
- // "Employee [REDACTED] called."
551
+ anonymize("Employee EMP-001234 called.", {
552
+ customPatterns: [{ pattern: /\bEMP-\d{6}\b/g, label: "[EMPLOYEE_ID]" }],
553
+ }).text;
554
+ // "Employee [EMPLOYEE_ID] called."
537
555
  ```
538
556
 
557
+ The span engine takes detectors for categories of your own, each with its own strategy:
558
+
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]"
580
+ ```
581
+
582
+ `AnonymaPlugin` and the `plugins` option of `createAnonymizer()` are declared in the types, but
583
+ `createAnonymizer()` does not apply plugins.
584
+
539
585
  ---
540
586
 
541
587
  ## AI Integration
@@ -583,6 +629,12 @@ const opts = AnonymizeOptionsSchema.parse(req.body.options);
583
629
  const result = anonymize(req.body.text as string, opts);
584
630
  ```
585
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
+
586
638
  ---
587
639
 
588
640
  ## Subpath Imports
@@ -608,32 +660,206 @@ const result = anonymize(req.body.text as string, opts);
608
660
  ## Span Engine, Tokenization, Audit and AI Modules
609
661
 
610
662
  The subpaths `anonyma/engine`, `anonyma/vault`, `anonyma/audit`, `anonyma/compliance`,
611
- `anonyma/ai`, `anonyma/mcp` and `anonyma/middleware` are a newer, separate set of APIs.
612
- They do not change the functions described above.
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.
613
666
 
614
- They ship from `1.1.0-beta.0` (`npm install anonyma@next`) and are **experimental** until
615
- 1.1.0 is released: their APIs may still change between pre-releases.
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.
616
674
 
617
675
  ```ts
618
676
  import { compilePipeline, createPipelineStream } from "anonyma/engine";
619
- import { createSessionTokenizer } from "anonyma/vault";
620
677
 
621
- // Irreversible, with a compliance preset:
622
678
  const pipeline = compilePipeline({ preset: "hipaa" });
623
- pipeline.transform("Patient jane@example.org, SSN 123-45-6789").text;
624
- // "Patient [REDACTED], SSN [REDACTED]"
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…]` |
625
700
 
626
- // Reversible tokens for an LLM round trip:
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
627
713
  const session = createSessionTokenizer();
628
714
  const tokenizing = compilePipeline(
629
715
  { defaultStrategy: { strategy: "tokenize" } },
630
716
  { tokenization: session },
631
717
  );
632
- const prompt = tokenizing.transform("Email alice@example.com").text; // "Email [EMAIL_0001]"
718
+ tokenizing.transform("Email alice@example.com").text; // "Email [EMAIL_0001]"
633
719
  session.restore("Sent to [EMAIL_0001].").text; // "Sent to alice@example.com."
634
720
 
635
- // Text that arrives in arbitrary chunks:
636
- const scrubbed = source.pipeThrough(createPipelineStream(pipeline));
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
+ }
637
863
  ```
638
864
 
639
865
  ---