Rename to kpxc, add generic wrapper and integration tests

Project renamed kpcache -> kpxc. The kpxc command is a thin wrapper
around any keepassxc-cli subcommand using the cached master password
(ls, search, db-info, attachment-export, ...). kpget stays as the
short hot-path for `show -a Password` in script configs.

Breaking changes from v0.1.0:
- Env vars renamed KPCACHE_* -> KP_* (KP_DB, KP_KEYFILE, KP_TTL,
  KP_CACHE, KP_CONFIG). Avoids collision with keepassxc-cli's own
  KPXC_CONFIG / KPXC_CONFIG_LOCAL env vars.
- Cache file moved /dev/shm/<uid>-kpcache -> /dev/shm/<uid>-kpxc
- Config dir moved ~/.config/kpcache/ -> ~/.config/kpxc/

New:
- bin/kpxc generic wrapper (subcommands streamed to keepassxc-cli with
  cached password injected, denylist for no-DB subcommands)
- tests/test.sh integration suite (15 tests, builds ephemeral DB with
  low KDF rounds, exercises kpget/kpxc/kplock end-to-end)
- CI runs both shellcheck and the test suite
- README adds disclaimer that this is an unofficial third-party wrapper
  not affiliated with the KeePassXC project

Author: magnattic

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ludeeus/action-shellcheck@master
+        with:
+          scandir: ./bin
+          severity: warning
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install keepassxc-cli
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y keepassxc
+      - name: Run integration tests
+        run: bash tests/test.sh

.github/workflows/shellcheck.yml

@@ -1,29 +1,32 @@
-# kpcache
+# kpxc
 
-Tiny shell wrapper that caches your **KeePassXC master password in tmpfs**
-so that `keepassxc-cli` lookups don't prompt for it on every call.
+Cached wrapper around `keepassxc-cli`: unlock once per session, then run any
+KeePassXC subcommand without reprompting for the master password.
 
 For headless / WSL / server setups where you want to use KeePassXC entries
-from CLI tools (himalaya, mbsync, mutt, isync, restic, …) without typing
-the master password each time and without running a long-lived daemon.
+from CLI tools (himalaya, mbsync, mutt, isync, restic) without typing the
+master password each time and without running a long-lived daemon.
+
+> Unofficial third-party wrapper. Not affiliated with the KeePassXC project.
 
 ## Quickstart
 
 ```sh
-git clone https://github.com/magnattic/kpcache ~/.local/share/kpcache
-ln -s ~/.local/share/kpcache/bin/kp{unlock,get,lock} ~/.local/bin/
+git clone https://github.com/magnattic/kpxc ~/.local/share/kpxc
+ln -s ~/.local/share/kpxc/bin/kp{unlock,get,lock,xc} ~/.local/bin/
 
 export KP_DB=~/Passwords.kdbx
 kpunlock                       # type master password once
-kpget "Email/personal"         # → password, no prompt
+kpget "Email/personal"         # password, no prompt
 kpget "Email/personal" -a User # any keepassxc-cli show option
+kpxc ls /Email                 # any keepassxc-cli subcommand
 kplock                         # clear the cache
 ```
 
 ## Why
 
-`keepassxc-cli` is fast - it's the official C++ binary that uses native
-Argon2/AES (via Botan) - but it prompts for the master password on every
+`keepassxc-cli` is fast (it's the official C++ binary using native
+Argon2/AES via Botan), but it prompts for the master password on every
 invocation. That's unworkable when an MTA polls IMAP every 60 seconds or
 when scripts make many lookups.
 
@@ -36,12 +39,12 @@ Existing solutions don't fit headless setups well:
   unlocked, with the browser-extension protocol. Doesn't work headless.
 - **keepasxcli-wrapper** - unmaintained since 2021.
 
-`kpcache` is ~80 lines of bash that:
+`kpxc` is ~120 lines of bash that:
 
-1. Prompts for the master password once.
-2. Stores it in `/dev/shm/<uid>-kpcache` with mode `0600`.
-3. Each subsequent `kpget` reads from the cache and shells out to
-   `keepassxc-cli show` - fast because it's the official binary.
+1. Prompts for the master password once (`kpunlock`).
+2. Stores it in `/dev/shm/<uid>-kpxc` with mode `0600`.
+3. Each subsequent `kpget` / `kpxc` reads from the cache and shells out
+   to `keepassxc-cli`. Fast because it's the official binary.
 
 The master password lives in RAM only (tmpfs is in-memory). It's gone
 after reboot or `kplock`.
