ts-pykeepass-wrapper/README.md

kdbx-lib

TypeScript wrapper around pykeepass for reading and modifying KeePass .kdbx files.

Overview

This project uses:

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

The TypeScript layer launches a Python bridge per request 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, 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.

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

createEntry(entry)

Creates a new entry in the target database and persists it immediately.

Entry input

• title: entry title
• username: optional username
• password: optional password
• url: optional URL
• notes: optional notes
• groupPath: optional target group path

createGroup(group)

Creates a new group and persists it immediately.

Group input

• name: group name
• path: optional parent group path

save()

Persists the current database state.

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, including invalid or empty output.
• A persistent Python process can be added later if needed.
• Write operations currently open, modify, and save the database per command.
• Bundled fixtures include tests/fixtures/data.kdbx and tests/fixtures/empty.kdbx; the companion JSON file stores 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, and may skip cleanly when pykeepass is unavailable.