KeePass 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

See docs/reference-format.md.

Config and Maps

Resolution order:

1. CLI flags.
2. LOCALSETUP_SECRETS_* environment variables.
3. Repo-local .localsetup/secrets/config.yaml and map.
4. Legacy secrets/keepass-config.yaml plus secrets/*-secrets-map.yaml.
5. 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.

Documentation

• Architecture
• Command reference
• Config resolution
• Global vs repo-local scope
• Vault backends
• KeePassXC installation and versioning
• Portable vault files
• Migration from v1
• Security threat model
• Agent usage patterns
• Troubleshooting
• Update procedure
• Source ledger
• Version ledger