Architecture

Architecture#

This page describes the internal design of tabby-keepass-ssh and the reasoning behind its key implementation choices.

Authentication hook#

The plugin integrates with Tabby’s SSH stack by observing the keyboard-interactive authentication flow exposed by tabby-ssh. When a connection prompts for a password or a TOTP code, the plugin intercepts the prompt, looks up a matching KeePass entry, and submits the appropriate value automatically — without requiring the user to interact with the prompt.

Entry matching#

Entries are matched by comparing the SSH profile’s host and port against each entry’s URL field, which is expected to follow the ssh://hostname or ssh://hostname:port convention. When several entries resolve to the same URL, the plugin does not guess: it defers to Tabby’s built-in selector UI so the user can pick the correct entry for that connection.

Secure handling of the master password#

The KeePass master password is treated as sensitive material throughout its lifecycle:

  • It is stored in the OS-native secret store — macOS Keychain, libsecret on Linux, or Windows Credential Manager — never written to disk in plaintext.

  • It is only held in memory for the duration of a single database-open operation, then discarded.

  • Field values inside the decrypted database are wrapped in kdbxweb’s ProtectedValue type. ProtectedValue.getText() is called immediately before a value (password or TOTP secret) is used, and the plain string is not cached or retained afterwards.

Database format support#

The plugin reads both KDBX3 and KDBX4 database files. KDBX4 databases that use Argon2 as their key derivation function are supported through the hash-wasm library, which provides a WebAssembly implementation of Argon2 suitable for use inside Tabby’s Node.js/Electron runtime.

TOTP generation#

TOTP codes are generated locally from the secret stored in the entry. The plugin recognizes three possible field names for the secret (otp, TimeOtp-Secret-Base32, TOTP Seed) to stay compatible with KeePassXC, KeePass’s built-in TOTP support (2.47+), and the legacy KeePass TOTP plugin. See Usage for the exact field formats.

Live reload of the database file#

The plugin watches the configured .kdbx file with Node’s fs.watch. When the file changes on disk — for example after adding a new SSH entry in KeePass — the plugin’s in-memory cache is invalidated automatically, so the next connection attempt reads the updated database instead of a stale cached copy.