Registry / database / kdbxweb

kdbxweb

JSON →
library2.1.1jsnpmunverified

KdbxWeb is a high-performance JavaScript library for reading and writing KeePass v2 databases, specifically supporting Kdbx3 and Kdbx4 file formats. It functions seamlessly in both Node.js environments and modern web browsers, maintaining a compact size of approximately 130kB including its internal dependencies. Key features include fast encryption powered by WebCrypto, secure in-memory handling of protected values using XORing, and robust capabilities for conflict-free merging of database states. While offering comprehensive Kdbx feature support, it's crucial to note that the library does not support older KeePass v1 `.kdb` files. For Kdbx4 files utilizing Argon2, users are required to provide their own Argon2 implementation, as it's not bundled to allow for optimal platform-specific performance choices. The current stable version is 2.1.1, with releases typically following development needs rather than a fixed cadence.

npm install kdbxweb
INSTALL
IMPORT
SIG · KDBXWEB
K
kdbxweb
databasejavascriptv2.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Kdbx
import { Kdbx } from 'kdbxweb';
const Kdbx = require('kdbxweb').Kdbx;
Primary class for loading, saving, and managing KDBX databases. KdbxWeb is ESM-first and ships TypeScript types.
Credentials
import { Credentials } from 'kdbxweb';
const Credentials = require('kdbxweb').Credentials;
Used for managing database authentication details like passwords and key files.
ProtectedValue
import { ProtectedValue } from 'kdbxweb';
const ProtectedValue = require('kdbxweb').ProtectedValue;
Essential for securely handling sensitive string data like passwords, ensuring they are XORed in memory.
CryptoEngine
import { CryptoEngine } from 'kdbxweb';
const CryptoEngine = require('kdbxweb').CryptoEngine;
Provides methods to configure cryptographic implementations, notably for setting a custom Argon2 hashing function.

Demonstrates creating a new KDBX database, adding groups and entries, saving it to a buffer, loading it back, and updating its master password, including the necessary Argon2 implementation setup.

import { Kdbx, Credentials, ProtectedValue, Consts, CryptoEngine } from 'kdbxweb'; // Dummy Argon2 implementation for KDBX4 support (required for real-world use) CryptoEngine.setArgon2Impl((password, salt, memory, iterations, length, parallelism, type, version) => { // In a real application, you'd use a robust Argon2 library here (e.g., argon2-browser). // This is a placeholder for demonstration purposes and will not actually hash. console.warn('Using dummy Argon2 implementation. Provide a real one for KDBX4 support.'); const dummyHash = new Uint8Array(length).fill(0xAA); return Promise.resolve(dummyHash); }); async function manageKeePassDatabase() { const masterPassword = ProtectedValue.fromString('mySuperSecretPassword'); const credentials = new Credentials(masterPassword); // 1. Create a new database console.log('Creating a new database...'); let newDb = Kdbx.create(credentials, 'My New KeePass Database'); newDb.setKdf(Consts.KdfId.Aes); // Set KDF to AES const defaultGroup = newDb.getDefaultGroup(); const subgroup = newDb.createGroup(defaultGroup, 'Web Logins'); const entry = newDb.createEntry(subgroup); entry.fields.Title = 'Example Website'; entry.fields.UserName = 'demo'; entry.fields.Password = ProtectedValue.fromString('demoPass123'); entry.fields.URL = 'https://example.com'; // 2. Save the new database const newDbBuffer = await newDb.save(); console.log(`New database saved. Size: ${newDbBuffer.byteLength} bytes`); // 3. Load the database back (simulating opening an existing file) console.log('Loading database from buffer...'); const loadedDb = await Kdbx.load(newDbBuffer, credentials); const loadedEntry = loadedDb.getDefaultGroup().groups[0].entries[0]; console.log(`Loaded entry title: ${loadedEntry.fields.Title}`); console.log(`Loaded entry username: ${loadedEntry.fields.UserName}`); console.log(`Loaded entry password: ${loadedEntry.fields.Password.getText()}`); // 4. Update credentials and save again console.log('Changing master password and saving...'); const newMasterPassword = ProtectedValue.fromString('evenMoreSecurePassword'); loadedDb.credentials.setPassword(newMasterPassword); const updatedDbBuffer = await loadedDb.save(); console.log(`Database updated and saved. New size: ${updatedDbBuffer.byteLength} bytes`); console.log('Database operations complete.'); } manageKeePassDatabase().catch(console.error);
Debug
Known issues
breakingFor KeePass KDBX4 files that utilize Argon2 as their Key Derivation Function (KDF), KdbxWeb requires developers to provide their own Argon2 implementation. The library does not bundle Argon2 due to the complexity of providing a universally fast and efficient solution across various JavaScript environments (Node.js, browser, Web Workers). Failing to set an Argon2 implementation will prevent opening KDBX4 files encrypted with Argon2.
fix
Implement and set a custom Argon2 hashing function using `kdbxweb.CryptoEngine.setArgon2Impl(argon2Function)`. An example can be found in the KdbxWeb tests or by integrating a library like `argon2-browser` or a Node.js-specific Argon2 package.
affects: >=1.0.0
gotchaKdbxWeb explicitly does not support older KeePass v1 database files (those with a `.kdb` extension). It is designed exclusively for KeePass v2 and later, which use the `.kdbx` format (Kdbx3 and Kdbx4). Attempts to load a `.kdb` file will result in an error.
fix
Ensure that the database file is in the KDBX format (KeePass v2 or later). Convert old `.kdb` files to `.kdbx` using the official KeePass desktop application if necessary.
affects: >=1.0.0
gotchaWhile KdbxWeb supports conflict-free merging of entries, groups, and metadata, merging of entry history and certain non-critical meta fields in a peer-to-peer fashion can lead to 'phantom records' or unintentional deletions. Correct entry history merging is primarily supported with one central replica.
fix
When merging, consider using a central replica strategy for critical fields like entry history. Be aware that the order of items is not strictly guaranteed during merge operations, although the algorithm attempts to preserve it where possible.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Argon2 is not implemented. Set it via CryptoEngine.setArgon2Impl
Attempting to load a KDBX4 database file that uses Argon2 as its Key Derivation Function (KDF) without providing a custom Argon2 implementation to kdbxweb.
fix
You must provide a JavaScript implementation of Argon2 to `kdbxweb.CryptoEngine.setArgon2Impl()`. This often involves integrating a dedicated Argon2 library for your environment (e.g., `argon2-browser` for web or an `argon2` package for Node.js).
Error: Cannot read properties of undefined (reading 'length')
This error can occur if you try to load an unsupported Kdbx v1 (`.kdb`) file. The library expects a Kdbx v2 (`.kdbx`) file format.
fix
Verify that the database file you are attempting to load is a Kdbx v2 or v4 `.kdbx` file. Older `.kdb` files are not supported. If you have a `.kdb` file, you need to convert it to `.kdbx` using the KeePass desktop application.
Upgrade
Version history
2.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
1
Resources
kdbxweb — npm install kdbxweb · libregistry