88 lines
2.3 KiB
Markdown
88 lines
2.3 KiB
Markdown
# 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 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:
|
|
|
|
```bash
|
|
bun run setup:python
|
|
```
|
|
|
|
If you prefer manual installation:
|
|
|
|
```bash
|
|
python3 -m venv .venv && .venv/bin/pip install pykeepass
|
|
```
|
|
|
|
The bridge also works with a project-local virtual environment such as `.venv`.
|
|
|
|
## Usage
|
|
|
|
```ts
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
### `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.
|
|
- 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.
|