feat(ui-react): add Secure Vault for encrypted SSH private key storage

[luizhf42]

What

Encrypted SSH private key storage in the browser, protected by a master password. Keys are encrypted with AES-256-GCM (PBKDF2-SHA256 derived key) and persisted in localStorage. Private key authentication uses SSH challenge-response signing — the raw key never leaves the browser.

Why

ShellHub previously stored private keys in plain text in localStorage. The Secure Vault encrypts keys at rest behind a master password, matching the security model of tools like Termius Vault. This is the community/self-hosted implementation; the backend adapter pattern (IVaultBackend) supports future server-side storage for cloud/enterprise.

Changes

• Crypto layer (vault-crypto.ts): AES-256-GCM encryption/decryption, PBKDF2-SHA256 key derivation (600k iterations), verifier-based password checking without storing the password hash. Session key held in module scope (not in React state or localStorage).
• Storage abstraction (vault-backend.ts, vault-backend-local.ts): IVaultBackend interface with localStorage implementation and singleton factory.
• SSH key utilities (ssh-keys.ts): sshpk-based key validation with KeyEncryptedError detection for auto-detecting passphrase-protected keys, MD5 fingerprint extraction, algorithm/size detection (getAlgorithm), and challenge-response signature generation (RSA via node-rsa pkcs1-sha1; ED25519 via sshpk raw 64-byte output; ECDSA via sshpk with per-curve hash — SHA-256/nistp256, SHA-384/nistp384, SHA-512/nistp521 — and SSH wire format blob extraction).
• Vault store (vaultStore.ts): Zustand store managing vault lifecycle (uninitialized/locked/unlocked), key CRUD with duplicate name/data prevention, master password change, vault reset, and legacy key migration from the Vue UI format.
• Vault UI components: Setup dialog, unlock dialog (with autocomplete suppression), settings section (change password, lock, reset with typed confirmation).
• Secure Vault page: Three-state page — onboarding landing for uninitialized, full-screen locked state (matching the FeatureGate pattern), and key management table. The table is always visible when unlocked, with an in-table empty state, search by name or fingerprint, add/edit drawer (auto-detects encrypted keys and prompts for passphrase), and delete confirmation. Each key row displays its algorithm (e.g. Ed25519, RSA 4096, ECDSA P-256) and a lock icon for passphrase-protected keys.
• Terminal integration: TerminalInstance now implements the WebSocket challenge-response protocol (kind 3 Signature) for private key auth — POST sends fingerprint only, browser signs challenges locally. Sensitive key material is cleared immediately after signing and on component unmount. ConnectDrawer adds vault key selector with vault/manual toggle and unlock prompt when vault is locked.
• Auth integration: Vault session key cleared on logout (explicit, token expiry, 401).
• Reusable key file input: Extracted shared file input logic (drag-and-drop, paste interception, file/text mode toggle) into useKeyFileInput hook and KeyFileInput component, used by both public keys and secure vault drawers.
• Dependencies: Added sshpk, node-rsa, vite-plugin-node-polyfills (provides Node.js globals for sshpk/node-rsa in browser).

Testing

• Set up a vault, add keys (with and without passphrase), verify encrypted storage in localStorage (shellhub-vault-meta, shellhub-vault-data — no plaintext).
• Connect to a device with private key auth via vault selector and manual input — verify challenge-response completes (no kind 4 error).
• Test RSA, ED25519, and ECDSA key types for both vault storage and terminal connection.
• Change master password, then verify old password fails and new password unlocks with all keys intact.
• Reset vault, verify return to onboarding state.
• Logout and verify vault locks (session key cleared).
• If privateKeys exists in localStorage (legacy Vue UI), verify migration on first vault setup.
• 322 unit/component tests covering store, crypto utils, SSH key utils, backend, hook, and UI components.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 8m 48s —— View job

---

Code Review Complete

Reviewed 39 files across code quality, security, testing, TypeScript/React patterns, and architecture. 14 inline issues posted (1 high, 9 medium, 4 low).

Highlights

Security — The crypto implementation is sound: AES-256-GCM with PBKDF2-SHA256 at 600k iterations, fresh random IVs, session key in module scope (not React state or localStorage), vault locked on logout. Challenge-response SSH signing correctly keeps the private key client-side. One gap: clearSensitiveData is missing in the signature failure path (see comment).

Architecture — The IVaultBackend interface is synchronous, which will require a breaking refactor when adding the cloud/enterprise server-side backend (see comment). Vault storage keys aren't namespaced per user (see comment).

Performance — Six components use useVaultStore() without selectors, causing unnecessary re-renders cascading from the page root (see comment).

Additional notes

Testing gaps — 311 tests cover the store, crypto, SSH utils, backend, hook, and some UI components well. However, four vault UI components have zero test coverage: VaultSetupDialog, VaultUnlockDialog, VaultSettingsSection (including ChangePasswordDrawer), and ConnectDrawer. These are security-sensitive components handling master password entry, vault initialization, password changes, and SSH key authentication. Also, TerminalInstance's new challenge-response signing flow has no tests.

Token expiry — The logout action correctly locks the vault, but when the session expires via API interceptor redirect (without a full page reload), the vault session key may remain in memory. The interceptor should also call useVaultStore.getState().lock().

---

If you've addressed the feedback and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 6m 31s —— View job

---

Code Review Complete

Reviewed 39 files across code quality, security, testing, TypeScript/React patterns, and architecture — no issues found.

All fixes from the previous five review rounds were verified as correctly applied. The code looks good as-is.

---

If you push additional changes and want a new review, tag @shellhub-io/admin and a team member can trigger it.

[gustavosbarreto]

/review

[github-actions]

Claude finished @gustavosbarreto's task in 4m 18s —— View job

---

Code Review Complete

Reviewed 39 files across code quality, security, testing, TypeScript/React patterns, and architecture — no issues found.

All fixes from the previous five review rounds were verified as correctly applied. The code looks good as-is.

---

If you've addressed the feedback and want a new review, tag @shellhub-io/admin and a team member can trigger it.

View job