@varlock/keepass-plugin

@varlock/keepass-plugin

This package is a Varlock plugin that enables loading secrets from KeePass / KeePassXC databases (KDBX 4.0) into your configuration.

Features

• KDBX 4.0 support — reads KeePass database files directly via kdbxweb with pure WASM argon2
• KeePassXC CLI integration — use keepassxc-cli for development workflows
• Key file support — authenticate with password + optional key file
• Custom attributes — read any entry field via #attribute syntax
• Bulk loading with kpBulk() via @setValuesBulk to load all entries in a group
• Custom attributes object — load all custom fields from a single entry via customAttributesObj=true
• Multiple instances for accessing different databases

Installation

If you are in a JavaScript based project and have a package.json file, you can either install the plugin explicitly:

npm install @varlock/keepass-plugin

And then register the plugin without any version number:

# @plugin(@varlock/keepass-plugin)
# ---

Otherwise just set the explicit version number when you register it:

# @plugin(@varlock/keepass-plugin@0.0.1)
# ---

See our Plugin Guide for more details.

Modes of operation

File mode (default)

In file mode, the plugin opens and reads .kdbx files directly using kdbxweb. No external CLI is needed.

# @plugin(@varlock/keepass-plugin)
# @initKeePass(dbPath="./secrets.kdbx", password=$KP_PASSWORD)
# ---

CLI mode

When useCli=true, the plugin uses keepassxc-cli to read entries. This is useful during development when you want to leverage KeePassXC's system integration (e.g., YubiKey, Windows Hello). The useCli option can be dynamic — for example, useCli=forEnv(dev) to only use the CLI in development.

# @plugin(@varlock/keepass-plugin)
# @initKeePass(dbPath="./secrets.kdbx", password=$KP_PASSWORD, useCli=true)
# ---

Prerequisites for CLI mode

You must have KeePassXC installed, which includes keepassxc-cli:

# macOS
brew install --cask keepassxc

# Ubuntu/Debian
sudo apt install keepassxc

# Fedora/RHEL
sudo dnf install keepassxc

# Arch
pacman -S keepassxc

See KeePassXC downloads for more options.

Setup

After registering the plugin, initialize it with the @initKeePass root decorator.

Basic setup

# @plugin(@varlock/keepass-plugin)
# @initKeePass(dbPath="./secrets.kdbx", password=$KP_PASSWORD)
# ---

# @type=kdbxPassword @sensitive @internal
KP_PASSWORD=

With key file

# @plugin(@varlock/keepass-plugin)
# @initKeePass(dbPath="./secrets.kdbx", password=$KP_PASSWORD, keyFile="./secrets.keyx")
# ---

Multiple databases

# @plugin(@varlock/keepass-plugin)
# @initKeePass(id=prod, dbPath="./prod.kdbx", password=$KP_PROD_PASSWORD)
# @initKeePass(id=dev, dbPath="./dev.kdbx", password=$KP_DEV_PASSWORD)
# ---

PROD_DB_PASS=kp(prod, "Database/production")
DEV_DB_PASS=kp(dev, "Database/development")

Loading secrets

Once initialized, use the kp() resolver to fetch secrets.

Basic usage

# Fetch password (default attribute) from an entry
DB_PASSWORD=kp("Database/production")

# Fetch a different attribute using #attribute syntax
DB_USER=kp("Database/production#UserName")
DB_URL=kp("Database/production#URL")

# Read a custom string field
API_KEY=kp("Services/stripe#SecretKey")

Inferring entry name from key

When the env var key matches a KeePass entry title, you can omit the entry path:

# Looks up entry titled "DB_PASSWORD", reads the Password field
DB_PASSWORD=kp()

# Looks up entry titled "DB_USER", reads the UserName field
DB_USER=kp("#UserName")

Named attribute param

You can also use the attribute named param as an alternative to #attribute:

DB_USER=kp("Database/production", attribute=UserName)

Entry paths

Entry paths use forward slashes to separate groups from the entry title:

