anonyma 1.0.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 +457 -0
- package/LICENSE +21 -0
- package/README.md +605 -0
- package/dist/crypto.cjs +142 -0
- package/dist/crypto.cjs.map +1 -0
- package/dist/crypto.d.cts +51 -0
- package/dist/crypto.d.ts +51 -0
- package/dist/crypto.js +139 -0
- package/dist/crypto.js.map +1 -0
- package/dist/detectors/index.cjs +1487 -0
- package/dist/detectors/index.cjs.map +1 -0
- package/dist/detectors/index.d.cts +754 -0
- package/dist/detectors/index.d.ts +754 -0
- package/dist/detectors/index.js +1451 -0
- package/dist/detectors/index.js.map +1 -0
- package/dist/index.cjs +2877 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +772 -0
- package/dist/index.d.ts +772 -0
- package/dist/index.js +2850 -0
- package/dist/index.js.map +1 -0
- package/dist/schemas.cjs +361 -0
- package/dist/schemas.cjs.map +1 -0
- package/dist/schemas.d.cts +1031 -0
- package/dist/schemas.d.ts +1031 -0
- package/dist/schemas.js +341 -0
- package/dist/schemas.js.map +1 -0
- package/dist/stream.cjs +2315 -0
- package/dist/stream.cjs.map +1 -0
- package/dist/stream.d.cts +76 -0
- package/dist/stream.d.ts +76 -0
- package/dist/stream.js +2311 -0
- package/dist/stream.js.map +1 -0
- package/dist/types-D-9HzVuy.d.cts +553 -0
- package/dist/types-D-9HzVuy.d.ts +553 -0
- package/dist/validators.cjs +186 -0
- package/dist/validators.cjs.map +1 -0
- package/dist/validators.d.cts +136 -0
- package/dist/validators.d.ts +136 -0
- package/dist/validators.js +176 -0
- package/dist/validators.js.map +1 -0
- package/package.json +158 -0
|
@@ -0,0 +1,553 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module types
|
|
3
|
+
* @description Core TypeScript types and interfaces for the anonyma library.
|
|
4
|
+
*/
|
|
5
|
+
/**
|
|
6
|
+
* All PII (Personally Identifiable Information) categories that anonyma can detect.
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* `"name"` detection is heuristic — it catches names that follow greeting keywords,
|
|
10
|
+
* title prefixes (Mr./Dr./etc.), and context clues (patient, client, defendant, etc.).
|
|
11
|
+
* It is not an NLP-based name recogniser and may miss names that appear without
|
|
12
|
+
* any of these context signals.
|
|
13
|
+
*/
|
|
14
|
+
type PiiCategory = "email" | "phone" | "ssn" | "credit-card" | "ipv4" | "ipv6" | "url" | "iban" | "date-of-birth" | "name" | "address" | "passport" | "drivers-license" | "national-id" | "bank-account" | "cryptocurrency" | "tax-id" | "medical-record" | "health-insurance" | "prescription" | "api-key" | "social-media" | "vin" | "license-plate" | "tracking-number" | "case-number" | "company-registration";
|
|
15
|
+
/**
|
|
16
|
+
* A detected PII entity within a text string.
|
|
17
|
+
*/
|
|
18
|
+
interface PiiMatch {
|
|
19
|
+
/** The category of PII detected. */
|
|
20
|
+
readonly category: PiiCategory;
|
|
21
|
+
/** The verbatim matched value. */
|
|
22
|
+
readonly value: string;
|
|
23
|
+
/** Zero-based start index within the source string. */
|
|
24
|
+
readonly start: number;
|
|
25
|
+
/** Zero-based exclusive end index within the source string. */
|
|
26
|
+
readonly end: number;
|
|
27
|
+
/** Confidence score in the range [0, 1]. */
|
|
28
|
+
readonly confidence: number;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* An ad-hoc regex pattern that participates in PII detection and anonymization
|
|
32
|
+
* alongside the built-in detectors.
|
|
33
|
+
*
|
|
34
|
+
* @example
|
|
35
|
+
* ```ts
|
|
36
|
+
* const pattern: CustomPattern = {
|
|
37
|
+
* pattern: /\bACME-\d{6}\b/g,
|
|
38
|
+
* category: "order-id",
|
|
39
|
+
* confidence: 0.9,
|
|
40
|
+
* label: "[ORDER_ID]",
|
|
41
|
+
* };
|
|
42
|
+
* ```
|
|
43
|
+
*/
|
|
44
|
+
interface CustomPattern {
|
|
45
|
+
/**
|
|
46
|
+
* The regular expression to match. If the global flag is absent it will be
|
|
47
|
+
* added automatically before execution.
|
|
48
|
+
*/
|
|
49
|
+
readonly pattern: RegExp;
|
|
50
|
+
/**
|
|
51
|
+
* Category label attached to matches. Defaults to `"custom"`.
|
|
52
|
+
* Does not need to be a built-in {@link PiiCategory}.
|
|
53
|
+
*/
|
|
54
|
+
readonly category?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Confidence score in [0, 1]. Defaults to `0.85`.
|
|
57
|
+
*/
|
|
58
|
+
readonly confidence?: number;
|
|
59
|
+
/**
|
|
60
|
+
* Replacement label used when a match is replaced.
|
|
61
|
+
* Defaults to `"[REDACTED]"`.
|
|
62
|
+
*/
|
|
63
|
+
readonly label?: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Locale codes for locale-aware PII detection. `"global"` covers universally-
|
|
67
|
+
* formatted PII (e.g. email, IPv4, credit card).
|
|
68
|
+
*/
|
|
69
|
+
type Locale = "global" | "us" | "uk" | "eu" | "ca" | "au" | "br" | "in" | "cn" | "jp" | "kr" | "za";
|
|
70
|
+
/**
|
|
71
|
+
* Built-in compliance preset identifiers.
|
|
72
|
+
*/
|
|
73
|
+
type CompliancePreset = "gdpr" | "hipaa" | "ccpa" | "pci-dss" | "sox" | "ferpa";
|
|
74
|
+
/**
|
|
75
|
+
* A single tokenized PII match.
|
|
76
|
+
*/
|
|
77
|
+
interface TokenMatch {
|
|
78
|
+
/** The placeholder token, e.g. `<Email_1>` or `[EMAIL_a3f9]`. */
|
|
79
|
+
readonly token: string;
|
|
80
|
+
/** The original PII value. */
|
|
81
|
+
readonly original: string;
|
|
82
|
+
/** The PII category. */
|
|
83
|
+
readonly category: PiiCategory;
|
|
84
|
+
/** Zero-based start index within the source string. */
|
|
85
|
+
readonly start: number;
|
|
86
|
+
/** Zero-based exclusive end index within the source string. */
|
|
87
|
+
readonly end: number;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Result returned by `tokenize()`.
|
|
91
|
+
*/
|
|
92
|
+
interface TokenizeResult {
|
|
93
|
+
/** The tokenized text with PII replaced by placeholder tokens. */
|
|
94
|
+
readonly text: string;
|
|
95
|
+
/** A map from token → original value for reversibility. */
|
|
96
|
+
readonly mapping: ReadonlyMap<string, string>;
|
|
97
|
+
/** All token match details. */
|
|
98
|
+
readonly tokens: readonly TokenMatch[];
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Result returned by `detokenize()`.
|
|
102
|
+
*/
|
|
103
|
+
interface DetokenizeResult {
|
|
104
|
+
/** The restored text with tokens replaced by original values. */
|
|
105
|
+
readonly text: string;
|
|
106
|
+
/** Number of tokens successfully replaced. */
|
|
107
|
+
readonly replacedCount: number;
|
|
108
|
+
/** Any tokens not found in the mapping (left unchanged in output). */
|
|
109
|
+
readonly unresolved: readonly string[];
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Token format style.
|
|
113
|
+
* - `"angle"`: `<Category_N>` (default, LLM-friendly)
|
|
114
|
+
* - `"bracket"`: `[CATEGORY_xxxx]`
|
|
115
|
+
* - `"custom"`: Use `tokenTemplate` function
|
|
116
|
+
*/
|
|
117
|
+
type TokenFormat = "angle" | "bracket" | "custom";
|
|
118
|
+
/**
|
|
119
|
+
* Options accepted by `tokenize()`.
|
|
120
|
+
*/
|
|
121
|
+
interface TokenizeOptions {
|
|
122
|
+
/**
|
|
123
|
+
* Categories to detect and tokenize. Defaults to all.
|
|
124
|
+
*/
|
|
125
|
+
readonly categories?: readonly PiiCategory[];
|
|
126
|
+
/**
|
|
127
|
+
* Token format style. Defaults to `"bracket"`.
|
|
128
|
+
*/
|
|
129
|
+
readonly format?: TokenFormat;
|
|
130
|
+
/**
|
|
131
|
+
* Custom token template function. Only used when `format: "custom"`.
|
|
132
|
+
* @param category - The PII category.
|
|
133
|
+
* @param counter - The incrementing counter for this category.
|
|
134
|
+
* @param value - The original matched value.
|
|
135
|
+
*/
|
|
136
|
+
readonly tokenTemplate?: (category: string, counter: number, value: string) => string;
|
|
137
|
+
/**
|
|
138
|
+
* When `true`, identical PII values receive the same token. Defaults to `true`.
|
|
139
|
+
*/
|
|
140
|
+
readonly deterministic?: boolean;
|
|
141
|
+
/**
|
|
142
|
+
* When `true`, use aggressive detector patterns. Defaults to `false`.
|
|
143
|
+
*/
|
|
144
|
+
readonly aggressive?: boolean;
|
|
145
|
+
/**
|
|
146
|
+
* Locales to enable for detection. Defaults to `["global"]`.
|
|
147
|
+
*/
|
|
148
|
+
readonly locales?: readonly Locale[];
|
|
149
|
+
/**
|
|
150
|
+
* Confidence threshold - only tokenize matches at or above this score. Defaults to `0`.
|
|
151
|
+
*/
|
|
152
|
+
readonly confidenceThreshold?: number;
|
|
153
|
+
/**
|
|
154
|
+
* Custom detector overrides (same as `AnonymizeOptions.customDetectors`).
|
|
155
|
+
*/
|
|
156
|
+
readonly customDetectors?: Partial<Record<PiiCategory, Detector>>;
|
|
157
|
+
/**
|
|
158
|
+
* Values that should never be tokenized even when detected as PII.
|
|
159
|
+
*/
|
|
160
|
+
readonly allowlist?: readonly string[];
|
|
161
|
+
/**
|
|
162
|
+
* When `true`, allowlist string matches are case-sensitive. Defaults to `false`.
|
|
163
|
+
*/
|
|
164
|
+
readonly allowlistCaseSensitive?: boolean;
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Options for the `encrypt` strategy.
|
|
168
|
+
*/
|
|
169
|
+
interface EncryptOptions {
|
|
170
|
+
/**
|
|
171
|
+
* Passphrase used to derive an AES-256-GCM key via PBKDF2.
|
|
172
|
+
* Provide either `passphrase` or `keyBytes`, not both.
|
|
173
|
+
*/
|
|
174
|
+
readonly passphrase?: string;
|
|
175
|
+
/**
|
|
176
|
+
* Raw key bytes (16 or 32 bytes) for AES-128 or AES-256 GCM.
|
|
177
|
+
* Provide either `keyBytes` or `passphrase`, not both.
|
|
178
|
+
*/
|
|
179
|
+
readonly keyBytes?: Uint8Array;
|
|
180
|
+
/** Output encoding for the ciphertext. Defaults to `"base64"`. */
|
|
181
|
+
readonly encoding?: "base64" | "hex";
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Options for the `synthesize` strategy.
|
|
185
|
+
*/
|
|
186
|
+
interface SynthesizeOptions {
|
|
187
|
+
/**
|
|
188
|
+
* Optional seed string for deterministic output.
|
|
189
|
+
* Same seed + same value + same category always produces the same synthetic replacement.
|
|
190
|
+
*/
|
|
191
|
+
readonly seed?: string;
|
|
192
|
+
/** Locale hint for locale-specific synthesis (e.g. phone-number format). */
|
|
193
|
+
readonly locale?: Locale;
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* Result of a batch processing operation.
|
|
197
|
+
*/
|
|
198
|
+
/**
|
|
199
|
+
* A single item result from a batch processing operation.
|
|
200
|
+
*
|
|
201
|
+
* @example
|
|
202
|
+
* ```ts
|
|
203
|
+
* const results = anonymizeBatch(["alice@example.com", "bad input"]);
|
|
204
|
+
* for (const r of results) {
|
|
205
|
+
* if (r.ok) console.log(r.value.text);
|
|
206
|
+
* else console.error(`Item ${r.index} failed:`, r.error.message);
|
|
207
|
+
* }
|
|
208
|
+
* ```
|
|
209
|
+
*/
|
|
210
|
+
type BatchResult<T> = {
|
|
211
|
+
readonly index: number;
|
|
212
|
+
readonly ok: true;
|
|
213
|
+
readonly value: T;
|
|
214
|
+
} | {
|
|
215
|
+
readonly index: number;
|
|
216
|
+
readonly ok: false;
|
|
217
|
+
readonly error: Error;
|
|
218
|
+
};
|
|
219
|
+
/**
|
|
220
|
+
* A validator function that performs checksum/format validation.
|
|
221
|
+
* Returns `true` if the value is valid.
|
|
222
|
+
*/
|
|
223
|
+
type ValidatorFunction = (value: string) => boolean;
|
|
224
|
+
/**
|
|
225
|
+
* A strategy function that transforms a PII value to its anonymized form.
|
|
226
|
+
*/
|
|
227
|
+
type StrategyFunction = (value: string, options?: Record<string, unknown>) => string;
|
|
228
|
+
/**
|
|
229
|
+
* An anonyma plugin that extends detection, anonymization strategy, or validation.
|
|
230
|
+
*/
|
|
231
|
+
interface AnonymaPlugin {
|
|
232
|
+
/** Unique plugin name. */
|
|
233
|
+
readonly name: string;
|
|
234
|
+
/** Additional or replacement detectors (keyed by category name). */
|
|
235
|
+
readonly detectors?: Record<string, Detector>;
|
|
236
|
+
/** Additional anonymization strategy implementations. */
|
|
237
|
+
readonly strategies?: Record<string, StrategyFunction>;
|
|
238
|
+
/** Additional checksum/format validators. */
|
|
239
|
+
readonly validators?: Record<string, ValidatorFunction>;
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* Built-in anonymization strategy identifiers.
|
|
243
|
+
*/
|
|
244
|
+
type StrategyName = "mask" | "redact" | "pseudonymize" | "hash" | "generalize" | "tokenize" | "encrypt" | "synthesize";
|
|
245
|
+
/**
|
|
246
|
+
* Options for the `mask` strategy.
|
|
247
|
+
*/
|
|
248
|
+
interface MaskOptions {
|
|
249
|
+
/** Character used as the mask. Defaults to `"*"`. */
|
|
250
|
+
readonly maskChar?: string;
|
|
251
|
+
/** Number of leading characters to keep visible. Defaults to `0`. */
|
|
252
|
+
readonly keepLeading?: number;
|
|
253
|
+
/** Number of trailing characters to keep visible. Defaults to `0`. */
|
|
254
|
+
readonly keepTrailing?: number;
|
|
255
|
+
/**
|
|
256
|
+
* When `true`, apply format-preserving masking: alphabetic chars → `X`,
|
|
257
|
+
* digits → `0`, separators and punctuation preserved.
|
|
258
|
+
*
|
|
259
|
+
* @example `123-45-6789` → `000-00-0000`, `john@example.com` → `XXXX@XXXXXXX.XXX`
|
|
260
|
+
*/
|
|
261
|
+
readonly preserveFormat?: boolean;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* Options for the `redact` strategy.
|
|
265
|
+
*/
|
|
266
|
+
interface RedactOptions {
|
|
267
|
+
/** Replacement label. Defaults to `"[REDACTED]"`. */
|
|
268
|
+
readonly label?: string;
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* Options for the `pseudonymize` strategy.
|
|
272
|
+
*/
|
|
273
|
+
interface PseudonymizeOptions {
|
|
274
|
+
/**
|
|
275
|
+
* Secret seed used for deterministic output. When provided the same input + seed
|
|
276
|
+
* always produces the same pseudonym, enabling consistent replacement across a dataset.
|
|
277
|
+
* When omitted, a random pseudonym is generated.
|
|
278
|
+
*/
|
|
279
|
+
readonly seed?: string;
|
|
280
|
+
/** Namespace prefix appended to the pseudonym. Defaults to `"id_"`. */
|
|
281
|
+
readonly prefix?: string;
|
|
282
|
+
}
|
|
283
|
+
/**
|
|
284
|
+
* Options for the `hash` strategy.
|
|
285
|
+
*/
|
|
286
|
+
interface HashOptions {
|
|
287
|
+
/** Number of hex characters to keep from the digest. Defaults to `16`. */
|
|
288
|
+
readonly truncate?: number;
|
|
289
|
+
/**
|
|
290
|
+
* Optional pepper (a per-deployment secret) mixed into the hash. Using a pepper
|
|
291
|
+
* ensures hashes cannot be reversed via rainbow tables.
|
|
292
|
+
*/
|
|
293
|
+
readonly pepper?: string;
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* Options for the `generalize` strategy.
|
|
297
|
+
*/
|
|
298
|
+
interface GeneralizeOptions {
|
|
299
|
+
/**
|
|
300
|
+
* For numeric fields: the bucket/range width. For example `10` turns `27` into `"20-29"`.
|
|
301
|
+
* Defaults to `10`.
|
|
302
|
+
*/
|
|
303
|
+
readonly bucketSize?: number;
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* Union of all strategy option shapes.
|
|
307
|
+
*/
|
|
308
|
+
type StrategyOptions = ({
|
|
309
|
+
strategy: "mask";
|
|
310
|
+
} & MaskOptions) | ({
|
|
311
|
+
strategy: "redact";
|
|
312
|
+
} & RedactOptions) | ({
|
|
313
|
+
strategy: "pseudonymize";
|
|
314
|
+
} & PseudonymizeOptions) | ({
|
|
315
|
+
strategy: "hash";
|
|
316
|
+
} & HashOptions) | ({
|
|
317
|
+
strategy: "generalize";
|
|
318
|
+
} & GeneralizeOptions) | ({
|
|
319
|
+
strategy: "tokenize";
|
|
320
|
+
} & Omit<TokenizeOptions, "categories" | "aggressive" | "locales" | "confidenceThreshold">) | ({
|
|
321
|
+
strategy: "encrypt";
|
|
322
|
+
} & EncryptOptions) | ({
|
|
323
|
+
strategy: "synthesize";
|
|
324
|
+
} & SynthesizeOptions & {
|
|
325
|
+
category?: PiiCategory;
|
|
326
|
+
});
|
|
327
|
+
/**
|
|
328
|
+
* A rule that maps a PII category to an anonymization strategy.
|
|
329
|
+
*/
|
|
330
|
+
interface AnonymizationRule {
|
|
331
|
+
/** The PII category this rule applies to. */
|
|
332
|
+
readonly category: PiiCategory;
|
|
333
|
+
/** The strategy to apply. */
|
|
334
|
+
readonly strategy: StrategyOptions;
|
|
335
|
+
}
|
|
336
|
+
/**
|
|
337
|
+
* Options accepted by the top-level `anonymize()` function.
|
|
338
|
+
*/
|
|
339
|
+
interface AnonymizeOptions {
|
|
340
|
+
/**
|
|
341
|
+
* Per-category overrides. When specified, only the listed categories are processed;
|
|
342
|
+
* all others are left untouched.
|
|
343
|
+
*/
|
|
344
|
+
readonly rules?: readonly AnonymizationRule[];
|
|
345
|
+
/**
|
|
346
|
+
* Default strategy applied to any category not covered by `rules`.
|
|
347
|
+
* Defaults to `{ strategy: "redact" }`.
|
|
348
|
+
*/
|
|
349
|
+
readonly defaultStrategy?: StrategyOptions;
|
|
350
|
+
/**
|
|
351
|
+
* When `true`, detected matches are included in the result object.
|
|
352
|
+
* Defaults to `false` for performance.
|
|
353
|
+
*/
|
|
354
|
+
readonly includeMatches?: boolean;
|
|
355
|
+
/**
|
|
356
|
+
* Additional or overriding custom detectors per built-in category.
|
|
357
|
+
* Custom detectors are called instead of (not in addition to) the built-in detector
|
|
358
|
+
* for the specified category.
|
|
359
|
+
*/
|
|
360
|
+
readonly customDetectors?: Partial<Record<PiiCategory, Detector>>;
|
|
361
|
+
/**
|
|
362
|
+
* Additional ad-hoc regex patterns to match and replace alongside built-in detectors.
|
|
363
|
+
* Custom pattern matches participate in the standard overlap deduplication.
|
|
364
|
+
*/
|
|
365
|
+
readonly customPatterns?: readonly CustomPattern[];
|
|
366
|
+
/**
|
|
367
|
+
* When set, every detected PII entity (from all strategies) is replaced with
|
|
368
|
+
* this exact string, overriding per-category rules and `defaultStrategy`.
|
|
369
|
+
* Must be a non-empty string.
|
|
370
|
+
*/
|
|
371
|
+
readonly globalReplacement?: string;
|
|
372
|
+
/**
|
|
373
|
+
* When `true`, identical PII values receive the same token across the entire
|
|
374
|
+
* `anonymize()` call (e.g. `EMAIL_1`), and different values get different tokens.
|
|
375
|
+
* Tokens are category-prefixed with incrementing counters.
|
|
376
|
+
* State is scoped to a single call — no cross-call leakage.
|
|
377
|
+
*
|
|
378
|
+
* @example `alice@example.com` → `EMAIL_1`, `bob@example.com` → `EMAIL_2`
|
|
379
|
+
*/
|
|
380
|
+
readonly consistentTokens?: boolean;
|
|
381
|
+
/**
|
|
382
|
+
* When `true`, each detector uses its expanded, more permissive pattern set.
|
|
383
|
+
* This catches obfuscated or partial PII (e.g. `user [at] domain [dot] com`)
|
|
384
|
+
* at the cost of more false positives. Confidence scores are reduced accordingly.
|
|
385
|
+
*/
|
|
386
|
+
readonly aggressive?: boolean;
|
|
387
|
+
/**
|
|
388
|
+
* Convenience enable/disable map for PII categories.
|
|
389
|
+
* Categories set to `true` are active; `false` or missing entries are excluded.
|
|
390
|
+
* When both `enabledCategories` and `rules` are provided, `rules` takes
|
|
391
|
+
* precedence for the categories it covers.
|
|
392
|
+
*
|
|
393
|
+
* @example
|
|
394
|
+
* ```ts
|
|
395
|
+
* anonymize(text, { enabledCategories: { email: true, phone: true, ssn: false } });
|
|
396
|
+
* ```
|
|
397
|
+
*/
|
|
398
|
+
readonly enabledCategories?: Partial<Record<PiiCategory, boolean>>;
|
|
399
|
+
/**
|
|
400
|
+
* Exact values to exclude from detection (case-insensitive by default).
|
|
401
|
+
* Matches in the allowlist are skipped before strategy application.
|
|
402
|
+
*
|
|
403
|
+
* @example `allowlist: ["noreply@company.com"]`
|
|
404
|
+
*/
|
|
405
|
+
readonly allowlist?: readonly string[];
|
|
406
|
+
/**
|
|
407
|
+
* RegExp patterns for values to skip. Matches against the full PII value.
|
|
408
|
+
*
|
|
409
|
+
* @example `allowlistPatterns: [/^192\.168\./]`
|
|
410
|
+
*/
|
|
411
|
+
readonly allowlistPatterns?: readonly RegExp[];
|
|
412
|
+
/**
|
|
413
|
+
* When `allowlist` matching is case-sensitive. Defaults to `false` (case-insensitive).
|
|
414
|
+
*/
|
|
415
|
+
readonly allowlistCaseSensitive?: boolean;
|
|
416
|
+
/**
|
|
417
|
+
* Minimum confidence score [0, 1] for a match to be anonymized.
|
|
418
|
+
* Matches below this threshold are left untouched. Defaults to `0` (process all).
|
|
419
|
+
*/
|
|
420
|
+
readonly confidenceThreshold?: number;
|
|
421
|
+
/**
|
|
422
|
+
* Apply a built-in compliance preset, which pre-configures `enabledCategories`
|
|
423
|
+
* and `defaultStrategy`. Explicit `rules` and `defaultStrategy` options take
|
|
424
|
+
* precedence over preset values.
|
|
425
|
+
*/
|
|
426
|
+
readonly preset?: CompliancePreset;
|
|
427
|
+
/**
|
|
428
|
+
* Locales to activate for locale-specific detectors.
|
|
429
|
+
* Defaults to `["global"]` which includes universally-formatted PII.
|
|
430
|
+
* Add specific locales to include region-specific patterns (e.g. `["us", "uk"]`).
|
|
431
|
+
*/
|
|
432
|
+
readonly locales?: readonly Locale[];
|
|
433
|
+
}
|
|
434
|
+
/**
|
|
435
|
+
* Result returned by `anonymize()`.
|
|
436
|
+
*/
|
|
437
|
+
interface AnonymizeResult {
|
|
438
|
+
/** The anonymized text. */
|
|
439
|
+
readonly text: string;
|
|
440
|
+
/** Detected PII matches (only populated when `includeMatches: true`). */
|
|
441
|
+
readonly matches: readonly PiiMatch[];
|
|
442
|
+
}
|
|
443
|
+
/**
|
|
444
|
+
* A field-level rule for `anonymizeObject()` / `anonymizeRecord()`.
|
|
445
|
+
*/
|
|
446
|
+
interface FieldRule {
|
|
447
|
+
/** The strategy to apply to this field's value. */
|
|
448
|
+
readonly strategy: StrategyOptions;
|
|
449
|
+
}
|
|
450
|
+
/**
|
|
451
|
+
* A mapping of object field paths → `FieldRule`.
|
|
452
|
+
* Dot-notation is supported for nested paths (e.g. `"user.email"`).
|
|
453
|
+
*/
|
|
454
|
+
type FieldRuleMap = Readonly<Record<string, FieldRule>>;
|
|
455
|
+
/**
|
|
456
|
+
* A function that finds PII matches of a specific category in a string.
|
|
457
|
+
*
|
|
458
|
+
* @param text - The input string to scan.
|
|
459
|
+
* @returns An array of matches (may be empty).
|
|
460
|
+
*/
|
|
461
|
+
type Detector = (text: string) => PiiMatch[];
|
|
462
|
+
/**
|
|
463
|
+
* Registry of all available detectors keyed by PII category.
|
|
464
|
+
*/
|
|
465
|
+
type DetectorRegistry = Readonly<Record<PiiCategory, Detector>>;
|
|
466
|
+
/**
|
|
467
|
+
* A configured, reusable anonymizer instance produced by `createAnonymizer()`.
|
|
468
|
+
*/
|
|
469
|
+
interface Anonymizer {
|
|
470
|
+
/**
|
|
471
|
+
* Anonymize a text string.
|
|
472
|
+
* @param text - The input text.
|
|
473
|
+
* @param options - Optional per-call overrides.
|
|
474
|
+
*/
|
|
475
|
+
readonly anonymize: (text: string, options?: Partial<AnonymizeOptions>) => AnonymizeResult;
|
|
476
|
+
/**
|
|
477
|
+
* Anonymize a text string asynchronously (supports `hash` and `encrypt` strategies natively).
|
|
478
|
+
* @param text - The input text.
|
|
479
|
+
* @param options - Optional per-call overrides.
|
|
480
|
+
*/
|
|
481
|
+
readonly anonymizeAsync: (text: string, options?: Partial<AnonymizeOptions>) => Promise<AnonymizeResult>;
|
|
482
|
+
/**
|
|
483
|
+
* Detect all PII in a text string without anonymizing.
|
|
484
|
+
* @param text - The input text.
|
|
485
|
+
*/
|
|
486
|
+
readonly detect: (text: string) => PiiMatch[];
|
|
487
|
+
/**
|
|
488
|
+
* Anonymize specific fields in a plain record/object.
|
|
489
|
+
* @param record - The input record.
|
|
490
|
+
* @param rules - Field-level rules.
|
|
491
|
+
*/
|
|
492
|
+
readonly anonymizeRecord: <T extends Record<string, unknown>>(record: T, rules: FieldRuleMap) => T;
|
|
493
|
+
/**
|
|
494
|
+
* Recursively anonymize all string values in a JSON-serializable object tree.
|
|
495
|
+
* @param obj - The input object. Must be free of circular references.
|
|
496
|
+
* @param options - Optional per-call anonymization overrides.
|
|
497
|
+
*/
|
|
498
|
+
readonly anonymizeObject: <T extends object>(obj: T, options?: AnonymizeOptions) => T;
|
|
499
|
+
/**
|
|
500
|
+
* Tokenize PII in text for LLM-safe transmission.
|
|
501
|
+
* @param text - The input text.
|
|
502
|
+
* @param options - Tokenization options.
|
|
503
|
+
*/
|
|
504
|
+
readonly tokenize: (text: string, options?: TokenizeOptions) => TokenizeResult;
|
|
505
|
+
/**
|
|
506
|
+
* Return `true` if `text` contains any detectable PII.
|
|
507
|
+
* Stops scanning after the first match for performance.
|
|
508
|
+
* @param text - The input text.
|
|
509
|
+
*/
|
|
510
|
+
readonly hasPII: (text: string) => boolean;
|
|
511
|
+
}
|
|
512
|
+
/**
|
|
513
|
+
* Configuration for `createAnonymizer()`.
|
|
514
|
+
*/
|
|
515
|
+
interface AnonymizerConfig {
|
|
516
|
+
/** Ordered list of categories to detect. Defaults to all built-in categories. */
|
|
517
|
+
readonly categories?: readonly PiiCategory[];
|
|
518
|
+
/** Default strategy applied when no per-category rule is provided. */
|
|
519
|
+
readonly defaultStrategy?: StrategyOptions;
|
|
520
|
+
/** Additional or overriding custom detectors. */
|
|
521
|
+
readonly customDetectors?: Partial<Record<PiiCategory, Detector>>;
|
|
522
|
+
/** Ad-hoc regex patterns applied alongside built-in detectors. */
|
|
523
|
+
readonly customPatterns?: readonly CustomPattern[];
|
|
524
|
+
/**
|
|
525
|
+
* When set, every detected PII entity is replaced with this exact string.
|
|
526
|
+
* Overrides `defaultStrategy` and per-category rules.
|
|
527
|
+
*/
|
|
528
|
+
readonly globalReplacement?: string;
|
|
529
|
+
/**
|
|
530
|
+
* When `true`, identical PII values receive consistent tokens within a call.
|
|
531
|
+
* @see {@link AnonymizeOptions.consistentTokens}
|
|
532
|
+
*/
|
|
533
|
+
readonly consistentTokens?: boolean;
|
|
534
|
+
/**
|
|
535
|
+
* When `true`, detectors use expanded, more permissive patterns.
|
|
536
|
+
* @see {@link AnonymizeOptions.aggressive}
|
|
537
|
+
*/
|
|
538
|
+
readonly aggressive?: boolean;
|
|
539
|
+
/**
|
|
540
|
+
* Plugins to extend detector, strategy, or validator capabilities.
|
|
541
|
+
*/
|
|
542
|
+
readonly plugins?: readonly AnonymaPlugin[];
|
|
543
|
+
/**
|
|
544
|
+
* Apply a built-in compliance preset as the base for this anonymizer.
|
|
545
|
+
*/
|
|
546
|
+
readonly preset?: CompliancePreset;
|
|
547
|
+
/**
|
|
548
|
+
* Locales to activate for locale-specific detectors.
|
|
549
|
+
*/
|
|
550
|
+
readonly locales?: readonly Locale[];
|
|
551
|
+
}
|
|
552
|
+
|
|
553
|
+
export type { AnonymizeOptions as A, BatchResult as B, CompliancePreset as C, Detector as D, EncryptOptions as E, FieldRuleMap as F, GeneralizeOptions as G, HashOptions as H, Locale as L, MaskOptions as M, PiiCategory as P, RedactOptions as R, StrategyOptions as S, TokenizeOptions as T, ValidatorFunction as V, AnonymizeResult as a, TokenizeResult as b, AnonymizerConfig as c, Anonymizer as d, PiiMatch as e, DetokenizeResult as f, AnonymizationRule as g, PseudonymizeOptions as h, SynthesizeOptions as i, AnonymaPlugin as j, CustomPattern as k, DetectorRegistry as l, FieldRule as m, StrategyName as n, TokenFormat as o };
|