feat: add KeePass plugin for KDBX 4.0 database support by qades · Pull Request #413 · dmno-dev/varlock

qades · 2026-03-15T19:52:50Z

Summary

Adds @varlock/keepass-plugin for loading secrets from KeePass / KeePassXC databases (KDBX 4.0).

Based on the original contribution by @qades, with significant rework.

Plugin features

kp() resolver with #attribute syntax (kp("entry#UserName")), entry name inference from key (kp(), kp("#Attr")), and customAttributesObj=true for bulk custom field loading
kpBulk() resolver for loading all passwords from a group via @setValuesBulk
kdbxPassword data type for master password validation
File mode using kdbxweb with pure WASM argon2 via hash-wasm (no native addons, works in SEA builds)
CLI mode via keepassxc-cli with dynamic useCli option (e.g., useCli=forEnv(dev))
Multiple database instances via id param
Key file authentication support

Changes from original PR

Replaced native argon2 addon with hash-wasm (pure WASM, base64-embedded, SEA-compatible)
Renamed useDesktopApp to useCli, now resolved at runtime (supports forEnv())
Removed unnecessary CLI batching (varlock already parallelizes resolutions)
Added #attribute syntax as primary way to specify entry fields
Added entry name inference from key
Added customAttributesObj=true for bulk custom field loading
Removed attribute param from kpBulk (always reads Password)
Build as CJS matching other plugins, single self-contained bundle
Uses import { plugin } from 'varlock/plugin-lib' instead of global
Added input option to spawnAsync in @env-spec/utils

Testing & docs

Added pluginTest() helper (varlock/test-helpers) — reusable for all plugin packages
Added comprehensive tests (20 tests) with programmatically generated KDBX databases
Added website docs page, sidebar entry, overview listing
Updated README
Added changeset

Test plan

All 20 keepass plugin tests pass
All 328 existing varlock tests pass
Lint clean (0 errors)
Build succeeds (single CJS bundle, ~590KB)
Verify website docs page renders correctly
Test with real KeePassXC database

🤖 Generated with Claude Code

changeset-bot · 2026-03-15T19:52:54Z

🦋 Changeset detected

Latest commit: 5a8370c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@varlock/keepass-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

socket-security · 2026-03-15T19:53:44Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@babel/core@7.29.0
	@astrojs/partytown@2.1.6
	@astrojs/vue@5.1.4
	@astrojs/sitemap@3.7.2
	@astrojs/mdx@4.3.14
	@astrojs/starlight@0.37.7

View full report

qades · 2026-03-15T20:01:22Z

Full test folder, with executable "test" script.

test-keepass-plugin.zip

theoephraim

Thanks for this! Looks pretty good :)

Left a few small comments.

packages/plugins/keepass/src/cli-helper.ts

theoephraim · 2026-03-16T04:02:06Z

packages/plugins/keepass/src/kdbx-reader.ts

