ts-pykeepass-wrapper/.memory/project.md

kdbx-lib

TypeScript wrapper around pykeepass for read-only access to KeePass .kdbx files.

Architecture

• Public API: TypeScript
• Runtime backend: Python 3
• Bridge: src/python/bridge.py
• Transport: JSON over stdin/stdout
• Backend library: pykeepass

Requirements

• Node.js or Bun
• Python 3
• pykeepass installed in the Python environment used by the bridge
• A project-local .venv works well

Python setup

Install dependencies with:

bun run setup:python

Manual alternative:

python3 -m pip install pykeepass

Core behavior

• Read-only library; it does not modify databases.
• openKeePassDatabase(path, options) opens a database through the Python bridge.
• listEntries() returns all entry fields exposed by the bridge: title, username, password, url, notes, groupPath, and otp when present.
• findEntries(query) performs partial matching and returns full entries.
• listGroups() returns group names and paths.
• close() is currently a no-op.

Fixture facts

• Bundled fixtures: tests/fixtures/data.kdbx and tests/fixtures/empty.kdbx
• Fixture passwords and expected content live in companion JSON files
• data.kdbx contains four entries: root, otp1, f1-item1, f2-item1
• The fixture tree is Racine/ -> root, otp1, Folder1/ -> f1-item1, Folder2/ -> f2-item1
• Integration tests cover entries, groups, and the otp1 OTP/TOTP value
• Canonical OTP value is the full otpauth://... URI returned by pykeepass

Notes

• The bridge currently launches a Python process per call; simple but expensive.
• Errors from the bridge are propagated to TypeScript, including exit code when available.
• The API is still flatter than the real KeePass model.
• More failure-path tests are needed.
• Future improvement: a persistent Python process if performance becomes important.