kdbx-lib

TypeScript wrapper around pykeepass for reading KeePass .kdbx files.

Overview

This project uses:

• TypeScript as the public API
• Python as the runtime backend
• pykeepass to read KeePass databases

The TypeScript layer launches a Python bridge and exchanges JSON through stdin/stdout.

Requirements

• Node.js or Bun
• Python 3
• pykeepass installed in the Python environment used by the bridge (the project provides bun run setup:python)
• The bridge defaults to .venv/bin/python3 when available, or you can override with PYTHON_PATH

Python setup

Install pykeepass in the Python environment used by the bridge:

bun run setup:python

If you prefer manual installation:

python3 -m venv .venv && .venv/bin/pip install pykeepass

The bridge also works with a project-local virtual environment such as .venv and the tests will use it when present.

Usage

import { openKeePassDatabase } from "./src/keepass";

const db = openKeePassDatabase("tests/fixtures/data.kdbx", {
	password: "123",
});

const entries = await db.listEntries();
console.log(entries);

Example

Run the example using the bundled data fixture credentials:

bun run src/example.ts

API

openKeePassDatabase(path, options)

Creates a database wrapper.

Options

• password: KeePass master password, read from the fixture JSON in examples/tests when applicable
• keyFile: optional key file path

listEntries()

Returns all entries in the database, with every entry field exposed by the bridge (title, username, password, url, notes, groupPath, otp when present).

findEntries(query)

Finds entries by partial match and returns the full entry objects.

listGroups()

Returns all groups, including their names and paths.

close()

No-op for now.

Notes

• The bridge currently launches a Python process per call.
• This is simple and robust for a first version.
• Errors from the Python bridge are propagated to the TypeScript API with the bridge exit code when available.
• A persistent Python process can be added later if needed.
• Bundled fixtures include tests/fixtures/data.kdbx and tests/fixtures/empty.kdbx; their companion JSON files store the password and expected content for tests/examples.
• Integration tests validate the bundled data.kdbx entry-by-entry and group-by-group against tests/fixtures/data.kdbx.json.