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