KeePassHTTP Secrets Skill

Codex skill for reading credentials from a local KeePass database through the KeePassHTTP plugin while minimizing exposure of secret values.

This project is designed for local use. It does not ship with credentials, database files, KeePass configuration, or machine-specific association state.

What It Does

• Creates a one-time KeePassHTTP client association for the current machine and user profile.
• Stores only the KeePassHTTP client id and AES key in a local state file.
• Reuses that association for later read-only lookups.
• Reads narrow fields such as login, password, title, uuid, or count.
• Defaults to count output so accidental invocations do not dump decrypted entries.

Requirements

• Python 3.11 or newer.
• Poetry.
• KeePass with the KeePassHTTP plugin enabled.
• An unlocked KeePass database, or permission for KeePassHTTP to trigger an unlock prompt.

Install

make install

make install installs Python dependencies and starts the one-time association flow. Approve the new client in KeePass when prompted.

The association is stored at:

~/.config/keepasshttp-secrets/client.json

That file is machine-local secret material. Do not commit or publish it.

Usage

Create or refresh the association:

make associate

Force a new association:

make reauthorize

Count matching entries:

poetry run python scripts/read_secret.py https://example.com

Read the first matching login:

poetry run python scripts/read_secret.py https://example.com --field login --first

Read the first matching password only when explicitly needed:

poetry run python scripts/read_secret.py https://example.com --field password --first

Inspect full decrypted matching entries only when necessary:

poetry run python scripts/read_secret.py https://example.com --field json

Configuration

The default KeePassHTTP endpoint is:

http://localhost:19455

Override it per command:

poetry run python scripts/read_secret.py https://example.com --endpoint http://localhost:19455

Or via environment:

KEEPASSHTTP_ENDPOINT=http://localhost:19455 poetry run python scripts/read_secret.py https://example.com

Use a separate client state file:

poetry run python scripts/read_secret.py https://example.com --client-file ./client.json

Or via environment:

KEEPASSHTTP_CLIENT_FILE=./client.json poetry run python scripts/read_secret.py https://example.com

Safety Rules

• Never publish client.json, KeePass databases, exported credentials, logs containing decrypted values, or screenshots with secrets.
• Prefer --field count, --field login, --field title, or --field uuid before using --field password.
• Use --field json only for deliberate debugging or inspection.
• Do not paste decrypted payloads into issue trackers, pull requests, chat, or logs.

Test

make test

The test target validates project metadata, compiles the helper, runs unit tests, and checks CLI help without contacting KeePassHTTP.

License

BSD 3-Clause License. See LICENSE.

Publishing Checklist

• Run make test.
• Confirm git status --short does not include __pycache__, *.pyc, client.json, or other local state.
• Confirm the BSD 3-Clause license text and copyright holder are correct.