fressh/docs/import-private-key-plan.md

# Import Private Key — Detailed Plan

This plan covers implementing private key import (paste or file), improving key
management UX, adding metadata display, and enabling copying the corresponding
public key. It is grounded in the current code found in:

- `apps/mobile/src/app/index.tsx` (connection form + `KeyIdPicker`)
- `apps/mobile/src/components/key-manager-modal.tsx` (list, generate, rename,
  delete, set default)
- `apps/mobile/src/lib/secrets-manager.ts` (chunked secure store, key metadata,
  queries)

Relevant Expo docs (for implementation reference):

- Document Picker: https://docs.expo.dev/versions/latest/sdk/document-picker/
- File System: https://docs.expo.dev/versions/latest/sdk/filesystem/
- Clipboard (for copy public key):
  https://docs.expo.dev/versions/latest/sdk/clipboard/

## Current State (from repo)

- Keys are stored via a chunked manifest around `expo-secure-store` with
  metadata schema:
  `{ priority: number; createdAtMs: int; label?: string; isDefault?: boolean }`.
- `KeyManagerModal` supports: generate key (RSA 4096), rename, delete, set
  default, and selection through `onSelect` (already wired and used by the
  form’s `KeyIdPicker`).
- `generateKeyPair` uses `@dylankenneally/react-native-ssh-sftp`. We currently
  save only `pair.privateKey`, discard public key.
- Selection UI shows label or id; there’s no import flow yet; no createdAt
  display; no copy public key.

## Goals

- Import private keys via two paths:
  - Paste PEM/OpenSSH text into a multiline field.
  - Pick a key file via a system file picker and read its contents.
- Let users name the key before creating/storing it (applies to both Generate
  and Import flows).
- Allow users to copy the corresponding public key for any stored private key.
- Show basic metadata (createdAt) in the key list for context.
- Keep storage compatible and robust (no breaking changes to existing
  manifests).

## UX Plan

1. Entry points in Key Manager

- Add a secondary action “Import Key” next to the existing “Generate” button.
- When no keys exist, show both “Generate New Key” and “Import Key” prominently
  in the empty state.

2. Import flow (single modal sheet with tabs or steps)

- Step A: Choose method: “Paste PEM” or “Pick File”.
  - Paste PEM: multiline `TextInput` for the private key content; live
    validation feedback.
  - Pick File: button to open file picker (DocumentPicker). After selection,
    read file with FileSystem and populate a read-only preview (collapsible) +
    validation feedback.
- Step B: Name & options
  - “Label” text input (required or at least prompted before confirm).
  - Optional: “Set as default key” toggle.
  - Optional: public key association (see Public Key section below).
- Step C: Confirm & Save
  - On success, call `secretsManager.keys.utils.upsertPrivateKey` with computed
    `keyId`, metadata, and value.
  - Close the import sheet and refresh list.

3. Generate flow improvements

- Instead of immediate generate, open a small pre-flight form:
  - Label (text input; default prefilled like “My RSA Key”).
  - Key type (dropdown/segmented, default RSA).
  - Key size for RSA (e.g., 2048/4096; default 4096).
  - Optional comment (passed to generator if supported).
  - On submit, call `generateKeyPair`, then `upsertPrivateKey` with label and
    useful metadata (see Data Model Changes).

4. Key list rows (metadata + actions)

- Under the title, show small muted details: “ID: … • Created: …” (formatted via
  date-fns).
- Add an overflow/action area with:
  - Copy Public Key (uses `expo-clipboard`).
  - Rename (existing).
  - Set Default (existing).
  - Delete (existing).
- If public key is not known, show “Add Public Key” which opens a small paste
  dialog to attach one (stored in metadata).

## File Picker + File Reading (Expo)

Document selection:

- Use `expo-document-picker`:
  - `const res = await DocumentPicker.getDocumentAsync({ type: ['text/*', 'application/x-pem-file', 'application/octet-stream'], copyToCacheDirectory: true });`
  - Handle cancelation: `res.canceled` or check `res.assets?.length` depending
    on SDK version.
  - Use `res.assets[0].uri` and `res.assets[0].name`.

File reading:

- Use `expo-file-system`:
  - `const contents = await FileSystem.readAsStringAsync(uri, { encoding: FileSystem.EncodingType.UTF8 });`
  - If using DocumentPicker with `copyToCacheDirectory: true`, the returned
    `uri` is readable by FileSystem on both iOS and Android.
  - Normalize line endings (`\r\n` → `\n`) and trim extraneous whitespace.

Validation basics:

- Accept common formats:
  - OpenSSH:
    `-----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----`
  - RSA: `-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----`
  - ECDSA/ED25519/ED448/DSA similarly.
- Quick checks:
  - Contains a matching BEGIN/END block.
  - Reasonable length (e.g., 500–5000 chars); reject empty/suspiciously short.
  - Optional: basic type inference from header for metadata.
- Store as-is on success; more advanced parsing is a future enhancement.

## Public Key Handling

- Generated keys: `generateKeyPair` likely returns a `publicKey` alongside
  `privateKey`. Store that public key in metadata so users can copy it later.
