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.
Files changed (183) hide show
  1. package/CHANGELOG.md +273 -144
  2. package/README.md +427 -143
  3. package/dist/ai/index.cjs +522 -0
  4. package/dist/ai/index.cjs.map +1 -0
  5. package/dist/ai/index.d.cts +322 -0
  6. package/dist/ai/index.d.ts +322 -0
  7. package/dist/ai/index.js +505 -0
  8. package/dist/ai/index.js.map +1 -0
  9. package/dist/audit/index.cjs +359 -0
  10. package/dist/audit/index.cjs.map +1 -0
  11. package/dist/audit/index.d.cts +287 -0
  12. package/dist/audit/index.d.ts +287 -0
  13. package/dist/audit/index.js +340 -0
  14. package/dist/audit/index.js.map +1 -0
  15. package/dist/chunk-26IHMQHL.cjs +662 -0
  16. package/dist/chunk-26IHMQHL.cjs.map +1 -0
  17. package/dist/chunk-2F2GWGTB.js +174 -0
  18. package/dist/chunk-2F2GWGTB.js.map +1 -0
  19. package/dist/chunk-2NNMJ55L.cjs +45 -0
  20. package/dist/chunk-2NNMJ55L.cjs.map +1 -0
  21. package/dist/chunk-2YG7R4KJ.cjs +114 -0
  22. package/dist/chunk-2YG7R4KJ.cjs.map +1 -0
  23. package/dist/chunk-2ZZHLCEJ.js +237 -0
  24. package/dist/chunk-2ZZHLCEJ.js.map +1 -0
  25. package/dist/chunk-3CY6ATKS.cjs +308 -0
  26. package/dist/chunk-3CY6ATKS.cjs.map +1 -0
  27. package/dist/chunk-3D5ZCJ7R.js +268 -0
  28. package/dist/chunk-3D5ZCJ7R.js.map +1 -0
  29. package/dist/chunk-6LDAIJBL.js +103 -0
  30. package/dist/chunk-6LDAIJBL.js.map +1 -0
  31. package/dist/chunk-7HK2V5Q4.js +111 -0
  32. package/dist/chunk-7HK2V5Q4.js.map +1 -0
  33. package/dist/chunk-AAP472NG.js +177 -0
  34. package/dist/chunk-AAP472NG.js.map +1 -0
  35. package/dist/chunk-AP4JIUNW.js +42 -0
  36. package/dist/chunk-AP4JIUNW.js.map +1 -0
  37. package/dist/chunk-BBJPQPGP.js +457 -0
  38. package/dist/chunk-BBJPQPGP.js.map +1 -0
  39. package/dist/chunk-CRXRJZEV.cjs +82 -0
  40. package/dist/chunk-CRXRJZEV.cjs.map +1 -0
  41. package/dist/chunk-E3PICZYI.js +20 -0
  42. package/dist/chunk-E3PICZYI.js.map +1 -0
  43. package/dist/chunk-F7O2FA3F.cjs +1255 -0
  44. package/dist/chunk-F7O2FA3F.cjs.map +1 -0
  45. package/dist/chunk-FB56NAAH.cjs +243 -0
  46. package/dist/chunk-FB56NAAH.cjs.map +1 -0
  47. package/dist/chunk-G4AN7FND.js +1063 -0
  48. package/dist/chunk-G4AN7FND.js.map +1 -0
  49. package/dist/chunk-GS3FRH4K.js +294 -0
  50. package/dist/chunk-GS3FRH4K.js.map +1 -0
  51. package/dist/chunk-GYMG5OI3.cjs +186 -0
  52. package/dist/chunk-GYMG5OI3.cjs.map +1 -0
  53. package/dist/chunk-IHEIYZPL.cjs +301 -0
  54. package/dist/chunk-IHEIYZPL.cjs.map +1 -0
  55. package/dist/chunk-IJAMLYOT.cjs +1087 -0
  56. package/dist/chunk-IJAMLYOT.cjs.map +1 -0
  57. package/dist/chunk-ISL5B4LU.cjs +181 -0
  58. package/dist/chunk-ISL5B4LU.cjs.map +1 -0
  59. package/dist/chunk-JKW36IPT.js +179 -0
  60. package/dist/chunk-JKW36IPT.js.map +1 -0
  61. package/dist/chunk-KOCQBDI4.cjs +179 -0
  62. package/dist/chunk-KOCQBDI4.cjs.map +1 -0
  63. package/dist/chunk-OGNLB2KA.js +79 -0
  64. package/dist/chunk-OGNLB2KA.js.map +1 -0
  65. package/dist/chunk-PKHZ7CVI.js +28 -0
  66. package/dist/chunk-PKHZ7CVI.js.map +1 -0
  67. package/dist/chunk-QYD4F6T7.cjs +114 -0
  68. package/dist/chunk-QYD4F6T7.cjs.map +1 -0
  69. package/dist/chunk-RCW5IPPR.js +1288 -0
  70. package/dist/chunk-RCW5IPPR.js.map +1 -0
  71. package/dist/chunk-RMMKYHUN.cjs +35 -0
  72. package/dist/chunk-RMMKYHUN.cjs.map +1 -0
  73. package/dist/chunk-S4BJ2ADB.cjs +22 -0
  74. package/dist/chunk-S4BJ2ADB.cjs.map +1 -0
  75. package/dist/chunk-S7NH6CHY.cjs +462 -0
  76. package/dist/chunk-S7NH6CHY.cjs.map +1 -0
  77. package/dist/chunk-SIHPDZXA.js +176 -0
  78. package/dist/chunk-SIHPDZXA.js.map +1 -0
  79. package/dist/chunk-TW7PM3UJ.cjs +30 -0
  80. package/dist/chunk-TW7PM3UJ.cjs.map +1 -0
  81. package/dist/chunk-UA3EOFBS.cjs +1322 -0
  82. package/dist/chunk-UA3EOFBS.cjs.map +1 -0
  83. package/dist/chunk-VE4CCW7W.js +32 -0
  84. package/dist/chunk-VE4CCW7W.js.map +1 -0
  85. package/dist/chunk-W6RBCHYF.js +651 -0
  86. package/dist/chunk-W6RBCHYF.js.map +1 -0
  87. package/dist/chunk-WLJN7GIS.cjs +189 -0
  88. package/dist/chunk-WLJN7GIS.cjs.map +1 -0
  89. package/dist/chunk-YMLR375Z.js +1244 -0
  90. package/dist/chunk-YMLR375Z.js.map +1 -0
  91. package/dist/compliance/index.cjs +88 -0
  92. package/dist/compliance/index.cjs.map +1 -0
  93. package/dist/compliance/index.d.cts +277 -0
  94. package/dist/compliance/index.d.ts +277 -0
  95. package/dist/compliance/index.js +47 -0
  96. package/dist/compliance/index.js.map +1 -0
  97. package/dist/crypto.cjs +12 -136
  98. package/dist/crypto.cjs.map +1 -1
  99. package/dist/crypto.d.cts +4 -3
  100. package/dist/crypto.d.ts +4 -3
  101. package/dist/crypto.js +3 -137
  102. package/dist/crypto.js.map +1 -1
  103. package/dist/detectors/index.cjs +146 -1483
  104. package/dist/detectors/index.cjs.map +1 -1
  105. package/dist/detectors/index.d.cts +1 -1
  106. package/dist/detectors/index.d.ts +1 -1
  107. package/dist/detectors/index.js +3 -1449
  108. package/dist/detectors/index.js.map +1 -1
  109. package/dist/engine/index.cjs +441 -0
  110. package/dist/engine/index.cjs.map +1 -0
  111. package/dist/engine/index.d.cts +728 -0
  112. package/dist/engine/index.d.ts +728 -0
  113. package/dist/engine/index.js +189 -0
  114. package/dist/engine/index.js.map +1 -0
  115. package/dist/hash-2PSYNDMM.cjs +14 -0
  116. package/dist/hash-2PSYNDMM.cjs.map +1 -0
  117. package/dist/hash-CELLDNKN.js +5 -0
  118. package/dist/hash-CELLDNKN.js.map +1 -0
  119. package/dist/index.cjs +153 -2816
  120. package/dist/index.cjs.map +1 -1
  121. package/dist/index.d.cts +93 -11
  122. package/dist/index.d.ts +93 -11
  123. package/dist/index.js +13 -2791
  124. package/dist/index.js.map +1 -1
  125. package/dist/json-CKDvlRtl.d.ts +147 -0
  126. package/dist/json-s8ny-RCo.d.cts +147 -0
  127. package/dist/mcp/index.cjs +751 -0
  128. package/dist/mcp/index.cjs.map +1 -0
  129. package/dist/mcp/index.d.cts +226 -0
  130. package/dist/mcp/index.d.ts +226 -0
  131. package/dist/mcp/index.js +744 -0
  132. package/dist/mcp/index.js.map +1 -0
  133. package/dist/middleware/express.cjs +93 -0
  134. package/dist/middleware/express.cjs.map +1 -0
  135. package/dist/middleware/express.d.cts +90 -0
  136. package/dist/middleware/express.d.ts +90 -0
  137. package/dist/middleware/express.js +91 -0
  138. package/dist/middleware/express.js.map +1 -0
  139. package/dist/middleware/hono.cjs +58 -0
  140. package/dist/middleware/hono.cjs.map +1 -0
  141. package/dist/middleware/hono.d.cts +75 -0
  142. package/dist/middleware/hono.d.ts +75 -0
  143. package/dist/middleware/hono.js +56 -0
  144. package/dist/middleware/hono.js.map +1 -0
  145. package/dist/middleware/index.cjs +24 -0
  146. package/dist/middleware/index.cjs.map +1 -0
  147. package/dist/middleware/index.d.cts +106 -0
  148. package/dist/middleware/index.d.ts +106 -0
  149. package/dist/middleware/index.js +15 -0
  150. package/dist/middleware/index.js.map +1 -0
  151. package/dist/schemas.cjs +5 -5
  152. package/dist/schemas.cjs.map +1 -1
  153. package/dist/schemas.d.cts +20 -10
  154. package/dist/schemas.d.ts +20 -10
  155. package/dist/schemas.js +5 -5
  156. package/dist/schemas.js.map +1 -1
  157. package/dist/session-BdRftyZ5.d.cts +102 -0
  158. package/dist/session-Cs2zlNQp.d.ts +102 -0
  159. package/dist/stream.cjs +13 -2262
  160. package/dist/stream.cjs.map +1 -1
  161. package/dist/stream.d.cts +1 -1
  162. package/dist/stream.d.ts +1 -1
  163. package/dist/stream.js +6 -2255
  164. package/dist/stream.js.map +1 -1
  165. package/dist/types--tPm_AjY.d.ts +199 -0
  166. package/dist/types-0BJH_wqc.d.cts +199 -0
  167. package/dist/types-CPUhjvl8.d.cts +629 -0
  168. package/dist/types-Dtht33aq.d.ts +629 -0
  169. package/dist/{types-D-9HzVuy.d.cts → types-EJTj_BKY.d.cts} +38 -7
  170. package/dist/{types-D-9HzVuy.d.ts → types-EJTj_BKY.d.ts} +38 -7
  171. package/dist/types-Zt_bZvwS.d.cts +182 -0
  172. package/dist/types-Zt_bZvwS.d.ts +182 -0
  173. package/dist/validators.cjs +39 -181
  174. package/dist/validators.cjs.map +1 -1
  175. package/dist/validators.js +1 -174
  176. package/dist/validators.js.map +1 -1
  177. package/dist/vault/index.cjs +688 -0
  178. package/dist/vault/index.cjs.map +1 -0
  179. package/dist/vault/index.d.cts +385 -0
  180. package/dist/vault/index.d.ts +385 -0
  181. package/dist/vault/index.js +669 -0
  182. package/dist/vault/index.js.map +1 -0
  183. 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 };