dsh-secret-vault

Configuration

The plugin works with no configuration at all. Defaults:

Key	Default	Meaning
vaultDir	'' → $DSH_HOME/vault	Vault directory. DSH_HOME defaults to ~/.dsh (from os.homedir())
dbName	secrets.kdbx	Database file name inside vaultDir (no path separators)
keyName	secrets.key	Key file name inside vaultDir (no path separators)
cliPath	keepassxc-cli	Path or name of the KeePassXC CLI
cliTimeoutMs	30000	Timeout for one CLI call (2 s to 5 min)
useTimeoutMs	180000	Timeout for a vault_use command (2 s to 15 min)
confirmTimeoutMs	180000	How long the authorization dialog may stay unanswered before the use is denied; 0 removes the deadline (5 s to 15 min)
requireConfirmation	true	Interactive human confirmation before using an existing credential
allowReveal	true	Allow vault_reveal at all
binGroup	Recycle Bin	Name of the KeePassXC recycle-bin group (change it for a database created in another language)

To change a value, override the row by id in the profile's ~/.dsh/profiles/web/cordis.patch.yml. A patch replaces the whole config, so restate every key you keep:

- id: tool-secret-vault
  config:
    vaultDir: '/path/to/your/vault'   # or omit it to use $DSH_HOME/vault
    dbName: 'secrets.kdbx'
    keyName: 'secrets.key'
    cliPath: 'keepassxc-cli'
    cliTimeoutMs: 30000
    useTimeoutMs: 180000
    confirmTimeoutMs: 180000
    requireConfirmation: true
    allowReveal: true
    binGroup: 'Recycle Bin'

Vault layout and groups

The vault is an arbitrary KeePassXC group tree. The plugin never creates or assumes group names: whatever groups your database has are the ones vault_list reports, and an entry path is just group/subgroup/title.

Create groups in the KeePassXC GUI before storing below them (the CLI add does not create missing groups). A bare title with no / lands in the root group, so a fresh vault is usable immediately. Titles may repeat across groups: a bare title that matches more than one entry is refused with the candidate paths, and the full path picks one. Everything under the recycle-bin group (binGroup, default Recycle Bin) is hidden from vault_list and from title search.

Database and key file

The plugin expects a key-file-only KeePassXC database. On first use it creates secrets.kdbx plus a 64-byte random secrets.key in vaultDir, both mode 0600 inside a 0700 directory, and opens the database with --no-password --key-file.

To use an existing KeePassXC database, make sure it authenticates with a key file only (Database → Database Settings → Security in the KeePassXC GUI), then point vaultDir/dbName/keyName at the pair. A database that also needs a master password is not supported by the CLI flow of this plugin.

To inspect or edit the vault by hand, open it in the KeePassXC GUI (Database → Open…) and select the key file. Do that while the harness is not writing: keepassxc-cli and the desktop app do not coordinate locks, and saving from the GUI can overwrite a concurrent write.

Back up both files together. They only work as a pair; losing either one means losing the vault, and there is no master password to recover it. Keep the copy outside vaultDir.