anonyma 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +273 -144
- package/README.md +427 -143
- package/dist/ai/index.cjs +522 -0
- package/dist/ai/index.cjs.map +1 -0
- package/dist/ai/index.d.cts +322 -0
- package/dist/ai/index.d.ts +322 -0
- package/dist/ai/index.js +505 -0
- package/dist/ai/index.js.map +1 -0
- package/dist/audit/index.cjs +359 -0
- package/dist/audit/index.cjs.map +1 -0
- package/dist/audit/index.d.cts +287 -0
- package/dist/audit/index.d.ts +287 -0
- package/dist/audit/index.js +340 -0
- package/dist/audit/index.js.map +1 -0
- package/dist/chunk-26IHMQHL.cjs +662 -0
- package/dist/chunk-26IHMQHL.cjs.map +1 -0
- package/dist/chunk-2F2GWGTB.js +174 -0
- package/dist/chunk-2F2GWGTB.js.map +1 -0
- package/dist/chunk-2NNMJ55L.cjs +45 -0
- package/dist/chunk-2NNMJ55L.cjs.map +1 -0
- package/dist/chunk-2YG7R4KJ.cjs +114 -0
- package/dist/chunk-2YG7R4KJ.cjs.map +1 -0
- package/dist/chunk-2ZZHLCEJ.js +237 -0
- package/dist/chunk-2ZZHLCEJ.js.map +1 -0
- package/dist/chunk-3CY6ATKS.cjs +308 -0
- package/dist/chunk-3CY6ATKS.cjs.map +1 -0
- package/dist/chunk-3D5ZCJ7R.js +268 -0
- package/dist/chunk-3D5ZCJ7R.js.map +1 -0
- package/dist/chunk-6LDAIJBL.js +103 -0
- package/dist/chunk-6LDAIJBL.js.map +1 -0
- package/dist/chunk-7HK2V5Q4.js +111 -0
- package/dist/chunk-7HK2V5Q4.js.map +1 -0
- package/dist/chunk-AAP472NG.js +177 -0
- package/dist/chunk-AAP472NG.js.map +1 -0
- package/dist/chunk-AP4JIUNW.js +42 -0
- package/dist/chunk-AP4JIUNW.js.map +1 -0
- package/dist/chunk-BBJPQPGP.js +457 -0
- package/dist/chunk-BBJPQPGP.js.map +1 -0
- package/dist/chunk-CRXRJZEV.cjs +82 -0
- package/dist/chunk-CRXRJZEV.cjs.map +1 -0
- package/dist/chunk-E3PICZYI.js +20 -0
- package/dist/chunk-E3PICZYI.js.map +1 -0
- package/dist/chunk-F7O2FA3F.cjs +1255 -0
- package/dist/chunk-F7O2FA3F.cjs.map +1 -0
- package/dist/chunk-FB56NAAH.cjs +243 -0
- package/dist/chunk-FB56NAAH.cjs.map +1 -0
- package/dist/chunk-G4AN7FND.js +1063 -0
- package/dist/chunk-G4AN7FND.js.map +1 -0
- package/dist/chunk-GS3FRH4K.js +294 -0
- package/dist/chunk-GS3FRH4K.js.map +1 -0
- package/dist/chunk-GYMG5OI3.cjs +186 -0
- package/dist/chunk-GYMG5OI3.cjs.map +1 -0
- package/dist/chunk-IHEIYZPL.cjs +301 -0
- package/dist/chunk-IHEIYZPL.cjs.map +1 -0
- package/dist/chunk-IJAMLYOT.cjs +1087 -0
- package/dist/chunk-IJAMLYOT.cjs.map +1 -0
- package/dist/chunk-ISL5B4LU.cjs +181 -0
- package/dist/chunk-ISL5B4LU.cjs.map +1 -0
- package/dist/chunk-JKW36IPT.js +179 -0
- package/dist/chunk-JKW36IPT.js.map +1 -0
- package/dist/chunk-KOCQBDI4.cjs +179 -0
- package/dist/chunk-KOCQBDI4.cjs.map +1 -0
- package/dist/chunk-OGNLB2KA.js +79 -0
- package/dist/chunk-OGNLB2KA.js.map +1 -0
- package/dist/chunk-PKHZ7CVI.js +28 -0
- package/dist/chunk-PKHZ7CVI.js.map +1 -0
- package/dist/chunk-QYD4F6T7.cjs +114 -0
- package/dist/chunk-QYD4F6T7.cjs.map +1 -0
- package/dist/chunk-RCW5IPPR.js +1288 -0
- package/dist/chunk-RCW5IPPR.js.map +1 -0
- package/dist/chunk-RMMKYHUN.cjs +35 -0
- package/dist/chunk-RMMKYHUN.cjs.map +1 -0
- package/dist/chunk-S4BJ2ADB.cjs +22 -0
- package/dist/chunk-S4BJ2ADB.cjs.map +1 -0
- package/dist/chunk-S7NH6CHY.cjs +462 -0
- package/dist/chunk-S7NH6CHY.cjs.map +1 -0
- package/dist/chunk-SIHPDZXA.js +176 -0
- package/dist/chunk-SIHPDZXA.js.map +1 -0
- package/dist/chunk-TW7PM3UJ.cjs +30 -0
- package/dist/chunk-TW7PM3UJ.cjs.map +1 -0
- package/dist/chunk-UA3EOFBS.cjs +1322 -0
- package/dist/chunk-UA3EOFBS.cjs.map +1 -0
- package/dist/chunk-VE4CCW7W.js +32 -0
- package/dist/chunk-VE4CCW7W.js.map +1 -0
- package/dist/chunk-W6RBCHYF.js +651 -0
- package/dist/chunk-W6RBCHYF.js.map +1 -0
- package/dist/chunk-WLJN7GIS.cjs +189 -0
- package/dist/chunk-WLJN7GIS.cjs.map +1 -0
- package/dist/chunk-YMLR375Z.js +1244 -0
- package/dist/chunk-YMLR375Z.js.map +1 -0
- package/dist/compliance/index.cjs +88 -0
- package/dist/compliance/index.cjs.map +1 -0
- package/dist/compliance/index.d.cts +277 -0
- package/dist/compliance/index.d.ts +277 -0
- package/dist/compliance/index.js +47 -0
- package/dist/compliance/index.js.map +1 -0
- package/dist/crypto.cjs +12 -136
- package/dist/crypto.cjs.map +1 -1
- package/dist/crypto.d.cts +4 -3
- package/dist/crypto.d.ts +4 -3
- package/dist/crypto.js +3 -137
- package/dist/crypto.js.map +1 -1
- package/dist/detectors/index.cjs +146 -1483
- package/dist/detectors/index.cjs.map +1 -1
- package/dist/detectors/index.d.cts +1 -1
- package/dist/detectors/index.d.ts +1 -1
- package/dist/detectors/index.js +3 -1449
- package/dist/detectors/index.js.map +1 -1
- package/dist/engine/index.cjs +441 -0
- package/dist/engine/index.cjs.map +1 -0
- package/dist/engine/index.d.cts +728 -0
- package/dist/engine/index.d.ts +728 -0
- package/dist/engine/index.js +189 -0
- package/dist/engine/index.js.map +1 -0
- package/dist/hash-2PSYNDMM.cjs +14 -0
- package/dist/hash-2PSYNDMM.cjs.map +1 -0
- package/dist/hash-CELLDNKN.js +5 -0
- package/dist/hash-CELLDNKN.js.map +1 -0
- package/dist/index.cjs +153 -2816
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +93 -11
- package/dist/index.d.ts +93 -11
- package/dist/index.js +13 -2791
- package/dist/index.js.map +1 -1
- package/dist/json-CKDvlRtl.d.ts +147 -0
- package/dist/json-s8ny-RCo.d.cts +147 -0
- package/dist/mcp/index.cjs +751 -0
- package/dist/mcp/index.cjs.map +1 -0
- package/dist/mcp/index.d.cts +226 -0
- package/dist/mcp/index.d.ts +226 -0
- package/dist/mcp/index.js +744 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/middleware/express.cjs +93 -0
- package/dist/middleware/express.cjs.map +1 -0
- package/dist/middleware/express.d.cts +90 -0
- package/dist/middleware/express.d.ts +90 -0
- package/dist/middleware/express.js +91 -0
- package/dist/middleware/express.js.map +1 -0
- package/dist/middleware/hono.cjs +58 -0
- package/dist/middleware/hono.cjs.map +1 -0
- package/dist/middleware/hono.d.cts +75 -0
- package/dist/middleware/hono.d.ts +75 -0
- package/dist/middleware/hono.js +56 -0
- package/dist/middleware/hono.js.map +1 -0
- package/dist/middleware/index.cjs +24 -0
- package/dist/middleware/index.cjs.map +1 -0
- package/dist/middleware/index.d.cts +106 -0
- package/dist/middleware/index.d.ts +106 -0
- package/dist/middleware/index.js +15 -0
- package/dist/middleware/index.js.map +1 -0
- package/dist/schemas.cjs +5 -5
- package/dist/schemas.cjs.map +1 -1
- package/dist/schemas.d.cts +20 -10
- package/dist/schemas.d.ts +20 -10
- package/dist/schemas.js +5 -5
- package/dist/schemas.js.map +1 -1
- package/dist/session-BdRftyZ5.d.cts +102 -0
- package/dist/session-Cs2zlNQp.d.ts +102 -0
- package/dist/stream.cjs +13 -2262
- package/dist/stream.cjs.map +1 -1
- package/dist/stream.d.cts +1 -1
- package/dist/stream.d.ts +1 -1
- package/dist/stream.js +6 -2255
- package/dist/stream.js.map +1 -1
- package/dist/types--tPm_AjY.d.ts +199 -0
- package/dist/types-0BJH_wqc.d.cts +199 -0
- package/dist/types-CPUhjvl8.d.cts +629 -0
- package/dist/types-Dtht33aq.d.ts +629 -0
- package/dist/{types-D-9HzVuy.d.cts → types-EJTj_BKY.d.cts} +38 -7
- package/dist/{types-D-9HzVuy.d.ts → types-EJTj_BKY.d.ts} +38 -7
- package/dist/types-Zt_bZvwS.d.cts +182 -0
- package/dist/types-Zt_bZvwS.d.ts +182 -0
- package/dist/validators.cjs +39 -181
- package/dist/validators.cjs.map +1 -1
- package/dist/validators.js +1 -174
- package/dist/validators.js.map +1 -1
- package/dist/vault/index.cjs +688 -0
- package/dist/vault/index.cjs.map +1 -0
- package/dist/vault/index.d.cts +385 -0
- package/dist/vault/index.d.ts +385 -0
- package/dist/vault/index.js +669 -0
- package/dist/vault/index.js.map +1 -0
- package/package.json +128 -11
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
|
|
20
|
-
- 🌍 **
|
|
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
|
|
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,
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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
|
-
// "
|
|
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",
|
|
140
|
+
{ category: "ipv4", strategy: { strategy: "redact", label: "[IP REMOVED]" } },
|
|
126
141
|
],
|
|
127
142
|
});
|
|
128
|
-
// "a
|
|
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,
|
|
169
|
+
anonymize(userData, { preset: "gdpr" }).text;
|
|
155
170
|
|
|
156
|
-
// ──
|
|
157
|
-
anonymize("NHS: 943 476 5919"
|
|
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:
|
|
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
|
-
// "
|
|
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(
|
|
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
|
-
|
|
209
|
-
|
|
210
|
-
|
|
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
|
|
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
|
|
238
|
-
|
|
239
|
-
| `email` | `alice@example.com`
|
|
240
|
-
| `phone` | `+1 (555) 867-5309`, `415.555.2671`
|
|
241
|
-
| `ssn` | `123-45-6789`
|
|
242
|
-
| `name` | `Dear Alice Smith`, `Patient: John Doe`
|
|
243
|
-
| `date-of-birth` | `1990-04-15`, `April 15, 1990`
|
|
244
|
-
| `address` | `123 Main St, Springfield, IL 62701`
|
|
245
|
-
| `passport` | `A12345678`, `P1234567`
|
|
246
|
-
| `drivers-license` | `D123-4567-8901`, `F123-456-78-910-1`
|
|
247
|
-
| `national-id` | Aadhaar, NHS number, NINO, CPF, etc.
|
|
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
|
|
252
|
-
|
|
253
|
-
| `credit-card`
|
|
254
|
-
| `iban`
|
|
255
|
-
| `bank-account`
|
|
256
|
-
| `cryptocurrency`
|
|
257
|
-
| `tax-id`
|
|
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
|
|
262
|
-
|
|
263
|
-
| `medical-record`
|
|
264
|
-
| `health-insurance
|
|
265
|
-
| `prescription`
|
|
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
|
|
270
|
-
|
|
271
|
-
| `ipv4` | `192.168.1.1`, `10.0.0.0/8`
|
|
272
|
-
| `ipv6` | `2001:0db8::8a2e:0370:7334`
|
|
273
|
-
| `url` | `https://example.com/path?q=1`
|
|
274
|
-
| `api-key` | Bearer tokens, AWS keys, GitHub PATs, etc.
|
|
275
|
-
| `social-media` | `@username`, profile URLs, handles
|
|
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
|
|
280
|
-
|
|
281
|
-
| `vin` | `1HGCM82633A004352`
|
|
282
|
-
| `license-plate` | `ABC-1234`, `AB12CDE`
|
|
283
|
-
| `tracking-number` | FedEx, UPS, USPS, DHL tracking codes
|
|
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
|
|
288
|
-
|
|
289
|
-
| `case-number`
|
|
290
|
-
| `company-registration
|
|
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
|
|
299
|
-
|
|
300
|
-
| `gdpr`
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
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); // [
|
|
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",
|
|
332
|
-
// format: "angle", // "<
|
|
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
|
-
//
|
|
444
|
-
|
|
445
|
-
|
|
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 {
|
|
506
|
+
import { compilePipeline } from "anonyma/engine";
|
|
458
507
|
|
|
459
|
-
synthesize("alice@example.com",
|
|
460
|
-
// "
|
|
508
|
+
synthesize("alice@example.com", "email", { seed: "project-y" });
|
|
509
|
+
// "olivia.williams47@example.com"
|
|
461
510
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
// "Call +1-
|
|
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,
|
|
477
|
-
verhoeff,
|
|
478
|
-
nhsMod11,
|
|
479
|
-
cpfChecksum,
|
|
480
|
-
vinChecksum,
|
|
481
|
-
deaChecksum,
|
|
482
|
-
ibanMod97,
|
|
483
|
-
ninoValid,
|
|
484
|
-
aadhaarFormat
|
|
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");
|
|
488
|
-
ibanMod97("GB82WEST12345698765432");
|
|
489
|
-
nhsMod11("943-476-5919");
|
|
536
|
+
luhn("4111111111111111"); // true
|
|
537
|
+
ibanMod97("GB82WEST12345698765432"); // true
|
|
538
|
+
nhsMod11("943-476-5919"); // true
|
|
490
539
|
```
|
|
491
540
|
|
|
492
541
|
---
|
|
493
542
|
|
|
494
|
-
##
|
|
543
|
+
## Custom Detectors
|
|
495
544
|
|
|
496
|
-
|
|
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 {
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
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
|
-
|
|
517
|
-
|
|
518
|
-
|
|
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
|
|
573
|
-
|
|
574
|
-
| `"anonyma"`
|
|
575
|
-
| `"anonyma/detectors"`
|
|
576
|
-
| `"anonyma/schemas"`
|
|
577
|
-
| `"anonyma/validators"`
|
|
578
|
-
| `"anonyma/stream"`
|
|
579
|
-
| `"anonyma/crypto"`
|
|
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
|
|