KdbxWeb: KeePass KDBX Database Reader/Writer

Common errors

• Error: Argon2 is not implemented. Set it via CryptoEngine.setArgon2Impl

  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.
  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')

  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.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install kdbxweb npm
• yarn add kdbxweb yarn
• pnpm add kdbxweb pnpm

Imports

• Kdbx
  wrong:

  const Kdbx = require('kdbxweb').Kdbx;

  correct:

  import { Kdbx } from 'kdbxweb';

  Primary class for loading, saving, and managing KDBX databases. KdbxWeb is ESM-first and ships TypeScript types.
• Credentials
  wrong:

  const Credentials = require('kdbxweb').Credentials;

  correct:

  import { Credentials } from 'kdbxweb';

  Used for managing database authentication details like passwords and key files.
• ProtectedValue
  wrong:

  const ProtectedValue = require('kdbxweb').ProtectedValue;

  correct:

  import { ProtectedValue } from 'kdbxweb';

  Essential for securely handling sensitive string data like passwords, ensuring they are XORed in memory.
• CryptoEngine
  wrong:

  const CryptoEngine = require('kdbxweb').CryptoEngine;

  correct:

  import { CryptoEngine } from 'kdbxweb';

  Provides methods to configure cryptographic implementations, notably for setting a custom Argon2 hashing function.

Quickstart

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);