ls-keepass-secrets
Use when validating logical secret-ID maps, config, and reference syntax for a KeePassXC integration; output is redacted and the fake backend is test-only.
SKILL.mdls/skills/ls-keepass-secrets/SKILL.md
GitHubKeePass secret mappings
Use this skill to validate non-secret logical-ID metadata and reference syntax. It does not resolve, display, create, rotate, update, delete, or otherwise access real KeePassXC entries.
Supported commands
Primary validation commands:
python3 scripts/localsetup_secrets.py map-validate --map examples/map.yaml
python3 scripts/localsetup_secrets.py reference '{{secret:mail.box03.example.admin:password}}'
Capability check:
python3 scripts/verify_keepassxc.py --format json
The CLI emits JSON envelopes by default:
{
"ok": true,
"command": "map-validate",
"data": {},
"warnings": [],
"errors": [],
"sources": [],
"sensitive": false,
"redactions": []
}
Use --format human only for interactive display. Diagnostics are redacted. Protected values require --show-sensitive.
The default keepassxc backend preserves existing configuration and may check the CLI version. When keepassxc-cli is unavailable it reports missing_backend; otherwise it refuses every vault operation with interactive_backend_required. fake exists only for deterministic tests and examples; it is not a secret store.
Logical IDs
Canonical IDs are lowercase and may contain letters, digits, dots, underscores, and hyphens:
mail.box03.example.admin
postgres.box03.app1
api.box03.stripe.live
Aliases, including email-like aliases, may be declared in map files. Ambiguous aliases fail clearly.
References
Supported forms:
Secret ID: mail.box03.example.admin
{{secret:mail.box03.example.admin:password}}
secret://localsetup/repo/default/mail.box03.example.admin#field=password
Config and Maps
Resolution order:
- CLI flags.
- LOCALSETUP_SECRETS_* environment variables.
- Repo-local .localsetup/secrets/config.yaml and map.
- Legacy secrets/keepass-config.yaml plus secrets/*-secrets-map.yaml.
- Global ~/.config/localsetup/secrets/config.yaml and ~/.local/share/localsetup/secrets/maps/default.yaml.
Config and map files may contain metadata, entry paths, usernames, URLs, and aliases. They must not contain passwords, tokens, key material, or passphrases.
Examples live in examples/. Contract schemas live in schemas/.
Backends
- keepassxc: the default capability guard. It checks that keepassxc-cli is present for diagnostics but never opens a vault or runs read/write operations.
- fake: deterministic test and example backend for placeholder data only. It must not be used as a secret store.
- PyKeePass: future optional backend only; not installed or required by this skill.
Safety Rules
- Never put secret values in tracked files.
- Keep .kdbx, keyfiles, and .env files out of Git.
- Treat interactive_backend_required as an explicit refusal, not a request to bypass the vault boundary.
- Use the fake backend only in isolated tests and examples.
- Do not open, create, or inspect real vaults during tests.