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