{"id":17281,"library":"kdbxweb","title":"KdbxWeb: KeePass KDBX Database Reader/Writer","description":"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.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/keeweb/kdbxweb","tags":["javascript","kdbx","keepass","typescript"],"install":[{"cmd":"npm install kdbxweb","lang":"bash","label":"npm"},{"cmd":"yarn add kdbxweb","lang":"bash","label":"yarn"},{"cmd":"pnpm add kdbxweb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary class for loading, saving, and managing KDBX databases. KdbxWeb is ESM-first and ships TypeScript types.","wrong":"const Kdbx = require('kdbxweb').Kdbx;","symbol":"Kdbx","correct":"import { Kdbx } from 'kdbxweb';"},{"note":"Used for managing database authentication details like passwords and key files.","wrong":"const Credentials = require('kdbxweb').Credentials;","symbol":"Credentials","correct":"import { Credentials } from 'kdbxweb';"},{"note":"Essential for securely handling sensitive string data like passwords, ensuring they are XORed in memory.","wrong":"const ProtectedValue = require('kdbxweb').ProtectedValue;","symbol":"ProtectedValue","correct":"import { ProtectedValue } from 'kdbxweb';"},{"note":"Provides methods to configure cryptographic implementations, notably for setting a custom Argon2 hashing function.","wrong":"const CryptoEngine = require('kdbxweb').CryptoEngine;","symbol":"CryptoEngine","correct":"import { CryptoEngine } from 'kdbxweb';"}],"quickstart":{"code":"import { Kdbx, Credentials, ProtectedValue, Consts, CryptoEngine } from 'kdbxweb';\n\n// Dummy Argon2 implementation for KDBX4 support (required for real-world use)\nCryptoEngine.setArgon2Impl((password, salt, memory, iterations, length, parallelism, type, version) => {\n    // In a real application, you'd use a robust Argon2 library here (e.g., argon2-browser).\n    // This is a placeholder for demonstration purposes and will not actually hash.\n    console.warn('Using dummy Argon2 implementation. Provide a real one for KDBX4 support.');\n    const dummyHash = new Uint8Array(length).fill(0xAA);\n    return Promise.resolve(dummyHash);\n});\n\nasync function manageKeePassDatabase() {\n    const masterPassword = ProtectedValue.fromString('mySuperSecretPassword');\n    const credentials = new Credentials(masterPassword);\n\n    // 1. Create a new database\n    console.log('Creating a new database...');\n    let newDb = Kdbx.create(credentials, 'My New KeePass Database');\n    newDb.setKdf(Consts.KdfId.Aes); // Set KDF to AES\n\n    const defaultGroup = newDb.getDefaultGroup();\n    const subgroup = newDb.createGroup(defaultGroup, 'Web Logins');\n    const entry = newDb.createEntry(subgroup);\n    entry.fields.Title = 'Example Website';\n    entry.fields.UserName = 'demo';\n    entry.fields.Password = ProtectedValue.fromString('demoPass123');\n    entry.fields.URL = 'https://example.com';\n\n    // 2. Save the new database\n    const newDbBuffer = await newDb.save();\n    console.log(`New database saved. Size: ${newDbBuffer.byteLength} bytes`);\n\n    // 3. Load the database back (simulating opening an existing file)\n    console.log('Loading database from buffer...');\n    const loadedDb = await Kdbx.load(newDbBuffer, credentials);\n    const loadedEntry = loadedDb.getDefaultGroup().groups[0].entries[0];\n    console.log(`Loaded entry title: ${loadedEntry.fields.Title}`);\n    console.log(`Loaded entry username: ${loadedEntry.fields.UserName}`);\n    console.log(`Loaded entry password: ${loadedEntry.fields.Password.getText()}`);\n\n    // 4. Update credentials and save again\n    console.log('Changing master password and saving...');\n    const newMasterPassword = ProtectedValue.fromString('evenMoreSecurePassword');\n    loadedDb.credentials.setPassword(newMasterPassword);\n    const updatedDbBuffer = await loadedDb.save();\n    console.log(`Database updated and saved. New size: ${updatedDbBuffer.byteLength} bytes`);\n\n    console.log('Database operations complete.');\n}\n\nmanageKeePassDatabase().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"For 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"KdbxWeb 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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).","cause":"Attempting to load a KDBX4 database file that uses Argon2 as its Key Derivation Function (KDF) without providing a custom Argon2 implementation to kdbxweb.","error":"Error: Argon2 is not implemented. Set it via CryptoEngine.setArgon2Impl"},{"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.","cause":"This error can occur if you try to load an unsupported Kdbx v1 (`.kdb`) file. The library expects a Kdbx v2 (`.kdbx`) file format.","error":"Error: Cannot read properties of undefined (reading 'length')"}],"ecosystem":"npm","meta_description":null}