KeePass for SuperCmd and Raycast

A read-only KeePass .kdbx viewer extension for SuperCmd and Raycast. The goal is to provide KeePassXC-like launcher access without requiring KeePassXC, keepassxc-cli, Homebrew packages, native helper apps, or external command-line tools.

Status

This project is in verification. It has a working Raycast-compatible command and automated tests, but KDBX compatibility and runtime support are not release-final yet.

• KDBX parsing currently uses a provisional kdbxweb plus hash-wasm stack.
• Password-only and password plus key-file unlocks are covered by generated KDBX4 tests.
• Practical external KDBX3/KDBX4 fixture coverage is still needed.
• Raycast and SuperCmd runtime behavior must still be fully verified before claiming feature parity.
• Favicon display is intentionally disabled until network and runtime behavior is verified.

Features

• Unlock supported KeePass .kdbx databases locally.
• Support database password and optional key-file unlock.
• Search entries by title, username, URL, notes, folder, and tags.
• Filter all entries or favorites marked with the KeePass favorite tag.
• Copy and paste username, password, URL, notes, and generated TOTP codes.
• Open HTTP and HTTPS URLs through explicit user action.
• Lock manually or after the configured inactivity timer.
• Remember the database path and password after a successful unlock for startup auto-unlock.

Security Notes

• KDBX access is read-only. The extension does not create, edit, delete, save, merge, or rewrite database files.
• Decrypted entries are kept in memory only for the active unlocked session and are cleared on lock.
• Database passwords and database paths are remembered by current implementation through Raycast LocalStorage plus a file-backed fallback under the extension support directory. Treat remembered values as sensitive plaintext available to the same user account.
• Manual lock and inactivity lock clear decrypted database state, but they do not clear remembered unlock values.
• Use Forget Remembered Unlock Values in the unlock form to remove the remembered database path and password.
• Key-file bytes and key-file paths are not intentionally persisted.
• Decrypted data, TOTP seeds, and entry URLs are not sent to network services. Favicon fetching remains disabled.

Usage

1. Run the Search command.
2. Choose a KeePass .kdbx database in the unlock form.
3. Enter the database password.
4. Choose a key file if the database requires one.
5. Search entries and use actions to copy, paste, open URLs, generate TOTP codes, or lock the database.

Development

Install dependencies:

npm install

Run the extension during development:

npm run dev

Run checks:

npm run test
npm run typecheck
npm run build
npm run lint
npm audit --omit=dev

Project Structure

• src/search.tsx: command entry point, unlock form, search list, actions, remembered unlock handling.
• src/utils/kdbx-loader.ts: read-only KDBX loading boundary.
• src/utils/entry-mapper.ts: maps parser entries into the extension entry model.
• src/utils/totp.ts: local TOTP parsing and generation.
• src/utils/placeholder-processor.ts: conservative KeePass field placeholder replacement.
• src/utils/inactivity-timer.ts: inactivity lock parsing and timing.
• test/: automated tests for loader, entry mapping behavior, TOTP, placeholders, and inactivity locking.
• docs/: product requirements, architecture, dependency spike notes, compatibility status, and security notes.

Current Limitations

• KDBX support is best-effort until more real-world fixtures are tested.
• The parser stack is still treated as a verification spike, not final production adoption.
• KDBX3, KDBX4 AES-KDF, unsupported KDF, corrupt file, and practical external database fixture coverage is incomplete.
• Raycast GUI runtime verification is still incomplete.
• Clipboard auto-clearing is not implemented.
• Folder filtering was removed by request; search still includes folder text where available.

See docs/compatibility-verification.md and docs/security.md for the latest verification and security status.