59 lines
1.8 KiB
Markdown
59 lines
1.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
bun run setup:python
|
|
```
|
|
|
|
Manual alternative:
|
|
|
|
```bash
|
|
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.
|