Reconstruct KeePassGO repository

2026-03-29 11:04:38 -07:00
commit a2a8fcbd14
34 changed files with 14041 additions and 0 deletions
@@ -0,0 +1,34 @@
+# Desktop Automation Decision
+
+## Decision
+
+KeePassGO will not implement KeePass-style auto-type as its primary desktop automation mechanism.
+The secure gRPC API is the replacement integration surface for trusted desktop automation, browser extensions, and local helper tools.
+
+## Why
+
+- The gRPC API gives a narrower and more explicit trust boundary than synthetic key injection.
+- Browser and local automation clients can request exactly the credential operation they need:
+  - list entries
+  - list groups
+  - list templates
+  - create and mutate entries
+  - copy fields
+  - manage attachments
+  - generate passwords
+- A typed authenticated API is easier to test and reason about than fake keystroke delivery to arbitrary windows.
+- Synthetic typing is platform-specific, fragile, and substantially harder to make safe across Linux, Windows, and future Android support.
+- The product requirement is integration capability comparable in purpose to KeePass auto-type, not literal keystroke emulation.
+
+## Product Consequences
+
+- Trusted desktop automation should be implemented as clients of the gRPC service.
+- Browser integrations should target the gRPC API rather than ad hoc local protocols.
+- UI workflows may still provide copy-to-clipboard behavior for direct human use.
+- If a future use case demonstrates that gRPC plus clipboard is insufficient, native desktop automation can be reconsidered as a secondary capability, not as the baseline integration model.
+
+## Exit-Criteria Impact
+
+This document is the explicit resolution of the desktop automation requirement from [`AGENTS.md`](../AGENTS.md) and [`TODO.md`](../TODO.md):
+- desktop automation is resolved by design
+- the secure gRPC interface is the superseding trusted integration surface
@@ -0,0 +1,26 @@
+# KDBX Security Compatibility
+
+KeePassGO supports the following KDBX security workflows today:
+
+- open and save password-only vaults
+- open and save key-file-only vaults
+- open and save composite password-plus-key-file vaults
+- preserve the original opened vault's KDBX format version during save
+- preserve the original opened vault's cipher selection during save
+- preserve the original opened vault's KDF selection during save
+
+What "preserve" means:
+
+- if a vault is opened through a managed session and then saved, KeePassGO reuses the opened vault's KDBX header configuration instead of replacing it with default header settings
+- this applies to local and WebDAV-backed vault sessions
+
+Current explicit limitations:
+
+- KeePassGO does not yet provide a UI for editing cipher or KDF parameters directly
+- new vault creation still uses the library default KDBX header settings for freshly created databases
+- unsupported or unknown header fields outside the preserved header structures are not guaranteed to round-trip if they are not represented by the underlying library
+
+Practical expectation:
+
+- existing KeePass/KeePass2Android-compatible vaults keep their major format, cipher, and KDF family when edited and saved through KeePassGO
+- KeePassGO does not yet try to be a full advanced database-settings editor