fressh/docs/archive/key-management-plan.md

Key Management UX & Tech Plan

Goal: Make SSH private key management clear and consistent: selecting a key, generating/importing keys, renaming, deleting, and setting a default — all with a unified, styled UI and predictable data semantics.

Current State (Summary)

• Security type uses a Picker in the main form; defaults to password.
• Switching to key auth shows a Picker for keys (awkward empty state) and a “Manage Keys” button.
• Keys can be generated, renamed, deleted, set as default inside a modal.
• Storage uses a chunked manifest in expo-secure-store (works for >2KB values) with metadata (priority, createdAtMs, label?, isDefault?).
• All key mutations go through one upsertPrivateKey that invalidates the React Query keys query.

UX Objectives

• Remove the inline key Picker; select a key within the Key Manager modal.
• Replace the security type Picker with a simple toggle/switch.
• Handle the “no keys yet” case gracefully by auto-opening the modal when user chooses key auth.
• Keep visual styling consistent with text inputs (button heights, paddings, colors).
• Prepare the modal for importing private keys (paste text or select file) in a future phase.

Phase 1 — Selection UX + Styling

1. Replace security type Picker with toggle

   • Use a SwitchField (styled like inputs) labeled "Use Private Key".
   • Value mapping: off → password; on → key.
   • When toggled ON and there is no selected key and no keys exist, auto-open Key Manager.

2. Remove inline key Picker

   • Replace with a read-only field styled like inputs: label: "Private Key", value: current key label or "None".
   • The field is a Pressable that opens the Key Manager for selection.
   • Disabled state (no keys): show "None" with hint "Open Key Manager to add a key".

3. Key Manager: add selection mode

   • Add a radio-style control on each row to select the key for this session.
   • Modal accepts an optional selectedKeyId and onSelect(id) callback.
   • When user taps a row (or radio), call onSelect(id) and close the modal.
   • Continue to support generate/rename/delete/set-default; selection should update live.

4. Styling parity

   • Ensure the read-only "Private Key" field height/padding matches TextField.
   • Use consistent typography/colors for labels, values, and hints.

5. Empty states

   • If no keys: show a friendly empty state in modal with primary action "Generate New Key" and secondary "Import Key" (Import lands in Phase 2).

Deliverables (Phase 1)

• Update apps/mobile/src/app/index.tsx form:
  • Toggle for auth type.
  • Read-only key field that opens modal.
• Update KeyManagerModal:
  • Support selection behavior with visual radio and onSelect callback.
  • Keep existing generate/rename/delete/set-default.

Phase 2 — Import Keys

1. Import entry points in modal

   • Add "Import" button/menu in the modal header or as secondary action in empty state.
   • Options:
     • Paste PEM text (multiline input)
     • Pick a file (use expo-document-picker)

2. Validation + Storage

   • Validate PEM or OpenSSH formats; detect supported types (rsa/ecdsa/ed25519/ed448/dsa).
   • Optional passphrase field (store encrypted if supported by library; otherwise prompt each use — confirm feasibility with SSH lib).
   • On success, call the single upsertPrivateKey({ keyId, value, metadata }) and close import flow.

3. UX details

   • Show parse/validation errors inline.
   • Set initial label from filename (file import) or "Imported Key" (paste); allow editing label on success or selection.

Deliverables (Phase 2)

• Modal import screen(s) with paste/file flows.
• PEM validation utility and error handling.

Phase 3 — Data Model + Semantics

1. Default key semantics

   • Guarantee exactly one default key at most by flipping isDefault on upsert when isDefault === true.
   • Consider: separate lightweight persistent "defaultId" in manifest root to avoid iterating all keys on default change.

2. Robustness

   • Add safety around manifest chunk growth: if manifestChunkSize + newEntrySize > sizeLimit, create a new chunk.
   • Ensure createdAtMs is preserved across upserts (done) and add modifiedAtMs if useful.

3. Logging + Dev ergonomics

   • Gate verbose logs behind a debug flag to avoid log spam in production builds.

Phase 4 — Edge Cases & Polish

• Deleting the currently-selected key: clear selection and show hint to pick/create a new key.
• Auto-select the default key when switching to key auth and no key is selected.
• Handle failures from SecureStore (permissions/storage full) with user-friendly messages.
• Handle very large keys with chunking (already supported), surface an error if size exceeds safe thresholds.
• Accessibility: ensure labels/roles for controls in modal and the selection field.

Phase 5 — Testing & QA

• Unit test PEM parsing/validation (Phase 2).
• E2E flows:
  • First run → toggle to key → auto-open modal → generate key → selected → connect.
  • Import key by paste/file; rename; set default; delete.
  • Delete selected key; confirm the form state updates.

Implementation Notes

• Keep a single write path for keys: upsertPrivateKey (invalidates the keys query).
• Prefer modal-based selection with a simple “field-as-button” in the form.
• For future passphrase support, confirm the SSH library’s API shape and storage expectations.