keepassgo/TODO.md

TODO

Parallel Work Segments

These segments are intended to be independently executable wherever possible. Each segment has its own local exit criteria. The product is not complete until the global exit criteria at the end of this file are also met.

Segment 1: Application State Ownership

Scope:

• Keep the controller as the single source of truth for: session state, selected entry, selected template, current path, current section, search query, dirty state, status messaging, and error state.
• Remove remaining direct UI-owned mutation of product state.
• Keep list, detail, breadcrumb, section, and selection behavior controller-driven.

Exit criteria:

• No core workflow depends on UI-local state as the authoritative source of vault data.
• UI list and detail rendering derive from controller or session state only.
• Controller behavior tests cover section switching, selection, search, and dirty-state transitions.
• go test ./... passes.

Segment 2: Local Vault Lifecycle UI

Scope:

• Create new vault flow.
• Open local vault flow.
• Save current vault flow.
• Save-as local vault flow.
• Lock flow.
• Unlock flow.
• Visible error handling for invalid master key, unreadable file, decode failure, and missing path.

Exit criteria:

• A user can create, open, save, save-as, lock, and unlock a local vault through the UI.
• UI tests or controller-integrated tests cover each lifecycle path.
• Lifecycle actions update visible status and error messages consistently.
• go test ./... passes.

Segment 3: Remote WebDAV Lifecycle UI

Scope:

• Open remote WebDAV vault flow.
• Save remote WebDAV vault flow.
• Visible handling for remote error states.
• Visible handling for conflict responses and retry-safe behavior.

Exit criteria:

• A user can open and save a remote WebDAV-backed vault through the UI.
• Conflict and transport failures surface a visible error state.
• WebDAV lifecycle tests cover open, save, and conflict behavior.
• go test ./... passes.

Segment 4: Master Key Setup And Change Flows

Scope:

• Password-only setup and unlock.
• Key-file-only setup and unlock.
• Composite password-plus-key-file setup and unlock.
• UI for selecting master-key mode when creating a vault.
• UI for changing master-key mode on an existing vault where supported.

Exit criteria:

• All three master-key modes work through the product UI, not only storage helpers.
• Tests cover each mode for create, open, and unlock behavior.
• Validation and visible error states exist for missing or invalid key material.
• go test ./... passes.

Segment 5: KDBX Security Settings Preservation

Scope:

• Preserve supported cipher and KDF settings when reopening and saving.
• Surface relevant settings in product-facing docs or UI where appropriate.
• Document unsupported settings explicitly.

Exit criteria:

• Reopen-and-save cycles preserve supported KDBX security settings.
• Compatibility notes are current in docs/kdbx-compatibility.md.
• Tests cover settings preservation across save cycles.
• go test ./... passes.

Segment 6: Entry CRUD UI

Scope:

• Create entry.
• Edit entry.
• Duplicate entry.
• Delete entry to recycle bin.
• Restore entry from recycle bin.
• Move entry between groups if needed for editing flow.

Exit criteria:

• All core entry CRUD actions are available from the UI.
• Entry editor supports title, username, password, URL, notes, tags, and custom string fields.
• Deletion routes entries to recycle behavior rather than permanent loss.
• Tests cover create, edit, duplicate, delete, and restore flows.
• go test ./... passes.

Segment 7: Entry History UI

Scope:

• Browse history for the selected entry.
• Select a historical version.
• Restore a historical version into the current entry.

Exit criteria:

• Entry history is visible and restorable from the UI.
• History restore creates the expected new current state.
• Tests cover history listing and restore behavior.
• go test ./... passes.

Segment 8: Group And Path Management UI

Scope:

• Create group.
• Rename group.
• Delete group.
• Breadcrumb-driven path navigation.
• Explicit navigation for templates and recycle bin.
• Move entries between groups.

Exit criteria:

• Nested group management works from the UI.
• Breadcrumb navigation and group listing are controller-driven.
• Templates and recycle-bin locations are explicit and navigable.
• Tests cover create, rename, delete, navigate, and move behavior.
• go test ./... passes.

Segment 9: Search Completion

Scope:

• Current-group listing.
• Global search.
• Visible path context in results.
• Explicit behavior for templates search.
• Explicit behavior for recycle-bin search.
• Clear and reset behavior.

Exit criteria:

• Search behavior is consistent across desktop and phone layouts.
• Search results always retain visible path context.
• Template and recycle-bin search behavior is defined and tested.
• Tests cover clear/reset transitions.
• go test ./... passes.

