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.

## UI Review Follow-Ups

These items came from a hands-on emulator and desktop walkthrough.
They should be treated as usability work, not just polish.

### Cross-Platform Workflow Parity

These items are required to keep desktop, Android phone, and Android tablet
feeling like the same application rather than three related UIs.

- Workflow parity:
  define canonical workflows for open, unlock, set up remote sync, use remote
  sync, browse entries, and edit entries.
- Workflow parity:
  ensure desktop, phone, and tablet use the same action names and the same
  primary next steps for those workflows.
- Workflow parity:
  remove or reduce platform-specific workflow exceptions where the same user
  intent currently takes a different route on different form factors.
- Testing:
  add cross-mode behavior tests that assert workflow order and action
  prominence, not just label presence.
- Testing:
  add explicit lifecycle/open-screen tests for reachability of the primary
  action on desktop, phone, and tablet layouts.
- Testing:
  add explicit remote-sync workflow tests that prove setup, settings, use, and
  removal are reachable from the same primary affordance family across modes.
- Android verification:
  validate changed lifecycle/open/sync workflows on the emulator or a device,
  including with the on-screen keyboard visible.
- Android verification:
  treat “present but below the fold or behind an unexpected branch” as a parity
  failure, not as acceptable platform variation.

### Primary Workflow Changes

These should remain in the main user flow rather than being hidden behind a settings gear.

- Local open flow:
  make the start screen primarily about opening a vault, not configuring one.
- Local open flow:
  keep recent vault selection visually obvious and clearly tappable.
- Local open flow:
  once a recent vault is preselected, collapse the full path into a compact summary with a `Change...` affordance.
- Local open flow:
  improve Android field focus and IME behavior so the master-password field reliably takes focus and summons the keyboard.
- Local open flow:
  show an explicit progress state and allow cancel or retry while opening a vault, especially on Android.
- Remote open flow:
  break the remote form into clearer sections such as `Location` and `Authentication`.
- Remote open flow:
  make recent remote connections easier to scan with a friendlier label than raw URL and path.
- Locked screen:
  show clear vault identity and target summary so the user knows what is being unlocked.
- Entries screen:
  tighten the top strip on phone so tabs, breadcrumbs, and group controls do not fight for the same row.
- Entries screen:
  make breadcrumbs compress more aggressively on phone.
- Entries screen:
  improve entry-row hierarchy and selected-state contrast.
- Entries screen:
  provide section-specific empty states for search, recycle bin, API tokens, and empty groups.
- Group navigation:
  make the distinction between root, current group, and child groups more obvious.
- Group navigation:
  separate navigation controls from group-management controls more clearly.
- Entry detail:
  tighten field spacing and reduce unnecessary whitespace.
- Entry detail:
  group password reveal and copy actions more clearly.
- Entry detail:
  make attachments more visible and actionable.
- Entry edit:
  break the editor into clearer subsections such as `Basics`, `Notes`, `Custom Fields`, `History`, and `Attachments`.
- Entry edit:
  make add/remove affordances for custom fields more visually obvious.
- Entry edit:
  make generated-password draft state more explicit before save.
- Recycle bin:
  make it visually distinct from normal entry browsing.
- API tokens:
  give token list, token detail, and policy editing a clearer dedicated management surface.
- API tokens:
  make policy rows easier to scan by separating effect, operation, and resource visually.
- API audit:
  improve empty-state guidance and provide quick filtering by token, decision, and operation.
- Synchronize:
  keep the split-button pattern, but reduce the visual weight of the sync controls and make advanced sync affordances clearer.
- Synchronize:
  avoid layout-shifting success banners and keep noncritical notifications ephemeral.
- Phone layout:
  continue reducing header and control density so content appears sooner.
- Mobile reliability:
  fix Android local-open ANR behavior before deeper mobile polish.
- Autofill UX:
  surface whether a fill candidate was found, ambiguous, blocked, or awaiting approval.

### Settings Gear Candidates

These are important, but they should likely move behind a dedicated settings gear or advanced/settings surface instead of occupying first-run or day-to-day credential screens.

- Vault security:
  move `Cipher` and `KDF` off the main local-open screen and into `Advanced` or `Vault Settings`.