- Imported keys: deriving public keys on-device for all types may require an
  extra JS crypto library. To keep scope small and reliable:
  - MVP: Allow the user to optionally paste a corresponding public key during
    import (or later via “Add Public Key”).
  - Stretch: Add an optional dependency to derive a public key from the private
    key (e.g., a pure JS RSA/ed25519 parser) and auto-populate the metadata when
    feasible.
- UI: “Copy Public Key” button copies `metadata.publicKey` to clipboard; if
  absent, offer “Add Public Key”.

## Data Model Changes (backward-compatible)

- Extend `keyMetadataSchema` with optional fields:
  - `publicKey?: string` — OpenSSH public key (single line) or PEM.
  - `keyType?: SshPrivateKeyType` — derived from header or generator input.
  - `keySize?: number` — for RSA/ECDSA when known.
  - `fingerprint?: string` — short identifier derived from the private key (see
    below).
  - Keep existing: `priority`, `createdAtMs`, `label?`, `isDefault?`.
- Compute `keyId` at import/generate time:
  - Prefer deterministic id using a short fingerprint: `key_<8-char-fp>`.
  - Use `expo-crypto.digestStringAsync('SHA-256', privateKey)` → base16; take
    first 8–10 chars for id and show full fingerprint in row subtitle if needed.
  - Fallback to current `key_<timestamp>` if hashing ever fails.
- Size considerations:
  - Metadata is bounded by the ~1KB per-manifest-chunk budget; an OpenSSH public
    key line is typically < 1KB, so storing `publicKey` is safe.

## Implementation Steps

1. Secrets manager updates

- Update `keyMetadataSchema` (optional fields listed above) in
  `apps/mobile/src/lib/secrets-manager.ts`.
- When generating a key, store `metadata.publicKey`, `metadata.keyType`,
  `metadata.keySize`, and computed `fingerprint`.
- Add a tiny helper:
  `computeKeyFingerprint(privateKey: string): Promise<string>` using
  `expo-crypto`.

2. Key Manager modal — UI and flows

- Add “Import Key” entry. Implement a small state machine:
  `mode = 'list' | 'import' | 'generate'`.
- Import mode:
  - Tabs or toggle between “Paste” and “Pick File”.
  - Paste: multiline `TextInput`, Validate, Label input, Default toggle, Save.
  - Pick File: Launch DocumentPicker, read via FileSystem, fill preview,
    Validate, Label input, Default toggle, Save.
- Generate mode: show label/type/size/comment inputs; on submit generate and
  upsert.
- List mode rows:
  - Show label, id, createdAt (formatted), and default badge.
  - Row actions: Select (radio), Copy Public Key, Rename, Set Default, Delete.
  - If no `metadata.publicKey`, action shows “Add Public Key” and opens a small
    paste dialog; on save, upsert metadata only.

3. Copy public key

- Use `expo-clipboard`:
  - `await Clipboard.setStringAsync(metadata.publicKey)`
  - Show a small toast/snackbar or inline confirmation.

4. Date formatting

- Add `date-fns` and format with either `format` (e.g., `MMM d, yyyy`) or
  `formatDistanceToNow` for a relative display. Placement: muted line under the
  label in each row.

5. Validation utilities

- Add a small util module: `parseSshPrivateKey.ts` with functions:
  - `detectPrivateKeyType(pem: string): SshPrivateKeyType | 'openssh' | undefined`
  - `isLikelyValidPrivateKey(pem: string): boolean`
  - These are string/regex based for MVP; we can replace with stronger parsing
    later.

6. Error handling

- Show inline errors in the import modal (invalid format, unreadable file, empty
  input).
- Disable Save until validation passes.

## Dependencies to add

- `expo-document-picker` — file selection.
- `expo-file-system` — read selected file contents.
- `expo-clipboard` — copy public key.
- `date-fns` — format timestamps.

Notes:

- Ensure proper installation via
  `npx expo install expo-document-picker expo-file-system expo-clipboard date-fns`.
- For DocumentPicker, prefer `copyToCacheDirectory: true` to guarantee a
  readable `uri`.

## Security & Privacy

- Never log key material or show it in error messages.
- Keep logs behind a debug flag; redact key strings in any analytics.
- Continue storing private keys in `SecureStore` (already handled), avoid moving
  them to less secure storage.

## Testing Plan

- Unit tests for the validation utils with sample PEM strings.
- Manual QA on devices/simulators:
  - Paste invalid/valid keys (OpenSSH, RSA) → proper errors/success.
  - Pick a `.pem`/no-extension text file → reads, validates, stores.
  - Rename, set default, delete flows unchanged.
  - Copy public key present vs. absent → “Add Public Key” flow wiring.
  - CreatedAt formatting appears correctly and is stable across renames.

## Implementation Notes (cross-cutting)

- Keep all key writes going through `upsertPrivateKey` so React Query
  invalidation stays consistent.
- Preserve `createdAtMs` on upserts (already implemented), add `fingerprint`
  only once when first inserted.
- If adding new metadata fields, mark them optional in zod to avoid breaking
  existing entries.