Segment 10: Template CRUD UI

Scope:

• Create template.
• Edit template.
• Delete template.
• Browse template list.
• Instantiate a template with overrides.

Exit criteria:

• Templates are manageable from the UI.
• Template instantiation can create a real entry with overrides.
• Tests cover template CRUD and instantiation behavior.
• go test ./... passes.

Segment 11: Attachment Workflow UI

Scope:

• Add attachment.
• List attachments.
• Export attachment.
• Replace attachment.
• Remove attachment.
• Error and size handling.

Exit criteria:

• Attachments are manageable from the UI end to end.
• Attachment workflows are covered by tests.
• Replace and remove behavior preserve expected vault state.
• go test ./... passes.

Segment 12: Password Generation UX

Scope:

• Expose password generation profiles in the UI.
• Allow generated passwords to populate the active entry form.
• Keep generator behavior aligned with gRPC.

Exit criteria:

• Users can generate a password from the UI without leaving the entry workflow.
• Profile selection is visible and tested.
• Generated values flow into entry create and edit forms correctly.
• go test ./... passes.

Segment 13: Copy, Reveal, And Secret Transfer UX

Scope:

• Copy username.
• Copy password.
• Copy URL.
• Reveal or hide password.
• Visible copy feedback.
• Secret-safe error and status behavior.
• Optional timed clipboard clearing if retained.

Exit criteria:

• Copy and reveal flows work in the UI end to end.
• Clipboard feedback is visible and non-secret-bearing.
• If timed clearing exists, it is tested.
• go test ./... passes.

Segment 14: gRPC Lifecycle API

Scope:

• Session status RPC.
• Open local vault RPC.
• Open remote vault RPC.
• Save vault RPC.
• Lock vault RPC.
• Unlock vault RPC.

Exit criteria:

• Trusted clients can manage vault lifecycle through gRPC.
• Authentication and error contracts are consistent across lifecycle methods.
• Lifecycle gRPC integration tests pass.
• go test ./... passes.

Segment 15: gRPC Mutation API

Scope:

• Entry mutation RPCs.
• Group mutation RPCs.
• Template mutation RPCs.
• History restore RPCs.
• Attachment upload, download, list, and delete RPCs.
• Copy-field RPCs.
• Password generation RPC.

Exit criteria:

• Trusted clients can perform all major mutation workflows through gRPC.
• The API does not depend on UI-local state.
• Integration tests cover the mutation surfaces.
• go test ./... passes.

Segment 16: Accessibility And Keyboard-First Behavior

Scope:

• Keyboard navigation for search, list, detail, dialogs, and breadcrumbs.
• Shortcuts for save, lock, new entry, search focus, and field copy actions.
• Visible focus states.
• High-DPI sanity coverage.
• Screen-reader-conscious labels where Gio permits.

Exit criteria:

• Core workflows are operable without a pointing device on desktop.
• Keyboard shortcuts exist for major actions and are tested.
• Focus and accessibility states are visible and intentional.
• go test ./... passes.

Segment 17: UI Completion And Error Surfaces

Scope:

• Empty states.
• Loading states.
• Error states.
• Lock screen.
• Master-key prompts.
• Save conflict surfaces.
• Remove remaining prototype-only affordances.

Exit criteria:

• Core product workflows no longer rely on prototype-style hidden assumptions.
• Lock, error, loading, and empty states are visible and intentional.
• UI tests or controller-integrated tests cover these states.
• go test ./... passes.

Segment 18: Desktop Automation Resolution

Scope:

• Either implement a desktop login automation mechanism comparable in purpose to KeePass auto-type,
• or explicitly finalize the design that secure gRPC supersedes auto-type.
• Keep the decision documented in-repo.

Exit criteria:

• The desktop automation requirement is explicitly resolved in code or docs.
• The chosen approach is documented in docs/desktop-automation.md.
• Any implemented behavior is tested.
• go test ./... passes.

Segment 19: Packaging And Runbook

Scope:

• Keep the app runnable from source.
• Document desktop build and run steps.
• Document Android packaging with gogio.
• Add icon and metadata placeholders if missing.

Exit criteria:

• README.md is accurate for local build, run, and Android packaging guidance.
• Placeholder metadata exists where needed for packaging.
• The app still builds from the repo.
• go test ./... passes.

