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,385 @@
|
|
|
1
|
+
import { K as KeyMaterial, e as KeyRingManifest, f as KeyRing, T as TokenizationProvider, a as TokenContext, E as ErasureReceipt, g as TokenVault, V as VaultRecord, R as RestoreResult, h as Replacer } from '../types-Dtht33aq.js';
|
|
2
|
+
export { i as KeyPurpose, j as KeyState, k as KeyVersionInfo, M as MaybePromise } from '../types-Dtht33aq.js';
|
|
3
|
+
export { a as SessionSnapshot, S as SessionTokenizer, b as SessionTokenizerOptions, c as createSessionTokenizer } from '../session-Cs2zlNQp.js';
|
|
4
|
+
import '../types-EJTj_BKY.js';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* @module vault/keyring
|
|
8
|
+
* @description Versioned key management: every version holds one secret from
|
|
9
|
+
* which independent, purpose-bound keys are derived with HKDF-SHA-256.
|
|
10
|
+
*
|
|
11
|
+
* Cryptographic parameters
|
|
12
|
+
* - Raw material: used directly as HKDF input keying material (at least 32 bytes).
|
|
13
|
+
* - Passphrases: stretched with PBKDF2-HMAC-SHA-256 (600,000 iterations by
|
|
14
|
+
* default, never fewer than 100,000) into 32 bytes of keying material.
|
|
15
|
+
* - Salt: 32 random bytes per version, used for PBKDF2 and for HKDF-Extract.
|
|
16
|
+
* It is not secret and is part of the manifest.
|
|
17
|
+
* - Domain separation: the HKDF `info` is `"anonyma/v1/" + purpose + NUL +
|
|
18
|
+
* namespace`, so keys differ per purpose and per namespace.
|
|
19
|
+
* - Derived keys are non-extractable `CryptoKey` objects.
|
|
20
|
+
* - The manifest carries an HMAC-SHA-256 under a key of the active version.
|
|
21
|
+
* A manifest that was edited (another active version, a lower iteration
|
|
22
|
+
* count, another salt) is refused when the ring is created from it.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Options accepted by {@link createKeyRing}.
|
|
27
|
+
*/
|
|
28
|
+
interface KeyRingOptions {
|
|
29
|
+
/** Domain-separation label (tenant, dataset or environment). Must not be empty. */
|
|
30
|
+
readonly namespace: string;
|
|
31
|
+
/**
|
|
32
|
+
* The secret of every live version, oldest first. Unless a manifest says
|
|
33
|
+
* otherwise, the last one is active and the others are retired.
|
|
34
|
+
*/
|
|
35
|
+
readonly keys: readonly {
|
|
36
|
+
readonly id: string;
|
|
37
|
+
readonly material: KeyMaterial;
|
|
38
|
+
}[];
|
|
39
|
+
/**
|
|
40
|
+
* The manifest of a previous run. Supplying it makes the ring derive the
|
|
41
|
+
* same keys again; versions it lists as destroyed need no entry in `keys`.
|
|
42
|
+
* Every entry of `keys` must be listed in it: a new version is added with
|
|
43
|
+
* {@link KeyRing.rotate}, never by passing an extra key.
|
|
44
|
+
*/
|
|
45
|
+
readonly manifest?: KeyRingManifest;
|
|
46
|
+
/** Clock used for `createdAt`. Defaults to `Date.now`. */
|
|
47
|
+
readonly now?: () => number;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Generate fresh, random key material for a new key version.
|
|
51
|
+
*
|
|
52
|
+
* @returns 32 random bytes wrapped as {@link KeyMaterial}.
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* ```ts
|
|
56
|
+
* const ring = await createKeyRing({
|
|
57
|
+
* namespace: "prod/eu",
|
|
58
|
+
* keys: [{ id: "k1", material: await generateKeyMaterial() }],
|
|
59
|
+
* });
|
|
60
|
+
* ```
|
|
61
|
+
*/
|
|
62
|
+
declare function generateKeyMaterial(): Promise<KeyMaterial>;
|
|
63
|
+
/**
|
|
64
|
+
* Create a key ring.
|
|
65
|
+
*
|
|
66
|
+
* @param options - Namespace, the secret of every live version, and optionally
|
|
67
|
+
* the manifest of a previous run.
|
|
68
|
+
* @returns The {@link KeyRing}.
|
|
69
|
+
* @throws {@link KeyManagementError} When an identifier is malformed or repeated, material is
|
|
70
|
+
* too weak, or a live version of the manifest has no material.
|
|
71
|
+
*
|
|
72
|
+
* @example
|
|
73
|
+
* ```ts
|
|
74
|
+
* import { createKeyRing } from "anonyma/vault";
|
|
75
|
+
*
|
|
76
|
+
* const ring = await createKeyRing({
|
|
77
|
+
* namespace: "billing",
|
|
78
|
+
* keys: [{ id: "2026a", material: { kind: "raw", bytes: secretBytes } }],
|
|
79
|
+
* });
|
|
80
|
+
* saveSomewhere(JSON.stringify(ring.manifest())); // not secret
|
|
81
|
+
*
|
|
82
|
+
* // Later: add a version, then retire and finally destroy the old one.
|
|
83
|
+
* await ring.rotate({ id: "2026b", material: { kind: "raw", bytes: newSecretBytes } });
|
|
84
|
+
* ring.destroy("2026a");
|
|
85
|
+
* ```
|
|
86
|
+
*/
|
|
87
|
+
declare function createKeyRing(options: KeyRingOptions): Promise<KeyRing>;
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* @module vault/keyed
|
|
91
|
+
* @description Deterministic, keyed tokenization. A token identifier is an
|
|
92
|
+
* HMAC-SHA-256 of the category and the value under a secret key, so the same
|
|
93
|
+
* value always yields the same token for a key version — across calls,
|
|
94
|
+
* processes and machines — without anyone being able to recompute it without
|
|
95
|
+
* the key.
|
|
96
|
+
*
|
|
97
|
+
* With a vault the scheme is reversible: the original value is stored sealed
|
|
98
|
+
* with AES-256-GCM. Without a vault it is a one-way keyed pseudonym.
|
|
99
|
+
*/
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Options accepted by {@link createKeyedTokenizer}.
|
|
103
|
+
*/
|
|
104
|
+
interface KeyedTokenizerOptions {
|
|
105
|
+
/** The key ring that supplies the identifier and sealing keys. */
|
|
106
|
+
readonly keyring: KeyRing;
|
|
107
|
+
/** Where sealed originals are kept. Leave it out for one-way pseudonyms. */
|
|
108
|
+
readonly vault?: TokenVault;
|
|
109
|
+
/**
|
|
110
|
+
* Key version used for token identifiers. Pin it to keep tokens stable
|
|
111
|
+
* while the sealing key rotates. Defaults to the ring's active version at
|
|
112
|
+
* the time of each call.
|
|
113
|
+
*
|
|
114
|
+
* A pinned version must stay in the ring: once it is destroyed, nothing can
|
|
115
|
+
* be tokenized any more. Tokens that must survive crypto-shredding of the
|
|
116
|
+
* sealing keys therefore need an identifier version that is retired but
|
|
117
|
+
* never destroyed.
|
|
118
|
+
*/
|
|
119
|
+
readonly idKeyId?: string;
|
|
120
|
+
/**
|
|
121
|
+
* Length of the identifier in base32 characters (5 bits each), 8 to 26.
|
|
122
|
+
* Defaults to `12` (60 bits).
|
|
123
|
+
*/
|
|
124
|
+
readonly idLength?: number;
|
|
125
|
+
/** Token prefixes for categories, overriding the defaults. */
|
|
126
|
+
readonly prefixes?: Readonly<Record<string, string>>;
|
|
127
|
+
/**
|
|
128
|
+
* Lifetime of vault records in milliseconds, counted from the first time a
|
|
129
|
+
* value is tokenized. Records never expire by default. A value that is
|
|
130
|
+
* tokenized again after its record expired gets a fresh record under the
|
|
131
|
+
* same token.
|
|
132
|
+
*/
|
|
133
|
+
readonly ttlMs?: number;
|
|
134
|
+
/** Clock. Defaults to `Date.now`. */
|
|
135
|
+
readonly now?: () => number;
|
|
136
|
+
}
|
|
137
|
+
/**
|
|
138
|
+
* A keyed {@link TokenizationProvider} with erasure operations.
|
|
139
|
+
*/
|
|
140
|
+
interface KeyedTokenizer extends TokenizationProvider {
|
|
141
|
+
readonly tokenize: (value: string, context: TokenContext) => Promise<string>;
|
|
142
|
+
readonly detokenize: (token: string) => Promise<string | undefined>;
|
|
143
|
+
/**
|
|
144
|
+
* Delete the vault record of one token. The token can no longer be resolved.
|
|
145
|
+
* Returns `true` when a record was deleted.
|
|
146
|
+
*/
|
|
147
|
+
readonly forgetToken: (token: string) => Promise<boolean>;
|
|
148
|
+
/**
|
|
149
|
+
* Delete every vault record of a value that was tokenized for this
|
|
150
|
+
* data-subject reference, and return a receipt for the audit log. A value
|
|
151
|
+
* that several subjects share has one record, so its token stops resolving
|
|
152
|
+
* for all of them.
|
|
153
|
+
*/
|
|
154
|
+
readonly forgetSubject: (subject: string) => Promise<ErasureReceipt>;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Create a keyed tokenizer.
|
|
158
|
+
*
|
|
159
|
+
* Tokens look like `[EMAIL_k1_7ZK3M9QW2ABC]`: category prefix, key version,
|
|
160
|
+
* identifier.
|
|
161
|
+
*
|
|
162
|
+
* @param options - Key ring, optional vault and token options.
|
|
163
|
+
* @returns The {@link KeyedTokenizer}.
|
|
164
|
+
* @throws {@link ValidationError} When an option is invalid.
|
|
165
|
+
*
|
|
166
|
+
* @example
|
|
167
|
+
* ```ts
|
|
168
|
+
* import { createKeyRing, createKeyedTokenizer, createMemoryVault } from "anonyma/vault";
|
|
169
|
+
*
|
|
170
|
+
* const keyring = await createKeyRing({ namespace: "crm", keys: [{ id: "k1", material }] });
|
|
171
|
+
* const tokenizer = createKeyedTokenizer({ keyring, vault: createMemoryVault() });
|
|
172
|
+
*
|
|
173
|
+
* const token = await tokenizer.tokenize("alice@example.com", { category: "email", subject: "user-42" });
|
|
174
|
+
* await tokenizer.detokenize(token); // "alice@example.com"
|
|
175
|
+
* await tokenizer.forgetSubject("user-42"); // erasure: the token no longer resolves
|
|
176
|
+
* ```
|
|
177
|
+
*/
|
|
178
|
+
declare function createKeyedTokenizer(options: KeyedTokenizerOptions): KeyedTokenizer;
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* @module vault/sealed
|
|
182
|
+
* @description Stateless reversible tokenization. The token carries the
|
|
183
|
+
* original value sealed with AES-256-GCM, so restoring it needs only the key
|
|
184
|
+
* ring — no vault, no shared state.
|
|
185
|
+
*
|
|
186
|
+
* The scheme is deterministic: the nonce is derived from the value with a
|
|
187
|
+
* keyed PRF (a synthetic initialisation vector), so equal values produce equal
|
|
188
|
+
* tokens and a nonce is never reused for different values except with
|
|
189
|
+
* negligible probability. As with random 96-bit nonces, rotate the key version
|
|
190
|
+
* well before 2^32 distinct values have been sealed under it (NIST SP 800-38D).
|
|
191
|
+
* The length of a token grows with the length of the value.
|
|
192
|
+
*/
|
|
193
|
+
|
|
194
|
+
/**
|
|
195
|
+
* Options accepted by {@link createSealedTokenizer}.
|
|
196
|
+
*/
|
|
197
|
+
interface SealedTokenizerOptions {
|
|
198
|
+
/** The key ring that supplies the nonce and sealing keys. */
|
|
199
|
+
readonly keyring: KeyRing;
|
|
200
|
+
/** Token prefixes for categories, overriding the defaults. */
|
|
201
|
+
readonly prefixes?: Readonly<Record<string, string>>;
|
|
202
|
+
/**
|
|
203
|
+
* Longest value, in UTF-8 bytes, that may be sealed. It bounds the length of
|
|
204
|
+
* a token. Defaults to `256`.
|
|
205
|
+
*/
|
|
206
|
+
readonly maxValueBytes?: number;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* A stateless, reversible {@link TokenizationProvider}.
|
|
210
|
+
*/
|
|
211
|
+
interface SealedTokenizer extends TokenizationProvider {
|
|
212
|
+
readonly tokenize: (value: string, context: TokenContext) => Promise<string>;
|
|
213
|
+
readonly detokenize: (token: string) => Promise<string | undefined>;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* Create a stateless reversible tokenizer.
|
|
217
|
+
*
|
|
218
|
+
* Tokens look like `[EMAIL_k1.5wq…]`: category prefix, key version, then the
|
|
219
|
+
* sealed value. A token that was altered, or whose prefix or key version was
|
|
220
|
+
* swapped, does not resolve.
|
|
221
|
+
*
|
|
222
|
+
* @param options - Key ring and token options.
|
|
223
|
+
* @returns The {@link SealedTokenizer}.
|
|
224
|
+
* @throws {@link ValidationError} When an option is invalid.
|
|
225
|
+
*
|
|
226
|
+
* @example
|
|
227
|
+
* ```ts
|
|
228
|
+
* import { createKeyRing, createSealedTokenizer } from "anonyma/vault";
|
|
229
|
+
*
|
|
230
|
+
* const keyring = await createKeyRing({ namespace: "exports", keys: [{ id: "k1", material }] });
|
|
231
|
+
* const tokenizer = createSealedTokenizer({ keyring });
|
|
232
|
+
*
|
|
233
|
+
* const token = await tokenizer.tokenize("alice@example.com", { category: "email" });
|
|
234
|
+
* await tokenizer.detokenize(token); // "alice@example.com", on any machine holding the key
|
|
235
|
+
* ```
|
|
236
|
+
*/
|
|
237
|
+
declare function createSealedTokenizer(options: SealedTokenizerOptions): SealedTokenizer;
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* @module vault/memory-vault
|
|
241
|
+
* @description An in-memory {@link TokenVault}. It is the reference
|
|
242
|
+
* implementation of the interface and is suitable for tests and for
|
|
243
|
+
* single-process, short-lived vaults.
|
|
244
|
+
*/
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* A {@link TokenVault} that also reports how many records it holds.
|
|
248
|
+
*/
|
|
249
|
+
interface MemoryVault extends TokenVault {
|
|
250
|
+
/** Number of records currently stored. */
|
|
251
|
+
readonly size: () => number;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* Create an in-memory token vault.
|
|
255
|
+
*
|
|
256
|
+
* @param records - Records to start with, for example from an earlier export.
|
|
257
|
+
* @returns The vault.
|
|
258
|
+
*
|
|
259
|
+
* @example
|
|
260
|
+
* ```ts
|
|
261
|
+
* import { createMemoryVault, createKeyedTokenizer } from "anonyma/vault";
|
|
262
|
+
*
|
|
263
|
+
* const vault = createMemoryVault();
|
|
264
|
+
* const tokenizer = createKeyedTokenizer({ keyring, vault });
|
|
265
|
+
* ```
|
|
266
|
+
*/
|
|
267
|
+
declare function createMemoryVault(records?: Iterable<VaultRecord>): MemoryVault;
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* @module vault/rotation
|
|
271
|
+
* @description Key rotation and erasure for token vaults.
|
|
272
|
+
*
|
|
273
|
+
* Rotation protocol
|
|
274
|
+
* 1. `keyring.rotate()` adds a version and makes it active. New records are
|
|
275
|
+
* sealed under it; the previous version stays available for unsealing.
|
|
276
|
+
* 2. {@link rewrapVault} re-seals every record under the active version.
|
|
277
|
+
* Tokens do not change, so data that already contains them is unaffected.
|
|
278
|
+
* 3. `keyring.destroy()` (or {@link shredKey}) discards the old version.
|
|
279
|
+
*
|
|
280
|
+
* Erasure
|
|
281
|
+
* - A single value or data subject: delete the vault records (see
|
|
282
|
+
* `KeyedTokenizer.forgetToken()` and `forgetSubject()`).
|
|
283
|
+
* - Everything sealed under a key version: {@link shredKey}. Without the key
|
|
284
|
+
* the sealed values cannot be recovered by anyone, even from backups of the
|
|
285
|
+
* vault.
|
|
286
|
+
*/
|
|
287
|
+
|
|
288
|
+
/**
|
|
289
|
+
* Outcome of {@link rewrapVault}.
|
|
290
|
+
*/
|
|
291
|
+
interface RewrapResult {
|
|
292
|
+
/** Records re-sealed under the active key version. */
|
|
293
|
+
readonly rewrapped: number;
|
|
294
|
+
/** Records that were already sealed under the active key version. */
|
|
295
|
+
readonly current: number;
|
|
296
|
+
/** Records whose key version is destroyed, or that failed authentication. They are left as they are. */
|
|
297
|
+
readonly unrecoverable: number;
|
|
298
|
+
/**
|
|
299
|
+
* Records that were erased or changed while the rewrap ran. Nothing was
|
|
300
|
+
* written for them; run the rewrap again to pick up the ones that still exist.
|
|
301
|
+
*/
|
|
302
|
+
readonly skipped: number;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Re-seal every vault record under the key ring's active version. A record
|
|
306
|
+
* that is erased while the rewrap runs stays erased: the rewrap only replaces
|
|
307
|
+
* records that are still what it read.
|
|
308
|
+
*
|
|
309
|
+
* @param vault - The vault to re-seal.
|
|
310
|
+
* @param keyring - The key ring. It must still hold the versions the records were sealed under.
|
|
311
|
+
* @returns Counts of what was done.
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* ```ts
|
|
315
|
+
* await keyring.rotate({ id: "k2", material });
|
|
316
|
+
* const { unrecoverable, skipped } = await rewrapVault(vault, keyring);
|
|
317
|
+
* if (unrecoverable === 0 && skipped === 0) keyring.destroy("k1");
|
|
318
|
+
* ```
|
|
319
|
+
*/
|
|
320
|
+
declare function rewrapVault(vault: TokenVault, keyring: KeyRing): Promise<RewrapResult>;
|
|
321
|
+
/**
|
|
322
|
+
* Crypto-shred a key version: discard its material and, when a vault is
|
|
323
|
+
* given, delete the records that were sealed under it.
|
|
324
|
+
*
|
|
325
|
+
* @param keyring - The key ring.
|
|
326
|
+
* @param keyId - The version to destroy. It must not be the active version.
|
|
327
|
+
* @param vault - The vault whose records under that version should be deleted.
|
|
328
|
+
* @param now - Clock for the receipt. Defaults to `Date.now`.
|
|
329
|
+
* @returns A receipt for the audit log.
|
|
330
|
+
* @throws KeyManagementError When the version is unknown or active.
|
|
331
|
+
*
|
|
332
|
+
* @example
|
|
333
|
+
* ```ts
|
|
334
|
+
* const receipt = await shredKey(keyring, "k1", vault);
|
|
335
|
+
* await audit.record({ operation: "key-destroy", fields: [], attributes: { erased: receipt.erased } });
|
|
336
|
+
* ```
|
|
337
|
+
*/
|
|
338
|
+
declare function shredKey(keyring: KeyRing, keyId: string, vault?: TokenVault, now?: () => number): Promise<ErasureReceipt>;
|
|
339
|
+
|
|
340
|
+
/**
|
|
341
|
+
* @module vault/restore
|
|
342
|
+
* @description Helpers that connect tokenization providers to text and to the
|
|
343
|
+
* span engine.
|
|
344
|
+
*/
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* Replace every token of `provider` found in `text` with its original value.
|
|
348
|
+
* Tokens that do not resolve are left in place and reported. A provider that
|
|
349
|
+
* has its own `restore()` is used through it.
|
|
350
|
+
*
|
|
351
|
+
* @param text - Text containing tokens.
|
|
352
|
+
* @param provider - The provider that issued them.
|
|
353
|
+
* @returns The restored text, the number of restored occurrences and the unresolved tokens.
|
|
354
|
+
*
|
|
355
|
+
* @example
|
|
356
|
+
* ```ts
|
|
357
|
+
* const { text, unresolved } = await restoreTokens(modelOutput, tokenizer);
|
|
358
|
+
* ```
|
|
359
|
+
*/
|
|
360
|
+
declare function restoreTokens(text: string, provider: TokenizationProvider): Promise<RestoreResult>;
|
|
361
|
+
/**
|
|
362
|
+
* Build an engine replacer that tokenizes every value with `provider`.
|
|
363
|
+
*
|
|
364
|
+
* @param provider - The tokenization provider.
|
|
365
|
+
* @param options - `subject` attaches a data-subject reference to every token,
|
|
366
|
+
* for later erasure.
|
|
367
|
+
* @returns A {@link Replacer}; asynchronous unless the provider is synchronous.
|
|
368
|
+
*
|
|
369
|
+
* @example
|
|
370
|
+
* ```ts
|
|
371
|
+
* import { createPipeline, emailDetector } from "anonyma/engine";
|
|
372
|
+
* import { createSessionTokenizer, tokenizeWith } from "anonyma/vault";
|
|
373
|
+
*
|
|
374
|
+
* const session = createSessionTokenizer();
|
|
375
|
+
* const pipeline = createPipeline({
|
|
376
|
+
* detectors: [emailDetector],
|
|
377
|
+
* replace: { fallback: tokenizeWith(session) },
|
|
378
|
+
* });
|
|
379
|
+
* ```
|
|
380
|
+
*/
|
|
381
|
+
declare function tokenizeWith(provider: TokenizationProvider, options?: {
|
|
382
|
+
readonly subject?: string;
|
|
383
|
+
}): Replacer;
|
|
384
|
+
|
|
385
|
+
export { ErasureReceipt, KeyMaterial, KeyRing, KeyRingManifest, type KeyRingOptions, type KeyedTokenizer, type KeyedTokenizerOptions, type MemoryVault, RestoreResult, type RewrapResult, type SealedTokenizer, type SealedTokenizerOptions, TokenContext, TokenVault, TokenizationProvider, VaultRecord, createKeyRing, createKeyedTokenizer, createMemoryVault, createSealedTokenizer, generateKeyMaterial, restoreTokens, rewrapVault, shredKey, tokenizeWith };
|