KdbxWeb is a high-performance javascript library for reading/writing KeePass v2 databases (kdbx) in node.js or browser.
Features
runs in browser or node.js
no native addons
fast encryption with WebCrypto
total ≈130kB with dependencies
full support of Kdbx features
protected values are stored in memory XOR'ed
conflict-free merge support
high code coverage
strict TypeScript
Browser support
modern browsers: Chrome, Firefox, Safari, Opera, Edge
node.js
Compatibility
Supported formats are Kdbx3 and Kdbx4, current KeePass file format. Old kdb files (for KeePass v1) are out of scope of this library.
Kdbx4
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:
kdbxweb.CryptoEngine.setArgon2Impl((password, salt, memory, iterations, length, parallelism, type, version) => { // your implementation makes hash (Uint8Array, 'length' bytes) return Promise.resolve(hash);});
let newDb = kdbxweb.Kdbx.create(credentials, 'My new db');let group = newDb.createGroup(newDb.getDefaultGroup(), 'subgroup');let entry = newDb.createEntry(group);
Maintenance
db.cleanup({ historyRules: true, customIcons: true, binaries: true});// upgrade the db to latest version (currently KDBX4)db.upgrade();// downgrade to KDBX3db.setVersion(3);// set KDF to AESdb.setKdf(kdbxweb.Consts.KdfId.Aes);
Merge
Entries, groups and meta are consistent against merging in any direction with any state.
Due to format limitations, p2p entry history merging and some non-critical fields in meta can produce phantom records or deletions,
so correct entry history merging is supported only with one central replica. Items order is not guaranteed but the algorithm tries to preserve it.
let db = await kdbxweb.Kdbx.load(data, credentials); // load local db// work with dbdb.save(); // save local dblet editStateBeforeSave = db.getLocalEditState(); // save local editing state (serializable to JSON)db.close(); // close local dbdb = kdbxweb.Kdbx.load(data, credentials); // reopen it againdb.setLocalEditState(editStateBeforeSave); // assign edit state obtained before save// work with dblet remoteDb = await kdbxweb.Kdbx.load(remoteData, credentials); // load remote dbdb.merge(remoteDb); // merge remote into localdelete remoteDb; // don't use remoteDb anymorelet saved
Groups
let defaultGroup = db.getDefaultGroup();let anotherGroup = db.getGroup(uuid);let deepGroup = defaultGroup.groups[1].groups[2];
Group creation
let group = db.createGroup(db.getDefaultGroup(), 'New group');let anotherGroup = db.createGroup(group, 'Subgroup');
let recycleBin = db.getGroup(db.meta.recycleBinUuid);if (!recycleBin) { db.createRecycleBin();}
Recursive traverse
for (const entry of group.allEntries()) { /* ... */ }for (const group of group.allGroups()) { /* ... */ }for (const entryOrGroup of group.allGroupsAndEntries()) { /* ... */ }
Entries
let entry = db.getDefaultGroup().entries[0];entry.fields.AccountNumber = '1234 5678';entry.fields.Pin = kdbxweb.ProtectedValue.fromString('4321');
Entry creation
let entry = db.createEntry(group);
Entry modification
// push current state to history stackentry.pushHistory();// change somethingentry.fgColor = '#ff0000';// update entry modification and access timeentry.times.update();// remove states from entry historyentry.removeHistory(index, count);
Important: don't modify history states directly, this will break merge.
Entry deletion
db.remove(entry);
Entry move
db.move(entry, toGroup);
If you're moving an entry from another file, this is called import:
db.importEntry(entry, toGroup, sourceFile);
ProtectedValue
Used for passwords and custom fields, stored the value in memory XOR'ed
let value = new kdbxweb.ProtectedValue(xoredByted, saltBytes);let valueFromString = kdbxweb.ProtectedValue.fromString('str');let valueFromBinary = kdbxweb.ProtectedValue.fromBinary(data);let textString = value.getText();let binaryData = value.getBinary();let includesSubString = value.includes('foo');