@@ -53,7 +56,7 @@ after reboot or `kplock`.
 You need `keepassxc-cli` in `$PATH`.
 
 ```sh
-# Debian/Ubuntu (newer releases also have keepassxc-minimal - no GUI deps)
+# Debian/Ubuntu (newer releases also have keepassxc-minimal, no GUI deps)
 sudo apt install keepassxc
 
 # Arch
@@ -62,52 +65,67 @@ sudo pacman -S keepassxc
 # Fedora
 sudo dnf install keepassxc
 
-# macOS - brew installs CLI inside the .app bundle, symlink it into PATH:
+# macOS: brew installs the CLI inside the .app bundle, symlink it into PATH:
 brew install --cask keepassxc
 sudo ln -s /Applications/KeePassXC.app/Contents/MacOS/keepassxc-cli \
            /usr/local/bin/keepassxc-cli
 ```
 
-### kpcache itself
+### kpxc itself
 
 ```sh
-git clone https://github.com/magnattic/kpcache ~/.local/share/kpcache
-ln -s ~/.local/share/kpcache/bin/kp{unlock,get,lock} ~/.local/bin/
+git clone https://github.com/magnattic/kpxc ~/.local/share/kpxc
+ln -s ~/.local/share/kpxc/bin/kp{unlock,get,lock,xc} ~/.local/bin/
 ```
 
 Make sure `~/.local/bin` is in your `$PATH`.
 
 ## Configure
 
 Set the database path either as an env var or in
-`~/.config/kpcache/config`:
+`~/.config/kpxc/config`:
 
 ```sh
-mkdir -p ~/.config/kpcache
-cat > ~/.config/kpcache/config <<'EOF'
-KPCACHE_DB="/path/to/your.kdbx"
-# KPCACHE_KEYFILE="/path/to/keyfile"   # if your DB uses one
-# KPCACHE_TTL=28800                    # optional: expire cache after 8h
+mkdir -p ~/.config/kpxc
+cat > ~/.config/kpxc/config <<'EOF'
+KPXC_DB="/path/to/your.kdbx"
+# KPXC_KEYFILE="/path/to/keyfile"   # if your DB uses one
+# KPXC_TTL=28800                    # optional: expire cache after 8h
 EOF
 ```
 
 ## Use
 
+Two commands cover almost everything:
+
 ```sh
 kpunlock                              # prompts for master password, caches it
-kpget "Email/personal"                # prints the password
+kpget "Email/personal"                # prints the password (hot path for scripts)
 kpget "Email/personal" -a Username    # prints the username
 kpget "Servers/prod" -a URL           # any keepassxc-cli show -a value
 kpget "Email/personal" -s             # show all attributes
 kplock                                # clears the cache (manual lock)
 ```
 
+For everything beyond `show`, use the generic wrapper:
+
+```sh
+kpxc ls /Email                        # list entries in a group
+kpxc search github                    # full-text search
+kpxc db-info                          # database metadata
+kpxc show -a Password Servers/prod    # equivalent to kpget Servers/prod
+```
+
+`kpxc` forwards any `keepassxc-cli` subcommand and injects the cached
+password automatically. `kpget` is just a shortcut for the most common
+case (printing one attribute) and stays terse in config files.
+
 ## Integrate with other tools
 
 ### himalaya (CLI mail client)
 
 ```toml
-# ~/.config/himalaya/config.toml - tested with himalaya v1.2+
+# ~/.config/himalaya/config.toml, tested with himalaya v1.2+
 backend.auth.cmd = "kpget Email/personal"
 ```
 
@@ -137,28 +155,28 @@ See [`examples/`](examples/) for full configs.
 
 ## Security model
 
-**What kpcache protects against:**
+**What kpxc protects against:**
 
 - The master password is never passed as a command-line argument, so it
   doesn't appear in `ps aux` or shell history.
 - The cache file is created atomically with `install -m 600 /dev/null`,
   so there's no readable window even before `chmod`.
 - `set -euo pipefail` plus an `ERR/INT/TERM` trap ensure the cache is
   removed if `kpunlock` is interrupted mid-write.
-- Entry paths are passed to `keepassxc-cli` after `--`, so an entry name
-  starting with `-` cannot be misinterpreted as an option.
+- Entry paths are passed to `keepassxc-cli show` after `--`, so an entry
+  name starting with `-` cannot be misinterpreted as an option.
 
-**What kpcache does *not* protect against:**
+**What kpxc does *not* protect against:**
 
 - **Root.** A root user can read any process memory or any file on the
   system. Not a goal here.
 - **Memory forensics.** The decrypted master password sits in tmpfs RAM.
   An attacker with kernel access (or a coredump) can read it.
 - **A compromised user account.** Any other process running as your user
-  can read `/dev/shm/<uid>-kpcache`. The model assumes your local user
-  is trusted.
+  can read `/dev/shm/<uid>-kpxc`. The model assumes your local user is
+  trusted.
 - **Hardware tokens (YubiKey challenge-response).** Not currently
-  supported. Patches welcome.
+  supported. PRs welcome.
 
 If your threat model requires per-process secret isolation, hardware
 tokens, or memory hardening, use a kernel-keyring solution or the
@@ -175,14 +193,14 @@ still get fast lookups.
 
 ## Alternatives
 