Group/SubGroup/EntryTitle

For example, if your KeePass database has:

• Root
  • Database
    • production (entry with Password, UserName fields)
  • Services
    • stripe (entry with a custom "SecretKey" field)

You would reference them as "Database/production" and "Services/stripe".

Custom attributes object

Use customAttributesObj=true to load all custom (non-standard) fields from a single entry as a JSON object. This is useful with @setValuesBulk to expand custom fields into env vars:

# Given an entry "Database/production" with custom fields: HOST, PORT, DB_NAME
# @setValuesBulk(kp("Database/production", customAttributesObj=true), createMissing=true)
# ---
HOST=
PORT=
DB_NAME=

Standard fields (Title, Password, UserName, URL, Notes) are excluded — only custom fields are included.

Bulk loading secrets

Use kpBulk() with @setValuesBulk to fetch the Password field from all entries under a group:

# @plugin(@varlock/keepass-plugin)
# @initKeePass(dbPath="./secrets.kdbx", password=$KP_PASSWORD)
# @setValuesBulk(kpBulk(Production), createMissing=true)
# ---

# These will be populated from entries under the "Production" group
DB_PASSWORD=
API_KEY=

# Load all entries from the database root
# @setValuesBulk(kpBulk())

# Load from a specific group
# @setValuesBulk(kpBulk("Services/APIs"))

# With a named instance
# @setValuesBulk(kpBulk(prod, Production))

Entry paths in the JSON output are sanitized to valid env var names (uppercased, non-alphanumeric characters replaced with underscores).

Reference

Root decorators

@initKeePass()

Initialize a KeePass plugin instance.

Parameter	Type	Required	Description
dbPath	string	yes	Path to the .kdbx database file
password	string	yes	Master password (typically from an env var like $KP_PASSWORD)
keyFile	string	no	Path to a key file for additional authentication
useCli	boolean	no	Use keepassxc-cli instead of reading the file directly (default: false). Can be dynamic, e.g. useCli=forEnv(dev)
id	string	no	Instance identifier for multiple databases (defaults to _default)

Data types

kdbxPassword

A sensitive string type for KeePass database master passwords. Validates that the value is a non-empty string.

Resolver functions

kp()

Fetch a single entry field from a KeePass database.

Signatures:

• kp() — infer entry name from key, read Password field
• kp(entryPath) — read Password field
• kp("entryPath#Attribute") — read a specific attribute
• kp("#Attribute") — infer entry name from key, read a specific attribute
• kp(entryPath, attribute=X) — read a specific attribute (named param)
• kp(instanceId, entryPath) — read from a named database instance
• kp(entryPath, customAttributesObj=true) — return all custom fields as a JSON object

Returns: The field value as a string, or a JSON object string when customAttributesObj=true.

kpBulk()

Fetch the Password field from all entries under a group as a JSON map. Intended for use with @setValuesBulk.

Signatures:

• kpBulk() — load all entries from the database root
• kpBulk(groupPath) — load entries under a specific group
• kpBulk(instanceId, groupPath) — load from a named instance

Returns: JSON string of { "ENTRY_NAME": "password", ... } pairs. Entry paths are sanitized to valid env var names.

Troubleshooting

Invalid credentials

• Check that the database password is correct
• If using a key file, verify the path is correct and the file matches the database

Entry not found

• Entry paths are case-sensitive
• Use forward slashes to separate groups: "Group/SubGroup/Entry"
• In CLI mode, list entries with: keepassxc-cli ls <database.kdbx>

keepassxc-cli not found (CLI mode only)

• Install KeePassXC which includes the CLI (see Prerequisites)
• Ensure keepassxc-cli is in your PATH

Database file not found

• Check the dbPath value — it's resolved relative to the working directory
• Use an absolute path if needed

Resources

• KeePassXC — cross-platform KeePass-compatible password manager
• KeePass — original KeePass Password Safe
• KDBX format — KeePass database format specification
• kdbxweb — JavaScript KDBX reader library