KeyPlus technical overview

KeyPlus 0.3 separates presentation from vault operations. The CLI and PySide6 GUI are adapters over one application service; neither interface implements encryption or edits vault files directly.

Interactive CLI                 PySide6 GUI
       \                           /
                VaultService
        models, validation, errors
          /                    \
 VaultSession              FileVaultRepository
 key derivation            paths, locking, migration
 AES-GCM                    atomic files and backups

Package responsibilities

Package	Responsibility
`keyplus.application`	Vault models, input validation, interface-neutral errors, and `VaultService` operations.
`keyplus.security`	Argon2id key derivation, AES-GCM operations, and unlocked session state.
`keyplus.storage`	Platform paths, envelope serialization, atomic repository operations, locks, backups, and read-only 0.2 migration.
`keyplus.cli`	REPL parsing, prompts, rendering, and translation of core errors.
`keyplus.ui.gui`	PySide6 screens and dialogs using the shared service.
`keyplus.bootstrap`	Composition root that creates the repository, session, and service.

VaultService currently supports initialization, unlock and lock, entry listing and CRUD, master-password replacement, encrypted backup creation and restoration, and legacy migration. Both interfaces expose password replacement: the CLI through passwd and the GUI through the dashboard.

Internal vault format

The outer JSON envelope identifies keyplus-vault format version 1, the Argon2id profile and salt, the AES-256-GCM profile and nonce, and Base64-encoded ciphertext. The encrypted JSON document has its own payload version and stores creation/update timestamps plus UUID-based entry records.

The format metadata enables explicit rejection of unsupported versions and future migration work. It is an internal, evolving 0.3 format—not a stable interchange specification or supported public API. Applications should not modify it directly.

Persistence transactions

Repository writes acquire a platform advisory file lock, compare the current vault digest with the caller’s expected revision, preserve a valid previous envelope, and write to a temporary file in the destination directory. After flush and fsync, KeyPlus parses the temporary envelope and replaces the active file with os.replace. POSIX builds also synchronize the containing directory.

The revision check prevents an unlocked stale process from silently replacing a newer vault. Advisory locks depend on cooperating processes and do not make direct external file edits safe.

Session model

One VaultSession owns the unlocked derived key and decrypted document within a process. Core operations require that session and refresh its monotonic idle timer. The default timeout is 300 seconds. CLI and GUI launches in separate processes each have their own session, while repository locking and revision checks coordinate persistent writes.

Errors and tests

The core raises interface-neutral errors for uninitialized, locked, corrupt, unsupported, busy, unreadable, or unwritable vaults; unlock, backup, restore, and migration failures; invalid input; and missing or ambiguous entries. The interfaces decide how to display those errors.

The automated suite covers create/open and CRUD round trips, wrong passwords, authenticated tampering, unsupported versions, session expiry, password changes, POSIX modes, stale writers, failed replacement, backup restoration, restore failure preservation, backup collisions and inventory, damaged last-good replacement, legacy migration, deterministic paths, CLI routing, and GUI logout integration.

KeyPlus does not expose a supported public Python API. These internals are documented for contributors and implementation review, not as compatibility promises for external consumers.