Segment 20: Regression And Integration Coverage

Scope:

• Add integration coverage for reopen/save cycles.
• Add regression coverage for stable entry IDs.
• Add regression coverage for remote save and reopen.
• Add regression coverage for history, recycle bin, templates, groups, and attachments together.

Exit criteria:

• Cross-feature regressions have dedicated tests.
• Stable identity and persistence guarantees are covered by tests.
• go test ./... passes.

Global Exit Criteria

Do not treat the product as complete until all of the following are true:

• Segment 1 through Segment 20 are all complete.
• KeePassGO can create, open, edit, save, save-as, lock, and unlock local KDBX databases through the UI.
• KeePassGO can open and save remote WebDAV-backed KDBX databases through the UI, including visible conflict and error handling.
• KeePassGO supports master password, key file, and composite key workflows in the product.
• KeePassGO preserves supported KDBX security and KDF settings and documents unsupported settings.
• KeePassGO supports nested groups, path-aware navigation, explicit template navigation, and explicit recycle-bin navigation.
• KeePassGO supports entry create, edit, duplicate, delete, restore, history browse, and history restore through the UI.
• KeePassGO supports title, username, password, URL, notes, tags, and custom string fields through the UI.
• KeePassGO supports attachment add, replace, remove, list, and export through the UI.
• KeePassGO supports reusable templates through the UI and through the gRPC API.
• KeePassGO supports current-group listing, global search, and visible path context consistently across desktop and phone layouts.
• KeePassGO supports copy username, copy password, copy URL, and reveal or hide password behavior end to end.
• KeePassGO exposes password generation profiles through both UI and gRPC.
• The secure gRPC API is broad enough for trusted automation and browser-extension-style integration.
• The desktop automation requirement is explicitly resolved.
• Keyboard-first navigation and common shortcuts exist for major product workflows.
• The UI no longer depends on prototype-only mock behavior for any core workflow.
• Build and run instructions exist for desktop, and packaging guidance exists for Android.
• go test ./... passes.
• go tool golangci-lint run ./... passes.

Remaining Gaps Against AGENTS.md

This section tracks requirements from AGENTS.md that are not fully satisfied by the current landed code, even if the segment work and tests are green.

1. KDBX Security Settings Are Only Preserved, Not Fully Product-Configurable

Evidence:

• docs/kdbx-compatibility.md states that KeePassGO preserves the original opened vault's cipher and KDF selection during save.
• The same document also states:
  • KeePassGO does not yet provide a UI for editing cipher or KDF parameters directly.
  • New vault creation still uses library default KDBX header settings.

Why this is still a gap:

• AGENTS.md requires support for the major KeePass-style encryption and KDF configuration choices represented in KDBX databases.
• Preserving existing settings is good, but it is weaker than allowing the product user to choose those settings for new vaults or change them explicitly for existing vaults.

Remaining work:

• Expose major KDBX cipher/KDF choices in the product UI for vault creation.
• Expose supported security-setting changes for an existing unlocked vault.
• Add behavior tests covering explicit user selection of supported cipher/KDF options.
• Update docs/kdbx-compatibility.md once those product-facing controls exist.

Exit criteria for this gap:

• A user can create a vault with a selected supported cipher/KDF combination through the product.
• A user can change supported cipher/KDF settings for an existing vault through the product, where the underlying library supports it.
• Tests cover those choices end to end.

2. Accessibility Requirement Needs Explicit Screen-Reader Review

Evidence:

• Keyboard-first behavior and focus handling exist in the landed code.
• Accessibility labels exist in ui_accessibility.go.
• The repository does not currently contain a documented review of what screen-reader-conscious behavior Gio can and cannot provide on the supported desktop targets.

Why this is still a gap:

• AGENTS.md explicitly calls for screen-reader-conscious design, not only keyboard shortcuts and focus states.
• The current code suggests intent, but the repo does not yet document a concrete accessibility support boundary or validation result.

Remaining work:

• Audit the current Gio accessibility surface on Linux and Windows for the controls used by KeePassGO.
• Document what is currently exposed, what is intentionally labeled, and what remains limited by the toolkit.
• Add targeted tests for any label/focus mapping that can be verified in-repo.

Exit criteria for this gap:

• The repo includes a documented accessibility review for current desktop targets.
• Screen-reader-conscious behavior is explicitly described rather than implied.
• Any in-repo verifiable accessibility mappings have tests.