- Vault security:
  frame security settings as vault configuration rather than freeform text fields in the primary workflow.
- Remote preferences:
  move remembered-auth behavior details and retention policy explanations into settings/help rather than the main open flow.
- UI preferences:
  save and expose view preferences such as group-tools collapse state and any future dense/comfortable layout toggle under settings.
- Autofill behavior:
  app and browser allowlists, package rules, and first-fill approval preferences should live under a settings/privacy area.
- Sync defaults:
  source/direction defaults, conflict preferences, and any future background sync behavior should live under settings.
- Notification preferences:
  banner timeout, ephemeral notices, and other noncritical UI feedback tuning should live under settings.
- Accessibility preferences:
  future display-density, contrast, reduced-motion, or keyboard-focus tuning should live under settings.

### Exit Criteria

- The main workflow screens prioritize opening, browsing, copying, editing, and synchronizing credentials.
- Advanced vault/security and behavior preferences are no longer cluttering the primary open and browsing flows.
- Phone and desktop layouts both present a clear information hierarchy.
- The Android open flow is reliable enough to review and use without ANR during ordinary vault-open operations.

## API Token And gRPC Authorization Parallel Segments

These segments define the work for programmatic access control over gRPC.
They are designed to be independently landable wherever file overlap permits.
The feature is not complete until all segment exit criteria and the global exit criteria are satisfied.

### API Segment A: Token Domain Model

Scope:
- Represent API tokens as first-class vault-backed records.
- Mark token entries explicitly as API credentials rather than generic passwords.
- Store token metadata:
  token id,
  hashed secret or verifier,
  display name,
  client name,
  created at,
  expires at,
  disabled state.
- Keep the persisted representation compatible with KDBX entry fields.

Exit criteria:
- A domain type exists for API tokens and round-trips through the persisted vault model.
- Generic entry listing can distinguish API token entries from ordinary secrets.
- Tests cover create, load, save, and parse behavior for API token entries.
- `go test ./...` passes.

### API Segment B: Token Issuance And Rotation

Scope:
- Generate new API tokens for external tools.
- Return the cleartext token only at creation or explicit rotation time.
- Rotate an existing token while preserving its identity and policy linkage.
- Revoke or disable a token without deleting policy history.

Exit criteria:
- Token issuance, rotation, disable, and revoke operations exist in the domain/service layer.
- Cleartext token material is only exposed on creation or rotation paths.
- Tests cover generation, rotation, and disable/revoke semantics.
- `go test ./...` passes.

### API Segment C: Token Expiration

Scope:
- Allow tokens to have optional expiration timestamps.
- Treat expired tokens as unauthenticated.
- Surface expiration in UI and gRPC management views.
- Support non-expiring tokens explicitly.

Exit criteria:
- Expired tokens are rejected by the gRPC authentication path.
- Token expiration can be created, edited, and removed through the service layer.
- Tests cover valid, expired, and non-expiring token behavior.
- `go test ./...` passes.

### API Segment D: Authorization Policy Model

Scope:
- Define an authorization model for token-scoped access.
- Support allow and deny rules over:
  folders/groups,
  specific entries,
  entry fields where needed,
  and operation types.
- Keep specific deny rules higher priority than broad allow rules.
- Model “not yet decided” separately from “denied”.

Exit criteria:
- A policy evaluator exists for token, resource, and operation tuples.
- Explicit deny overrides allow.
- Unspecified access is distinguishable from denied access.
- Tests cover allow, deny, inherited group scope, and exact-entry scope behavior.
- `go test ./...` passes.

### API Segment E: gRPC Authentication And Authorization Enforcement

Scope:
- Replace the current single static bearer-token interceptor with token-backed auth.
- Authenticate callers using issued KeePassGO API tokens.
- Authorize every gRPC method against token policy.
- Apply scope checks to lifecycle, list, read, mutation, copy, and password-generation RPCs.

Exit criteria:
- gRPC requests authenticate through stored API tokens rather than one static shared secret.
- Every RPC enforces token-specific authorization before mutating or revealing vault data.
- Unauthorized requests return the correct authz/authn gRPC status.
- Integration tests cover permitted, denied, expired, and revoked token behavior.
- `go test ./...` passes.

### API Segment F: Approval Queue And Pending Access Requests