-- [kpsh](https://git.goral.net.pl/keepass-shell.git) - daemon, pure-Python
+- [kpsh](https://git.goral.net.pl/keepass-shell.git): daemon, pure-Python
   pykeepass. Good if your DB uses moderate KDF rounds.
-- [git-credential-keepassxc](https://github.com/Frederick888/git-credential-keepassxc)
-  - talks to a running KeePassXC GUI via the browser-extension protocol.
+- [git-credential-keepassxc](https://github.com/Frederick888/git-credential-keepassxc):
+  talks to a running KeePassXC GUI via the browser-extension protocol.
   Best if you have a GUI session anyway.
-- [pass](https://www.passwordstore.org/) - drop KeePass, use GPG-encrypted
+- [pass](https://www.passwordstore.org/): drop KeePass, use GPG-encrypted
   files with `gpg-agent` for caching. Larger migration.
 
 ## License
 
-MIT - see [LICENSE](LICENSE).
+MIT, see [LICENSE](LICENSE).

README.md

@@ -9,19 +9,19 @@
 
 set -euo pipefail
 
-CACHE="${KPCACHE_FILE:-/dev/shm/$(id -u)-kpcache}"
-CONFIG="${KPCACHE_CONFIG:-$HOME/.config/kpcache/config}"
+CACHE="${KP_CACHE:-/dev/shm/$(id -u)-kpxc}"
+CONFIG="${KP_CONFIG:-$HOME/.config/kpxc/config}"
 
 if [[ -f "$CONFIG" ]]; then
   # shellcheck source=/dev/null
   source "$CONFIG"
 fi
 
-DB="${KP_DB:-${KPCACHE_DB:-}}"
-KEYFILE="${KP_KEYFILE:-${KPCACHE_KEYFILE:-}}"
+DB="${KP_DB:-}"
+KEYFILE="${KP_KEYFILE:-}"
 
 if [[ -z "$DB" ]]; then
-  echo "❌ No database configured (set \$KP_DB or KPCACHE_DB in config)." >&2
+  echo "No database configured (set \$KP_DB env var or KP_DB= in config)." >&2
   exit 1
 fi
 
@@ -31,22 +31,22 @@ if [[ $# -lt 1 ]]; then
 fi
 
 if [[ ! -f "$CACHE" ]]; then
-  echo "❌ No cached master password - run 'kpunlock' first." >&2
+  echo "No cached master password - run 'kpunlock' first." >&2
   exit 1
 fi
 
-# Optional TTL check (portable mtime - GNU stat -c, BSD/macOS stat -f)
-if [[ -n "${KPCACHE_TTL:-}" ]]; then
+# Optional TTL check (portable mtime: GNU stat -c, BSD/macOS stat -f).
+if [[ -n "${KP_TTL:-}" ]]; then
   if mtime=$(stat -c %Y "$CACHE" 2>/dev/null); then :
   elif mtime=$(stat -f %m "$CACHE" 2>/dev/null); then :
   else
-    echo "❌ Could not read cache mtime - run 'kpunlock' again." >&2
+    echo "Could not read cache mtime - run 'kpunlock' again." >&2
     exit 1
   fi
   age=$(( $(date +%s) - mtime ))
-  if (( age > KPCACHE_TTL )); then
+  if (( age > KP_TTL )); then
     rm -f "$CACHE"
-    echo "❌ Cache expired (>${KPCACHE_TTL}s) - run 'kpunlock' again." >&2
+    echo "Cache expired (>${KP_TTL}s) - run 'kpunlock' again." >&2
     exit 1
   fi
 fi
@@ -62,6 +62,6 @@ extra_args=()
 [[ -n "$KEYFILE" ]] && extra_args+=(--key-file "$KEYFILE")
 
 if ! keepassxc-cli show -q "${extra_args[@]}" "$@" "$DB" -- "$ENTRY" < "$CACHE"; then
-  echo "❌ keepassxc-cli failed - cache may be stale, try 'kpunlock'." >&2
+  echo "keepassxc-cli failed - cache may be stale, try 'kpunlock'." >&2
   exit 1
 fi

bin/kpget

@@ -4,17 +4,17 @@
 # Note: shred has no effect on tmpfs (RAM-backed, no physical blocks),
 # so we just unlink - the kernel reclaims the pages.
 
-CONFIG="${KPCACHE_CONFIG:-$HOME/.config/kpcache/config}"
+CONFIG="${KP_CONFIG:-$HOME/.config/kpxc/config}"
 if [[ -f "$CONFIG" ]]; then
   # shellcheck source=/dev/null
   source "$CONFIG"
 fi
 
-CACHE="${KPCACHE_FILE:-/dev/shm/$(id -u)-kpcache}"
+CACHE="${KP_CACHE:-/dev/shm/$(id -u)-kpxc}"
 
 if [[ -f "$CACHE" ]]; then
   rm -f "$CACHE"
-  echo "✓ Cache cleared"
+  echo "Cache cleared"
 else
   echo "(no cache)"
 fi