Initial commit

2026-05-09 23:50:24 +02:00
commit 0d25e52ebc
21 changed files with 867 additions and 0 deletions
@@ -0,0 +1,86 @@
+# 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 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`)
+
+## 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 pip install pykeepass
+```
+
+The bridge also works with a project-local virtual environment such as `.venv` if you want to pin Python dependencies.
+
+## 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, read from the fixture JSON in examples/tests when applicable
+- `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 with the bridge exit code when available.
+- A persistent Python process can be added later if needed.
+- Bundled fixtures include `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`; their companion JSON files store 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`.