Scope:
- When a token requests access to a resource that is neither explicitly allowed nor denied:
  create a pending approval request.
- Include:
  token identity,
  client name,
  requested operation,
  requested group/entry scope,
  requested time,
  and permanence choice.
- Allow the request to be accepted, denied, or canceled by the user.

Exit criteria:
- Unspecified access creates a pending approval instead of silently denying or allowing.
- Pending approvals are queryable from the application layer.
- Canceling the prompt results in the API request failing without granting access.
- Tests cover pending creation, approval, denial, and cancellation.
- `go test ./...` passes.

### API Segment G: Approval UI

Scope:
- Show a user-facing approval screen/dialog when a pending API request needs a decision.
- Provide actions:
  allow once,
  deny once,
  allow permanently,
  deny permanently,
  cancel.
- Make the requested scope and operation clear to the user.
- Ensure the dialog appears only for requests not already decided.

Exit criteria:
- A pending request triggers a visible approval surface in the app.
- The user can allow, deny, or cancel from the UI.
- Permanent decisions become persisted policy rules.
- UI tests cover each approval outcome.
- `go test ./...` passes.

### API Segment H: gRPC Request Blocking And Resume Behavior

Scope:
- Define how an in-flight gRPC call waits for or fails on user approval.
- Hold the request while approval is pending within a bounded timeout.
- Return unauthenticated or permission-denied when denied/canceled/expired.
- Resume the original call automatically when approval is granted.

Exit criteria:
- Pending requests block safely without leaking goroutines.
- Allowed requests resume and complete without the client reissuing the call where practical.
- Denied and canceled requests return a consistent gRPC status code and message.
- Tests cover timeout, allow, deny, and cancel paths.
- `go test ./...` passes.

### API Segment I: Token Management UI

Scope:
- Add UI for listing API tokens.
- Create token flow with one-time secret display.
- Edit token display metadata and expiration.
- Disable, revoke, and rotate tokens.
- Show effective policy summary per token.

Exit criteria:
- Users can manage API tokens from the app UI end to end.
- One-time token display is explicit and not re-shown later.
- Expiration and disable state are visible.
- UI tests cover create, rotate, disable, revoke, and edit flows.
- `go test ./...` passes.

### API Segment J: Policy Management UI

Scope:
- Let users define folder, entry, and operation scopes for each token.
- Show explicit allow and deny rules.
- Show inherited implications of a folder-level rule.
- Let users review prior permanent decisions created from approval prompts.

Exit criteria:
- Users can inspect and edit token policy from the UI.
- Folder-level and entry-level rules are distinguishable and editable.
- Permanent prompt decisions are visible as policy.
- UI tests cover rule creation, update, and deletion.
- `go test ./...` passes.

### API Segment K: Audit And Event History

Scope:
- Record token issuance, rotation, revoke, approval, deny, and prompt outcomes.
- Record authorization failures and expirations without logging secret material.
- Provide a bounded event history visible in the UI and/or gRPC admin surface.

Exit criteria:
- Security-relevant API token events are captured without secret leakage.
- Approval outcomes and policy changes are auditable.
- Tests cover audit generation for the main token lifecycle and approval actions.
- `go test ./...` passes.

### 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 21: Accessibility Fill Generalization

Scope:
- Extend Android accessibility-based fill beyond the current Chrome demo path.
- Support package-specific rules so apps with stable package identities can have tailored matching behavior.
- Support view-id matching so custom login forms can be identified more reliably than by generic hints alone.
- Support app allowlists so only approved apps/packages are eligible for accessibility-based credential fill.
- Require an approval step before filling into a newly seen app/package unless the user has already made a persistent decision.

Exit criteria:
- The design for package-specific rules, view-id matching, app allowlists, and first-fill approval is implemented or broken into executable sub-slices.
- Accessibility fill no longer depends solely on Chrome-style generic username/password heuristics.
- New app/package fill attempts can be allowed, denied, or made persistent by the user.
- `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

None currently identified.

The last explicitly tracked gaps are now closed:
- KDBX security settings are product-configurable at the major cipher/KDF family level for both new vault creation and existing sessions.
- The current accessibility support boundary is documented in `docs/accessibility.md`, while in-repo focus and labeling behavior remains tested.