@keenext/kdbxweb 0.0.0-stage → 2.2.0-keenext.3

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 (38) hide show
  1. package/FORK.md +57 -0
  2. package/LICENSE +20 -0
  3. package/README.md +525 -2
  4. package/dist/index.js +5750 -0
  5. package/dist/index.js.map +7 -0
  6. package/dist/types/crypto/chacha20.d.ts +11 -0
  7. package/dist/types/crypto/crypto-engine.d.ts +27 -0
  8. package/dist/types/crypto/hashed-block-transform.d.ts +2 -0
  9. package/dist/types/crypto/hmac-block-transform.d.ts +4 -0
  10. package/dist/types/crypto/key-encryptor-aes.d.ts +2 -0
  11. package/dist/types/crypto/key-encryptor-kdf.d.ts +2 -0
  12. package/dist/types/crypto/protect-salt-generator.d.ts +12 -0
  13. package/dist/types/crypto/protected-value.d.ts +20 -0
  14. package/dist/types/crypto/salsa20.d.ts +17 -0
  15. package/dist/types/crypto/twofish.d.ts +22 -0
  16. package/dist/types/defs/consts.d.ts +119 -0
  17. package/dist/types/defs/xml-names.d.ts +94 -0
  18. package/dist/types/errors/kdbx-error.d.ts +5 -0
  19. package/dist/types/format/kdbx-binaries.d.ts +34 -0
  20. package/dist/types/format/kdbx-context.d.ts +10 -0
  21. package/dist/types/format/kdbx-credentials.d.ts +16 -0
  22. package/dist/types/format/kdbx-custom-data.d.ts +12 -0
  23. package/dist/types/format/kdbx-deleted-object.d.ts +9 -0
  24. package/dist/types/format/kdbx-entry.d.ts +94 -0
  25. package/dist/types/format/kdbx-format.d.ts +43 -0
  26. package/dist/types/format/kdbx-group.d.ts +49 -0
  27. package/dist/types/format/kdbx-header.d.ts +74 -0
  28. package/dist/types/format/kdbx-meta.d.ts +110 -0
  29. package/dist/types/format/kdbx-times.d.ts +16 -0
  30. package/dist/types/format/kdbx-uuid.d.ts +11 -0
  31. package/dist/types/format/kdbx.d.ts +184 -0
  32. package/dist/types/index.d.ts +32 -0
  33. package/dist/types/utils/binary-stream.d.ts +38 -0
  34. package/dist/types/utils/byte-utils.d.ts +11 -0
  35. package/dist/types/utils/int64.d.ts +9 -0
  36. package/dist/types/utils/var-dictionary.d.ts +28 -0
  37. package/dist/types/utils/xml-utils.d.ts +42 -0
  38. package/package.json +46 -4