+  /**
+   * Find an entry by its path (e.g., "Group/SubGroup/EntryTitle").
+   */
+  private findEntry(db: kdbxweb.Kdbx, entryPath: string): kdbxweb.KdbxEntry | undefined {


Is it worth doing a single pass putting everything into a hash with keys being the format used by the plugin? Make sure its only on the first actual read though, because we dont ever want to trigger an error if the plugin is not being used in the current resolution.

packages/plugins/keepass/src/plugin.ts

* feat: add KeePass plugin for KDBX 4.0 database and KeePassXC CLI support Adds @varlock/keepass-plugin with two modes: direct KDBX file reading via kdbxweb (production) and keepassxc-cli integration (development). Registers @initKeePass decorator, kp()/kpBulk() resolvers, and kdbxPassword data type. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add argon2 support for KDBX 4.0, plugin README, root README update - Register argon2 implementation in kdbxweb CryptoEngine for KDBX 4.0 key derivation (kdbxweb does not bundle one) - Add argon2 as external dependency (native addon, not bundleable) - Add createRequire banner in tsup for kdbxweb's require("crypto") - Add comprehensive plugin README with usage examples - Update root README plugin count and table Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: sanitize kpBulk keys into valid env var names KeePass entry paths like "DB/itest" contain characters invalid in env var names. Sanitize by replacing non-alphanumeric chars with underscores and uppercasing. Non-default attributes (e.g. UserName) are appended as a suffix to avoid collisions between bulk loads of different attributes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fixed spawnAsync to take an input option that gets streamed into the process stdin. Necessary for keepassxc-cli to work properly. --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

- Replace native argon2 addon with hash-wasm (pure WASM, SEA-compatible) - Rename useDesktopApp to useCli, now resolved at runtime (supports forEnv) - Remove unnecessary CLI batching - Add #attribute syntax for reading entry fields (kp("entry#UserName")) - Add entry name inference from key (kp(), kp("#Attr")) - Add customAttributesObj=true for bulk custom field loading - Remove attribute param from kpBulk (always reads Password) - Build as CJS matching other plugins, single self-contained bundle - Add pluginTest() helper (varlock/test-helpers) for plugin integration tests - Add comprehensive tests with programmatically generated KDBX databases - Add stdin input support to spawnAsync in @env-spec/utils - Add website docs page, sidebar entry, overview listing, README update - Add changeset Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

cloudflare-workers-and-pages · 2026-03-31T06:35:19Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	varlock-website	`560535d`	Commit Preview URL Branch Preview URL	Mar 31 2026, 07:13 AM

- Replace module-level CLI auth singletons with per-instance KpCliReader class, fixing a bug where multiple useCli=true instances would overwrite each other - Introduce KpReader interface to eliminate repeated if/else branching in every method of KeePassPluginInstance - Extract getPluginInstance() helper to deduplicate instance lookup logic - Move readAllEntries into KeePassPluginInstance (works for both modes) - Remove redundant "not configured" guards (decorator lifecycle guarantees order) - Fix copy-paste test bug: kp(attribute=X) test was retesting hash syntax - Add shared STANDARD_ENTRIES fixture to reduce test boilerplate - Remove dead main/types fields from package.json - Add Fedora install instruction to docs site Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pkg-pr-new · 2026-03-31T07:26:08Z

Open in StackBlitz

varlock

npm i https://pkg.pr.new/varlock@413

@varlock/astro-integration

npm i https://pkg.pr.new/@varlock/astro-integration@413

@varlock/cloudflare-integration

npm i https://pkg.pr.new/@varlock/cloudflare-integration@413

@varlock/expo-integration

npm i https://pkg.pr.new/@varlock/expo-integration@413

@varlock/nextjs-integration

npm i https://pkg.pr.new/@varlock/nextjs-integration@413

@varlock/vite-integration

npm i https://pkg.pr.new/@varlock/vite-integration@413

@varlock/1password-plugin

npm i https://pkg.pr.new/@varlock/1password-plugin@413

@varlock/aws-secrets-plugin

npm i https://pkg.pr.new/@varlock/aws-secrets-plugin@413

@varlock/azure-key-vault-plugin

npm i https://pkg.pr.new/@varlock/azure-key-vault-plugin@413

@varlock/bitwarden-plugin

npm i https://pkg.pr.new/@varlock/bitwarden-plugin@413

@varlock/google-secret-manager-plugin

npm i https://pkg.pr.new/@varlock/google-secret-manager-plugin@413

@varlock/hashicorp-vault-plugin

npm i https://pkg.pr.new/@varlock/hashicorp-vault-plugin@413

@varlock/infisical-plugin

npm i https://pkg.pr.new/@varlock/infisical-plugin@413

@varlock/keepass-plugin

npm i https://pkg.pr.new/@varlock/keepass-plugin@413

@varlock/pass-plugin

npm i https://pkg.pr.new/@varlock/pass-plugin@413

@varlock/proton-pass-plugin

npm i https://pkg.pr.new/@varlock/proton-pass-plugin@413

commit: 5a8370c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions bot added the community label Mar 15, 2026

theoephraim reviewed Mar 16, 2026

View reviewed changes

theoephraim added the plugin:keepass label Mar 18, 2026

qades and others added 2 commits March 30, 2026 23:29

theoephraim mentioned this pull request Mar 31, 2026

feat: add KeePass plugin for KDBX 4.0 database support #517

Closed

6 tasks

theoephraim force-pushed the main branch from 71bc0f5 to 6ab4fc9 Compare March 31, 2026 06:35

github-actions bot added core:website core:varlock core:utils labels Mar 31, 2026

Remove hash-wasm from root deps, change keepass changeset to patch

5a8370c

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

theoephraim approved these changes Mar 31, 2026

View reviewed changes

theoephraim merged commit 7b04b21 into dmno-dev:main Mar 31, 2026
15 checks passed

varlock-bot mentioned this pull request Mar 31, 2026

[Changesets] Versioned release #506

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add KeePass plugin for KDBX 4.0 database support#413

feat: add KeePass plugin for KDBX 4.0 database support#413
theoephraim merged 4 commits intodmno-dev:mainfrom
qades:main

qades commented Mar 15, 2026 •

edited by theoephraim

Loading

Uh oh!

changeset-bot bot commented Mar 15, 2026 •

edited

Loading

Uh oh!

socket-security bot commented Mar 15, 2026 •

edited

Loading

Uh oh!

qades commented Mar 15, 2026

Uh oh!

theoephraim left a comment

Uh oh!

Uh oh!

theoephraim Mar 16, 2026

Uh oh!

Uh oh!

Uh oh!

cloudflare-workers-and-pages bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Mar 31, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

qades commented Mar 15, 2026 • edited by theoephraim Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Plugin features

Changes from original PR

Testing & docs

Test plan

Uh oh!

changeset-bot bot commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

socket-security bot commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qades commented Mar 15, 2026

Uh oh!

theoephraim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

theoephraim Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cloudflare-workers-and-pages bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

pkg-pr-new bot commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

qades commented Mar 15, 2026 •

edited by theoephraim

Loading

changeset-bot bot commented Mar 15, 2026 •

edited

Loading

socket-security bot commented Mar 15, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Mar 31, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 31, 2026 •

edited

Loading