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

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 +56 -0
  2. package/LICENSE +20 -0
  3. package/README.md +523 -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,56 @@
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 history has the unmodified import as its own commit, so `git diff <import commit> -- 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
+ | 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). |
23
+ | 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). |
24
+ | 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. |
25
+ | `createRandomKeyFile` takes its key from `CryptoEngine.random` alone | `format/kdbx-credentials.ts` | Upstream mixes in `Math.random()`. |
26
+ | 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. |
27
+ | 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. |
28
+ | `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. |
29
+ | 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. |
30
+ | fflate 0.8 | `package.json` | 0.8 rejects some malformed GZIP data that 0.7 accepted; the synchronous API used here is unchanged. |
31
+ | `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. |
32
+ | 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. |
33
+ | `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. |
34
+
35
+ ## Changes to `test/`
36
+
37
+ - Run with Vitest (`npm test`) instead of mocha; `test/setup.ts` maps mocha's `before`/`after` and installs xmldom 0.9 as the DOM.
38
+ - Tests of the removed Node fallbacks and the subtle mock are gone; `CryptoEngine.argon2` is set through `setArgon2Impl` (ES module exports are read-only).
39
+ - Argon2 in tests uses hash-wasm instead of upstream's prebuilt emscripten blob.
40
+ - Resources are read with `fs`; `KdbxUuid` byte assertions compare byte values.
41
+ - 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).
42
+ - 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.
43
+ - `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.
44
+ - 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.
45
+
46
+ ## Build
47
+
48
+ `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`.
49
+
50
+ ## Notes for a security review
51
+
52
+ - 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`.
53
+ - Key handling: `format/kdbx-credentials.ts`, `crypto/key-encryptor-*.ts`, `crypto/protected-value.ts` (XOR-masked in-memory values, not encryption).
54
+ - 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.
55
+ - 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`).
56
+ - 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,524 @@
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
+ KdbxWeb is a high-performance javascript library for reading/writing KeePass v2 databases (kdbx) in node.js or browser.
6
+
7
+ <br />
8
+
9
+ ---
10
+
11
+ <br />
12
+
13
+ - [KdbxWeb ](#kdbxweb--)
14
+ - [Features](#features)
15
+ - [Browser support](#browser-support)
16
+ - [Compatibility](#compatibility)
17
+ - [Kdbx4](#kdbx4)
18
+ - [Usage](#usage)
19
+ - [Loading](#loading)
20
+ - [Saving](#saving)
21
+ - [File info](#file-info)
22
+ - [Changing Credentials](#changing-credentials)
23
+ - [Creation](#creation)
24
+ - [Maintenance](#maintenance)
25
+ - [Merge](#merge)
26
+ - [Groups](#groups)
27
+ - [Group Creation](#group-creation)
28
+ - [Group Deletion](#group-deletion)
29
+ - [Group Move](#group-move)
30
+ - [Recycle Bin](#recycle-bin)
31
+ - [Recursive Traverse](#recursive-traverse)
32
+ - [Entries](#entries)
33
+ - [Entry Creation](#entry-creation)
34
+ - [Entry Modification](#entry-modification)
35
+ - [Entry Deletion](#entry-deletion)
36
+ - [Entry Move](#entry-move)
37
+ - [ProtectedValue](#protectedvalue)
38
+ - [Errors](#errors)
39
+ - [Consts](#consts)
40
+ - [Random](#random)
41
+ - [ByteUtils](#byteutils)
42
+ - [Building](#building)
43
+ - [3rd party libs](#3rd-party-libs)
44
+ - [Tools](#tools)
45
+ - [See it in action](#see-it-in-action)
46
+ - [Extras](#extras)
47
+ - [License](#license)
48
+
49
+
50
+ <br />
51
+
52
+ ---
53
+
54
+ <br />
55
+
56
+ ## Features
57
+
58
+ kdbxweb offers the following feature sets:
59
+
60
+ - runs in browser or node.js
61
+ - no native addons
62
+ - fast encryption with WebCrypto
63
+ - total ≈130kB with dependencies
64
+ - full support of Kdbx features
65
+ - protected values are stored in memory XOR'ed
66
+ - conflict-free merge support
67
+ - high code coverage
68
+ - strict TypeScript
69
+
70
+ <br />
71
+
72
+ ---
73
+
74
+ <br />
75
+
76
+ ## Browser support
77
+
78
+ - All modern browsers
79
+ - Chrome / Chromium
80
+ - Firefox
81
+ - Safari
82
+ - Opera
83
+ - Edge
84
+ - NodeJS
85
+
86
+ <br />
87
+
88
+ ---
89
+
90
+ <br />
91
+
92
+ ## Compatibility
93
+
94
+ 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.
95
+
96
+ <br />
97
+
98
+ ---
99
+
100
+ <br />
101
+
102
+ ## Kdbx4
103
+
104
+ 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:
105
+
106
+ ```ts
107
+ kdbxweb.CryptoEngine.setArgon2Impl((password, salt,
108
+ memory, iterations, length, parallelism, type, version
109
+ ) => {
110
+ // your implementation makes hash (Uint8Array, 'length' bytes)
111
+ return Promise.resolve(hash);
112
+ });
113
+ ```
114
+
115
+ You can find an implementation example in [tests](https://github.com/keeweb/kdbxweb/blob/master/test/test-support/argon2.ts).
116
+
117
+ 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.
118
+
119
+ <br />
120
+
121
+ ---
122
+
123
+ <br />
124
+
125
+ ## Usage
126
+
127
+ This section gives usage examples on how you can implement kdbxweb into your project.
128
+
129
+ <br />
130
+
131
+ ### Loading
132
+
133
+ ```ts
134
+ let credentials = new kdbxweb.Credentials(kdbxweb.ProtectedValue.fromString('demo'),
135
+ keyFileArrayBuffer, challengeResponseFunction);
136
+ const db1 = await kdbxweb.Kdbx.load(dataAsArrayBuffer, credentials);
137
+ const db2 = await kdbxweb.Kdbx.loadXml(dataAsString, credentials);
138
+ ```
139
+
140
+ ### Saving
141
+
142
+ ```ts
143
+ const dataAsArrayBuffer = await db.save();
144
+ const xmlAsString = await db.saveXml();
145
+ ```
146
+
147
+ You can also pretty-print XML:
148
+ ```ts
149
+ const prettyPrintedXml = await db.saveXml(true);
150
+ ```
151
+
152
+ <br />
153
+
154
+ ### File info
155
+
156
+ ```ts
157
+ db.header
158
+ db.meta
159
+ ```
160
+
161
+ See the corresponding type fields inside, they should be obvious.
162
+
163
+ ### Changing Credentials
164
+
165
+ ```ts
166
+ const db = await kdbxweb.Kdbx.load(data, credentials);
167
+ db.credentials.setPassword(kdbxweb.ProtectedValue.fromString('newPass'));
168
+ const randomKeyFile = await kdbxweb.Credentials.createRandomKeyFile();
169
+ db.credentials.setKeyFile(randomKeyFile);
170
+ await db.save();
171
+ ```
172
+
173
+ ### Creation
174
+
175
+ ```ts
176
+ let newDb = kdbxweb.Kdbx.create(credentials, 'My new db');
177
+ let group = newDb.createGroup(newDb.getDefaultGroup(), 'subgroup');
178
+ let entry = newDb.createEntry(group);
179
+ ```
180
+
181
+ <br />
182
+
183
+ ### Maintenance
184
+
185
+ ```ts
186
+ db.cleanup({
187
+ historyRules: true,
188
+ customIcons: true,
189
+ binaries: true
190
+ });
191
+
192
+ // upgrade the db to latest version (currently KDBX4)
193
+ db.upgrade();
194
+
195
+ // downgrade to KDBX3
196
+ db.setVersion(3);
197
+
198
+ // set KDF to AES
199
+ db.setKdf(kdbxweb.Consts.KdfId.Aes);
200
+ ```
201
+
202
+ <br />
203
+
204
+ ### Merge
205
+
206
+ Entries, groups and meta are consistent against merging in any direction with any state.
207
+ Due to format limitations, p2p entry history merging and some non-critical fields in meta can produce phantom records or deletions,
208
+ so correct entry history merging is supported only with one central replica. Items order is not guaranteed but the algorithm tries to preserve it.
209
+
210
+ ```ts
211
+ let db = await kdbxweb.Kdbx.load(data, credentials); // load local db
212
+ // work with db
213
+ db.save(); // save local db
214
+ let editStateBeforeSave = db.getLocalEditState(); // save local editing state (serializable to JSON)
215
+ db.close(); // close local db
216
+
217
+ db = kdbxweb.Kdbx.load(data, credentials); // reopen it again
218
+ db.setLocalEditState(editStateBeforeSave); // assign edit state obtained before save
219
+
220
+ // work with db
221
+ let remoteDb = await kdbxweb.Kdbx.load(remoteData, credentials); // load remote db
222
+ db.merge(remoteDb); // merge remote into local
223
+ delete remoteDb; // don't use remoteDb anymore
224
+
225
+ let saved = await db.save(); // save local db
226
+ editStateBeforeSave = db.getLocalEditState(); // save local editing state again
227
+
228
+ let pushedOk = pushToUpstream(saved); // push db to upstream
229
+ if (pushedOk) {
230
+ db.removeLocalEditState(); // clear local editing state
231
+ editStateBeforeSave = null; // and discard it
232
+ }
233
+ ```
234
+
235
+ <br />
236
+
237
+ ### Groups
238
+
239
+ ```ts
240
+ let defaultGroup = db.getDefaultGroup();
241
+ let anotherGroup = db.getGroup(uuid);
242
+ let deepGroup = defaultGroup.groups[1].groups[2];
243
+ ```
244
+
245
+ <br />
246
+
247
+ ### Group Creation
248
+
249
+ ```ts
250
+ let group = db.createGroup(db.getDefaultGroup(), 'New group');
251
+ let anotherGroup = db.createGroup(group, 'Subgroup');
252
+ ```
253
+
254
+ <br />
255
+
256
+ ### Group Deletion
257
+
258
+ ```ts
259
+ db.remove(group);
260
+ ```
261
+
262
+ <br />
263
+
264
+ ### Group Move
265
+
266
+ ```ts
267
+ db.move(group, toGroup);
268
+ db.move(group, toGroup, atIndex);
269
+ ```
270
+
271
+ <br />
272
+
273
+ ### Recycle Bin
274
+
275
+ ```ts
276
+ let recycleBin = db.getGroup(db.meta.recycleBinUuid);
277
+ if (!recycleBin) {
278
+ db.createRecycleBin();
279
+ }
280
+ ```
281
+
282
+ <br />
283
+
284
+ ### Recursive Traverse
285
+
286
+ ```ts
287
+ for (const entry of group.allEntries()) { /* ... */ }
288
+ for (const group of group.allGroups()) { /* ... */ }
289
+ for (const entryOrGroup of group.allGroupsAndEntries()) { /* ... */ }
290
+ ```
291
+
292
+ <br />
293
+
294
+ ### Entries
295
+
296
+ ```ts
297
+ let entry = db.getDefaultGroup().entries[0];
298
+ entry.fields.AccountNumber = '1234 5678';
299
+ entry.fields.Pin = kdbxweb.ProtectedValue.fromString('4321');
300
+ ```
301
+
302
+ <br />
303
+
304
+ ### Entry Creation
305
+
306
+ ```ts
307
+ let entry = db.createEntry(group);
308
+ ```
309
+
310
+ <br />
311
+
312
+ ### Entry Modification
313
+
314
+ ```ts
315
+ // push current state to history stack
316
+ entry.pushHistory();
317
+
318
+ // change something
319
+ entry.fgColor = '#ff0000';
320
+
321
+ // update entry modification and access time
322
+ entry.times.update();
323
+
324
+ // remove states from entry history
325
+ entry.removeHistory(index, count);
326
+ ```
327
+
328
+ <br />
329
+
330
+ > [!WARNING]
331
+ > Do **not** modify history states directly; this will break merge.
332
+
333
+ <br />
334
+
335
+ ### Entry Deletion
336
+
337
+ ```ts
338
+ db.remove(entry);
339
+ ```
340
+
341
+ <br />
342
+
343
+ ### Entry Move
344
+
345
+ ```ts
346
+ db.move(entry, toGroup);
347
+ ```
348
+
349
+ If you're moving an entry from another file, this is called _import_:
350
+
351
+ ```ts
352
+ db.importEntry(entry, toGroup, sourceFile);
353
+ ```
354
+
355
+ <br />
356
+
357
+ ### ProtectedValue
358
+
359
+ Used for passwords and custom fields, stored the value in memory XOR'ed
360
+
361
+ ```ts
362
+ let value = new kdbxweb.ProtectedValue(xoredByted, saltBytes);
363
+ let valueFromString = kdbxweb.ProtectedValue.fromString('str');
364
+ let valueFromBinary = kdbxweb.ProtectedValue.fromBinary(data);
365
+ let textString = value.getText();
366
+ let binaryData = value.getBinary();
367
+ let includesSubString = value.includes('foo');
368
+ ```
369
+
370
+ <br />
371
+
372
+ ### Errors
373
+
374
+ ```ts
375
+ try {
376
+ await kdbxweb.Kdbx.load(data, credentials);
377
+ } catch (e) {
378
+ if (e instanceof kdbxweb.KdbxError && e.code === kdbxweb.Consts.ErrorCodes.BadSignature) {
379
+ /* ... */
380
+ }
381
+ }
382
+ ```
383
+
384
+ <br />
385
+
386
+ ### Consts
387
+
388
+ [Consts definition](https://github.com/keeweb/kdbxweb/blob/master/lib/defs/consts.ts)
389
+
390
+ ```ts
391
+ kdbxweb.Consts.ErrorCodes // all thrown errors have code property
392
+ kdbxweb.Consts.Defaults // default db settings
393
+ kdbxweb.Consts.Icons // icons map
394
+ ```
395
+
396
+ <br />
397
+
398
+ ### Random
399
+
400
+ ```ts
401
+ let randomArray = kdbxweb.Crypto.random(/* desired length */ 100);
402
+ ```
403
+
404
+ <br />
405
+
406
+ ### ByteUtils
407
+
408
+ ```ts
409
+ kdbxweb.ByteUtils.bytesToString(bytes);
410
+ kdbxweb.ByteUtils.stringToBytes(str);
411
+ kdbxweb.ByteUtils.bytesToBase64(bytes);
412
+ kdbxweb.ByteUtils.base64ToBytes(str);
413
+ kdbxweb.ByteUtils.bytesToHex(bytes);
414
+ kdbxweb.ByteUtils.hexToBytes(str);
415
+ ```
416
+
417
+ <br />
418
+
419
+ ---
420
+
421
+ <br />
422
+
423
+ ## Building
424
+
425
+ > [!NOTE]
426
+ > This project requires node v18.18.0.
427
+
428
+ <br />
429
+
430
+ Use npm to build this project:
431
+
432
+ ```sh
433
+ npm run build
434
+ ```
435
+
436
+ <br />
437
+
438
+ To run tests:
439
+
440
+ ```sh
441
+ npm test
442
+ ```
443
+
444
+ <br />
445
+
446
+ ---
447
+
448
+ <br />
449
+
450
+ ## 3rd party libs
451
+
452
+ kdbxweb includes these 3rd party libraries:
453
+ - [fflate](https://github.com/101arrowz/fflate)
454
+ - [xmldom](https://github.com/xmldom/xmldom)
455
+
456
+ <br />
457
+
458
+ ---
459
+
460
+ <br />
461
+
462
+ ## Tools
463
+
464
+ The library provides a number of scripts to work with KDBX files:
465
+
466
+ Dump the binary header:
467
+
468
+ ```sh
469
+ npm run script:dump-header my-db.kdbx
470
+ ```
471
+
472
+ <br />
473
+
474
+ Print detailed size information about internal objects:
475
+
476
+ ```sh
477
+ npm run script:kdbx-size-profiler my-db.kdbx password
478
+ ```
479
+
480
+ <br />
481
+
482
+ Dump the internal XML:
483
+
484
+ ```sh
485
+ npm run script:kdbx-to-xml my-db.kdbx password
486
+ ```
487
+
488
+ <br />
489
+
490
+ Generate big files for load testing:
491
+
492
+ ```sh
493
+ npm run script:make-big-files
494
+ ```
495
+
496
+ <br />
497
+
498
+ ---
499
+
500
+ <br />
501
+
502
+ ## See it in action
503
+
504
+ This library is used in **[KeeWeb](https://app.keeweb.info)**
505
+
506
+ <br />
507
+
508
+ ---
509
+
510
+ <br />
511
+
512
+ ## Extras
513
+
514
+ 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)**.
515
+
516
+ <br />
517
+
518
+ ---
519
+
520
+ <br />
521
+
522
+ ## License
523
+
524
+ MIT