package/FORK.md ADDED
@@ -0,0 +1,57 @@
1
+ # kdbxweb fork
2
+
3
+ Fork of [keeweb/kdbxweb](https://github.com/keeweb/kdbxweb) (MIT, see `LICENSE`) used by KeeNext.
4
+
5
+ Base: upstream `master` at `7601e45d2a437f35a7fa3d767164eab60bc05d42` (2024-12-23, after release 2.1.1; adds the `DriveWindows` icon fix and build tooling). The repository keeps upstream's history up to that commit, so `git diff 7601e45 -- lib test` shows every change listed here.
6
+
7
+ ## Changes to `lib/`
8
+
9
+ | Change | Files | Why |
10
+ |---|---|---|
11
+ | Twofish-256-CBC (PKCS#7) as third data cipher, `CipherId.Twofish` | `crypto/twofish.ts` (new), `crypto/crypto-engine.ts`, `format/kdbx-format.ts`, `defs/consts.ts` | KeePassXC, KeePassDX and KeePass (plugin) offer Twofish; such files could not be opened. |
12
+ | WebCrypto only: removed the Node `crypto`/`Buffer` fallbacks for SHA, HMAC, AES and random | `crypto/crypto-engine.ts`, `utils/byte-utils.ts` | WebCrypto, `atob`/`btoa` are global in all browsers and Node ≥ 19. One code path to review instead of two; no `import 'crypto'` to stub in bundles. |
13
+ | No built-in `@xmldom/xmldom`; `DOMParser`/`XMLSerializer` come from `globalThis` | `utils/xml-utils.ts` | The bundled xmldom 0.8 had open advisories and was only reachable in Node. Node users install a DOM implementation themselves (`test/setup.ts`). |
14
+ | `KdbxBinaries.computeHashes` keeps file order | `format/kdbx-binaries.ts` | Hashes resolved in arbitrary order with WebCrypto, so the binary pool (and the order of attachments in saved files) changed between saves. |
15
+ | Explicit `ArrayBuffer` conversions where `Uint8Array`s were passed as `ArrayBuffer` | `format/kdbx-header.ts`, `format/kdbx-uuid.ts`, `format/kdbx-credentials.ts`, `format/kdbx-format.ts`, `crypto/key-encryptor-kdf.ts`, `crypto/protected-value.ts`, `utils/byte-utils.ts` | Older TypeScript accepted this; TypeScript ≥ 5.7 does not. `KdbxUuid.toBytes()` now really returns an `ArrayBuffer` as declared. `ProtectedValue.clone()` copies explicitly. |
16
+ | Type-only names exported with `export type` | `index.ts` | Per-file transpilers (Vite, Vitest) otherwise emit exports that are `undefined` at runtime. |
17
+ | Reads past the end of a `BinaryStream` throw `FileCorrupt` | `utils/binary-stream.ts` | Upstream shortens such reads silently or throws `RangeError`; parsers of the header, inner header, `VarDictionary` and block streams now get exactly the announced number of bytes or a `KdbxError`. |
18
+ | Header: unknown field ids are skipped; compression flags, transform rounds, inner random stream id and inner-header binaries are length-checked | `format/kdbx-header.ts` | Upstream crashes with `TypeError` on unknown ids; KeePass and KeePassXC skip them. |
19
+ | Encryption IV length checked per cipher (AES and Twofish 16 bytes, ChaCha20 12); ChaCha20 gets a 12-byte IV in KDBX 3 as well | `format/kdbx-format.ts`, `format/kdbx-header.ts` | Upstream writes a 16-byte IV for ChaCha20 in KDBX 3, which KeePassXC rejects. |
20
+ | The HMAC of the empty final block of the KDBX 4 block stream is verified | `crypto/hmac-block-transform.ts` | Upstream accepts a stream cut at a block boundary followed by a forged final block. |
21
+ | Tabs survive XML parsing | `utils/xml-utils.ts` | Upstream's control-character filter removes tabs from all unprotected fields. |
22
+ | Tags are split at `;`, `,` and `:` alone; the surrounding whitespace is trimmed afterwards | `utils/xml-utils.ts` | Upstream's `\s*[;,:]\s*` takes quadratic time on long runs of whitespace: 40,000 spaces in a tags field take seconds, a few hundred kilobytes block the page for minutes. |
23
+ | Binary dates after 9999-12-31 are clamped to it; unparsable text dates and binary dates shorter than 8 bytes read as absent | `utils/xml-utils.ts` | KeePassDX writes dates far beyond; upstream throws `too large number` and the file does not open (upstream issue #48). |
24
+ | KDBX 4.1 `LastModificationTime` of custom data and custom icons is written in binary | `format/kdbx-custom-data.ts`, `format/kdbx-meta.ts` | Upstream writes ISO text, which KeePass rejects (upstream issue #49, PR #62). |
25
+ | An attachment whose binary is missing from the pool is skipped; the entry's other attachments are written | `format/kdbx-entry.ts` | Upstream drops every attachment after the missing one. |
26
+ | `createRandomKeyFile` takes its key from `CryptoEngine.random` alone | `format/kdbx-credentials.ts` | Upstream mixes in `Math.random()`. |
27
+ | Saving raises KDBX 4.0 to 4.1 when the database holds values only 4.1 stores: group tags, a disabled quality check, a previous parent group, custom icon names or times, custom data times (`Kdbx.hasKdbx41Values`). KDBX 3.1 becomes 4.1 for the same values except a previous parent group, keeping its AES-KDF and rounds (`KdbxHeader.upgradeToKdbx4KeepingAesKdf`) | `format/kdbx.ts`, `format/kdbx-format.ts`, `format/kdbx-header.ts` | Upstream drops these values from older files. KeePassXC raises files to 4.1 for the same values, KDBX 3.1 already when an object was moved; here a move alone keeps 3.1, so clients that only read KDBX 3 keep working. |
28
+ | Key files: XML whose root is not `KeyFile`, and `KeyFile` documents without key data, are hashed as a whole | `format/kdbx-credentials.ts` | Upstream rejects them; KeePassXC hashes them, so databases created there with e.g. an SVG as key file did not open. |
29
+ | `KdbxFormat` uses `async`/`await`; the credential hash, derived key, master key, cipher and HMAC keys and the header and per-block HMAC keys are zeroed in `finally` | `format/kdbx-format.ts`, `crypto/hmac-block-transform.ts` | Upstream zeroes them only on the success path: a wrong password leaves the master key (KDBX 3) or the cipher and HMAC keys (KDBX 4) in memory, and the header and per-block HMAC keys are never zeroed. |
30
+ | Protected values of XML nodes are kept in a `WeakMap` (`XmlUtils.getNodeProtectedValue`, `setNodeProtectedValue`) | `utils/xml-utils.ts` | Upstream stores them as an expando property declared on the global `Node` interface, which leaks into the DOM types of every consumer. |
31
+ | fflate 0.8 | `package.json` | 0.8 rejects some malformed GZIP data that 0.7 accepted; the synchronous API used here is unchanged. |
32
+ | `Kdbx.load(data, credentials, { signal })`: aborting the `AbortSignal` stops the key derivation and rejects with its reason. AES-KDF checks it between chunks of 10,000 rounds; `Argon2Fn` implementations receive it as last argument | `format/kdbx.ts`, `format/kdbx-format.ts`, `crypto/key-encryptor-kdf.ts`, `crypto/key-encryptor-aes.ts`, `crypto/crypto-engine.ts` | The rounds come from the file; the application needs a way to cancel an unlock that would take hours. |
33
+ | AES-KDF runs its chunks one after another instead of building the whole promise chain up front | `crypto/key-encryptor-aes.ts` | Upstream allocates one promise per 10,000 rounds before the first one runs, so a file with 2^50 rounds freezes the page. |
34
+ | `KdbxEntry.copyFrom` also copies custom data, quality check and previous parent group; `KdbxGroup.copyFrom` also copies tags, custom data and previous parent group; `importEntry` clears the previous parent group | `format/kdbx-entry.ts`, `format/kdbx-group.ts`, `format/kdbx-custom-data.ts`, `format/kdbx.ts` | Merge, history snapshots and `importEntry` copy through `copyFrom`; upstream loses these properties there, e.g. KeePassXC's browser settings in entry custom data on every sync merge. |
35
+
36
+ ## Changes to `test/`
37
+
38
+ - Run with Vitest (`npm test`) instead of mocha; `test/setup.ts` maps mocha's `before`/`after` and installs xmldom 0.9 as the DOM.
39
+ - Tests of the removed Node fallbacks and the subtle mock are gone; `CryptoEngine.argon2` is set through `setArgon2Impl` (ES module exports are read-only).
40
+ - Argon2 in tests uses hash-wasm instead of upstream's prebuilt emscripten blob.
41
+ - Resources are read with `fs`; `KdbxUuid` byte assertions compare byte values.
42
+ - New: `test/crypto/twofish.spec.ts` (known-answer tests from the Twofish submission, CBC round trips, wrong-key handling). Interoperability with KeePassXC is covered by the app's `tests/compat` (files written by KeePassXC with Twofish, and files written here, opened by KeePassXC).
43
+ - Each `lib/` change in the table above that changes behaviour has a regression test next to the tests of the file it changes; `kdbx.spec.ts` covers the ones that need a save and load (attachments, tabs, KDBX 4.1 times and values, IV length, import, abort, zeroed keys after a wrong password), `kdbx.merge.spec.ts` the merge of custom data and tags. The `WeakMap` and fflate changes are covered by the existing suite. The app's `tests/compat` checks the KDBX 4.1 values and the hashed key files against KeePassXC.
44
+ - `kdbx-entry.spec.ts` and `kdbx-group.spec.ts` check that `copyFrom` copies every own property of a fresh instance except an explicit list; a property added to the class fails there until the test populates it.
45
+ - Two upstream tests expected the lenient `BinaryStream`: `binary-stream.spec.ts` reads zero bytes at the end instead of five, and the bad-compression test in `kdbx-header.spec.ts` uses a complete 4-byte field.
46
+
47
+ ## Build
48
+
49
+ `npm run build` writes an ESM bundle to `dist/index.js` (for Node scripts) and type declarations to `dist/types`. KeeNext bundles `dist/index.js`.
50
+
51
+ ## Notes for a security review
52
+
53
+ - Untrusted input: the whole KDBX file (header fields, inner header, XML). Parsing entry points: `format/kdbx-format.ts` (`load`), `format/kdbx-header.ts`, `utils/var-dictionary.ts`, `utils/xml-utils.ts`.
54
+ - Key handling: `format/kdbx-credentials.ts`, `crypto/key-encryptor-*.ts`, `crypto/protected-value.ts` (XOR-masked in-memory values, not encryption).
55
+ - Integrity: KDBX 4 header HMAC and HMAC block stream (`crypto/hmac-block-transform.ts`); KDBX 3 relies on stream start bytes and the hashed block stream.
56
+ - KDF parameters (AES-KDF rounds, Argon2 memory, iterations, parallelism) come from the file without upper bounds and run before the key can be verified. The library offers cancellation (`signal`); limits belong to the application (KeeNext: `core/database.ts`, `DEFAULT_KDF_LIMITS`).
57
+ - Logic as in upstream and worth reviewing first: the XML handling of protected values (`XmlUtils.setProtectedValues`, `updateProtectedValuesSalt`, `getProtectedText`), the ChaCha20/Salsa20 implementations, the CRDT logic of `merge` (`KdbxGroup.mergeCollection`, `KdbxEntry.mergeHistory`).
package/LICENSE ADDED
@@ -0,0 +1,20 @@
1
+ Copyright (C) 2021-2025 Antelle
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,526 @@
1
- # Temporary Holding Version
1
+ # KdbxWeb
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ This is a fork of [keeweb/kdbxweb](https://github.com/keeweb/kdbxweb), published as `@keenext/kdbxweb` and maintained for KeeNext. What differs from upstream is listed in [FORK.md](FORK.md); everything below is upstream's documentation.
4
+
5
+ The fork is used by KeeNext, which is alpha software. It has not been independently audited and is provided without warranty, see [LICENSE](LICENSE).
6
+
7
+ KdbxWeb is a high-performance javascript library for reading/writing KeePass v2 databases (kdbx) in node.js or browser.
8
+
9
+ <br />
10
+
11
+ ---
12
+
13
+ <br />
14
+
15
+ - [KdbxWeb ](#kdbxweb--)
16
+ - [Features](#features)
17
+ - [Browser support](#browser-support)
18
+ - [Compatibility](#compatibility)
19
+ - [Kdbx4](#kdbx4)
20
+ - [Usage](#usage)
21
+ - [Loading](#loading)
22
+ - [Saving](#saving)
23
+ - [File info](#file-info)
24
+ - [Changing Credentials](#changing-credentials)
25
+ - [Creation](#creation)
26
+ - [Maintenance](#maintenance)
27
+ - [Merge](#merge)
28
+ - [Groups](#groups)
29
+ - [Group Creation](#group-creation)
30
+ - [Group Deletion](#group-deletion)
31
+ - [Group Move](#group-move)
32
+ - [Recycle Bin](#recycle-bin)
33
+ - [Recursive Traverse](#recursive-traverse)
34
+ - [Entries](#entries)
35
+ - [Entry Creation](#entry-creation)
36
+ - [Entry Modification](#entry-modification)
37
+ - [Entry Deletion](#entry-deletion)
38
+ - [Entry Move](#entry-move)
39
+ - [ProtectedValue](#protectedvalue)
40
+ - [Errors](#errors)
41
+ - [Consts](#consts)
42
+ - [Random](#random)
43
+ - [ByteUtils](#byteutils)
44
+ - [Building](#building)
45
+ - [3rd party libs](#3rd-party-libs)
46
+ - [Tools](#tools)
47
+ - [See it in action](#see-it-in-action)
48
+ - [Extras](#extras)
49
+ - [License](#license)
50
+
51
+
52
+ <br />
53
+
54
+ ---
55
+
56
+ <br />
57
+
58
+ ## Features
59
+
60
+ kdbxweb offers the following feature sets:
61
+
62
+ - runs in browser or node.js
63
+ - no native addons
64
+ - fast encryption with WebCrypto
65
+ - total ≈130kB with dependencies
66
+ - full support of Kdbx features
67
+ - protected values are stored in memory XOR'ed
68
+ - conflict-free merge support
69
+ - high code coverage
70
+ - strict TypeScript
71
+
72
+ <br />
73
+
74
+ ---
75
+
76
+ <br />
77
+
78
+ ## Browser support
79
+
80
+ - All modern browsers
81
+ - Chrome / Chromium
82
+ - Firefox
83
+ - Safari
84
+ - Opera
85
+ - Edge
86
+ - NodeJS
87
+
88
+ <br />
89
+
90
+ ---
91
+
92
+ <br />
93
+
94
+ ## Compatibility
95
+
96
+ Supported formats are Kdbx3 and Kdbx4, current KeePass file format. Old kdb files (for KeePass v1) are out of scope of this library. We currently have no plans to support the older formats.
97
+
98
+ <br />
99
+
100
+ ---
101
+
102
+ <br />
103
+
104
+ ## Kdbx4
105
+
106
+ Kdbx4 has introduced Argon2, a new hashing function. Due to complex calculations, you have to implement it manually and export to kdbxweb, if you want to support such files. Here's how:
107
+
108
+ ```ts
109
+ kdbxweb.CryptoEngine.setArgon2Impl((password, salt,
110
+ memory, iterations, length, parallelism, type, version
111
+ ) => {
112
+ // your implementation makes hash (Uint8Array, 'length' bytes)
113
+ return Promise.resolve(hash);
114
+ });
115
+ ```
116
+
117
+ You can find an implementation example in [tests](https://github.com/keeweb/kdbxweb/blob/master/test/test-support/argon2.ts).
118
+
119
+ It's not compiled into the library because there's no universal way to provide a fast implementation, so it's up to you to choose the best one.
120
+
121
+ <br />
122
+
123
+ ---
124
+
125
+ <br />
126
+
127
+ ## Usage
128
+
129
+ This section gives usage examples on how you can implement kdbxweb into your project.
130
+
131
+ <br />
132
+
133
+ ### Loading
134
+
135
+ ```ts
136
+ let credentials = new kdbxweb.Credentials(kdbxweb.ProtectedValue.fromString('demo'),
137
+ keyFileArrayBuffer, challengeResponseFunction);
138
+ const db1 = await kdbxweb.Kdbx.load(dataAsArrayBuffer, credentials);
139
+ const db2 = await kdbxweb.Kdbx.loadXml(dataAsString, credentials);
140
+ ```
141
+
142
+ ### Saving
143
+
144
+ ```ts
145
+ const dataAsArrayBuffer = await db.save();
146
+ const xmlAsString = await db.saveXml();
147
+ ```
148
+
149
+ You can also pretty-print XML:
150
+ ```ts
151
+ const prettyPrintedXml = await db.saveXml(true);
152
+ ```
153
+
154
+ <br />
155
+
156
+ ### File info
157
+
158
+ ```ts
159
+ db.header
160
+ db.meta
161
+ ```
162
+
163
+ See the corresponding type fields inside, they should be obvious.
164
+
165
+ ### Changing Credentials
166
+
167
+ ```ts
168
+ const db = await kdbxweb.Kdbx.load(data, credentials);
169
+ db.credentials.setPassword(kdbxweb.ProtectedValue.fromString('newPass'));
170
+ const randomKeyFile = await kdbxweb.Credentials.createRandomKeyFile();
171
+ db.credentials.setKeyFile(randomKeyFile);
172
+ await db.save();
173
+ ```
174
+
175
+ ### Creation
176
+
177
+ ```ts
178
+ let newDb = kdbxweb.Kdbx.create(credentials, 'My new db');
179
+ let group = newDb.createGroup(newDb.getDefaultGroup(), 'subgroup');
180
+ let entry = newDb.createEntry(group);
181
+ ```
182
+
183
+ <br />
184
+
185
+ ### Maintenance
186
+
187
+ ```ts
188
+ db.cleanup({
189
+ historyRules: true,
190
+ customIcons: true,
191
+ binaries: true
192
+ });
193
+
194
+ // upgrade the db to latest version (currently KDBX4)
195
+ db.upgrade();
196
+
197
+ // downgrade to KDBX3
198
+ db.setVersion(3);
199
+
200
+ // set KDF to AES
201
+ db.setKdf(kdbxweb.Consts.KdfId.Aes);
202
+ ```
203
+
204
+ <br />
205
+
206
+ ### Merge
207
+
208
+ Entries, groups and meta are consistent against merging in any direction with any state.
209
+ Due to format limitations, p2p entry history merging and some non-critical fields in meta can produce phantom records or deletions,
210
+ so correct entry history merging is supported only with one central replica. Items order is not guaranteed but the algorithm tries to preserve it.
211
+
212
+ ```ts
213
+ let db = await kdbxweb.Kdbx.load(data, credentials); // load local db
214
+ // work with db
215
+ db.save(); // save local db
216
+ let editStateBeforeSave = db.getLocalEditState(); // save local editing state (serializable to JSON)
217
+ db.close(); // close local db
218
+
219
+ db = kdbxweb.Kdbx.load(data, credentials); // reopen it again
220
+ db.setLocalEditState(editStateBeforeSave); // assign edit state obtained before save
221
+
222
+ // work with db
223
+ let remoteDb = await kdbxweb.Kdbx.load(remoteData, credentials); // load remote db
224
+ db.merge(remoteDb); // merge remote into local
225
+ delete remoteDb; // don't use remoteDb anymore
226
+
227
+ let saved = await db.save(); // save local db
228
+ editStateBeforeSave = db.getLocalEditState(); // save local editing state again
229
+
230
+ let pushedOk = pushToUpstream(saved); // push db to upstream
231
+ if (pushedOk) {
232
+ db.removeLocalEditState(); // clear local editing state
233
+ editStateBeforeSave = null; // and discard it
234
+ }
235
+ ```
236
+
237
+ <br />
238
+
239
+ ### Groups
240
+
241
+ ```ts
242
+ let defaultGroup = db.getDefaultGroup();
243
+ let anotherGroup = db.getGroup(uuid);
244
+ let deepGroup = defaultGroup.groups[1].groups[2];
245
+ ```
246
+
247
+ <br />
248
+
249
+ ### Group Creation
250
+
251
+ ```ts
252
+ let group = db.createGroup(db.getDefaultGroup(), 'New group');
253
+ let anotherGroup = db.createGroup(group, 'Subgroup');
254
+ ```
255
+
256
+ <br />
257
+
258
+ ### Group Deletion
259
+
260
+ ```ts
261
+ db.remove(group);
262
+ ```
263
+
264
+ <br />
265
+
266
+ ### Group Move
267
+
268
+ ```ts
269
+ db.move(group, toGroup);
270
+ db.move(group, toGroup, atIndex);
271
+ ```
272
+
273
+ <br />
274
+
275
+ ### Recycle Bin
276
+
277
+ ```ts
278
+ let recycleBin = db.getGroup(db.meta.recycleBinUuid);
279
+ if (!recycleBin) {
280
+ db.createRecycleBin();
281
+ }
282
+ ```
283
+
284
+ <br />
285
+
286
+ ### Recursive Traverse
287
+
288
+ ```ts
289
+ for (const entry of group.allEntries()) { /* ... */ }
290
+ for (const group of group.allGroups()) { /* ... */ }
291
+ for (const entryOrGroup of group.allGroupsAndEntries()) { /* ... */ }
292
+ ```
293
+
294
+ <br />
295
+
296
+ ### Entries
297
+
298
+ ```ts
299
+ let entry = db.getDefaultGroup().entries[0];
300
+ entry.fields.AccountNumber = '1234 5678';
301
+ entry.fields.Pin = kdbxweb.ProtectedValue.fromString('4321');
302
+ ```
303
+
304
+ <br />
305
+
306
+ ### Entry Creation
307
+
308
+ ```ts
309
+ let entry = db.createEntry(group);
310
+ ```
311
+
312
+ <br />
313
+
314
+ ### Entry Modification
315
+
316
+ ```ts
317
+ // push current state to history stack
318
+ entry.pushHistory();
319
+
320
+ // change something
321
+ entry.fgColor = '#ff0000';
322
+
323
+ // update entry modification and access time
324
+ entry.times.update();
325
+
326
+ // remove states from entry history
327
+ entry.removeHistory(index, count);
328
+ ```
329
+
330
+ <br />
331
+
332
+ > [!WARNING]
333
+ > Do **not** modify history states directly; this will break merge.
334
+
335
+ <br />
336
+
337
+ ### Entry Deletion
338
+
339
+ ```ts
340
+ db.remove(entry);
341
+ ```
342
+
343
+ <br />
344
+
345
+ ### Entry Move
346
+
347
+ ```ts
348
+ db.move(entry, toGroup);
349
+ ```
350
+
351
+ If you're moving an entry from another file, this is called _import_:
352
+
353
+ ```ts
354
+ db.importEntry(entry, toGroup, sourceFile);
355
+ ```
356
+
357
+ <br />
358
+
359
+ ### ProtectedValue
360
+
361
+ Used for passwords and custom fields, stored the value in memory XOR'ed
362
+
363
+ ```ts
364
+ let value = new kdbxweb.ProtectedValue(xoredByted, saltBytes);
365
+ let valueFromString = kdbxweb.ProtectedValue.fromString('str');
366
+ let valueFromBinary = kdbxweb.ProtectedValue.fromBinary(data);
367
+ let textString = value.getText();
368
+ let binaryData = value.getBinary();
369
+ let includesSubString = value.includes('foo');
370
+ ```
371
+
372
+ <br />
373
+
374
+ ### Errors
375
+
376
+ ```ts
377
+ try {
378
+ await kdbxweb.Kdbx.load(data, credentials);
379
+ } catch (e) {
380
+ if (e instanceof kdbxweb.KdbxError && e.code === kdbxweb.Consts.ErrorCodes.BadSignature) {
381
+ /* ... */
382
+ }
383
+ }
384
+ ```
385
+
386
+ <br />
387
+
388
+ ### Consts
389
+
390
+ [Consts definition](https://github.com/keeweb/kdbxweb/blob/master/lib/defs/consts.ts)
391
+
392
+ ```ts
393
+ kdbxweb.Consts.ErrorCodes // all thrown errors have code property
394
+ kdbxweb.Consts.Defaults // default db settings
395
+ kdbxweb.Consts.Icons // icons map
396
+ ```
397
+
398
+ <br />
399
+
400
+ ### Random
401
+
402
+ ```ts
403
+ let randomArray = kdbxweb.Crypto.random(/* desired length */ 100);
404
+ ```
405
+
406
+ <br />
407
+
408
+ ### ByteUtils
409
+
410
+ ```ts
411
+ kdbxweb.ByteUtils.bytesToString(bytes);
412
+ kdbxweb.ByteUtils.stringToBytes(str);
413
+ kdbxweb.ByteUtils.bytesToBase64(bytes);
414
+ kdbxweb.ByteUtils.base64ToBytes(str);
415
+ kdbxweb.ByteUtils.bytesToHex(bytes);
416
+ kdbxweb.ByteUtils.hexToBytes(str);
417
+ ```
418
+
419
+ <br />
420
+
421
+ ---
422
+
423
+ <br />
424
+
425
+ ## Building
426
+
427
+ > [!NOTE]
428
+ > This project requires node v18.18.0.
429
+
430
+ <br />
431
+
432
+ Use npm to build this project:
433
+
434
+ ```sh
435
+ npm run build
436
+ ```
437
+
438
+ <br />
439
+
440
+ To run tests:
441
+
442
+ ```sh
443
+ npm test
444
+ ```
445
+
446
+ <br />
447
+
448
+ ---
449
+
450
+ <br />
451
+
452
+ ## 3rd party libs
453
+
454
+ kdbxweb includes these 3rd party libraries:
455
+ - [fflate](https://github.com/101arrowz/fflate)
456
+ - [xmldom](https://github.com/xmldom/xmldom)
457
+
458
+ <br />
459
+
460
+ ---
461
+
462
+ <br />
463
+
464
+ ## Tools
465
+
466
+ The library provides a number of scripts to work with KDBX files:
467
+
468
+ Dump the binary header:
469
+
470
+ ```sh
471
+ npm run script:dump-header my-db.kdbx
472
+ ```
473
+
474
+ <br />
475
+
476
+ Print detailed size information about internal objects:
477
+
478
+ ```sh
479
+ npm run script:kdbx-size-profiler my-db.kdbx password
480
+ ```
481
+
482
+ <br />
483
+
484
+ Dump the internal XML:
485
+
486
+ ```sh
487
+ npm run script:kdbx-to-xml my-db.kdbx password
488
+ ```
489
+
490
+ <br />
491
+
492
+ Generate big files for load testing:
493
+
494
+ ```sh
495
+ npm run script:make-big-files
496
+ ```
497
+
498
+ <br />
499
+
500
+ ---
501
+
502
+ <br />
503
+
504
+ ## See it in action
505
+
506
+ This library is used in **[KeeWeb](https://app.keeweb.info)**
507
+
508
+ <br />
509
+
510
+ ---
511
+
512
+ <br />
513
+
514
+ ## Extras
515
+
516
+ We also provide a template for **[HexFiend](https://github.com/ridiculousfish/HexFiend)** to explore the contents of KDBX files, you can find it **[here](format)**.
517
+
518
+ <br />
519
+
520
+ ---
521
+
522
+ <br />
523
+
524
+ ## License
525
+
526
+ MIT