Vault System & Password Manager

Purpose

• Encrypt hosts.json at rest on your own machine, so someone with filesystem access to your laptop (or a stolen backup) can't read your saved server list and credentials in plain text.
• encrypt ciphertext hosts.json your saved connections Personal Vault AES-256-GCM, local key Disk unreadable without the key Everything stays on this one machine — Personal Vault has no network component at all.

How to do it

1. 1Open Settings → Encrypted Vault.
2. 2Choose a mode: auto (the default — a key is generated and stored in your OS's own keychain, so the vault unlocks silently as long as you're logged into your OS account, with zero extra password to remember) or vault (set an explicit master password you type in yourself, for a deliberate extra unlock step).
3. 3In vault mode, set a Lock timeout (minutes of inactivity before it auto-locks again).
4. 4Optionally enable the biometric gate (Windows Hello / Touch ID) specifically for revealing/copying Password Manager entries, on top of whichever vault mode you picked.

How to verify

1. 1In vault mode: lock the vault manually, restart the app, and confirm you're prompted for the master password before host data loads.
2. 2In auto mode: confirm hosts load with no prompt at all on this same machine, then copy the raw hosts.json file to a different machine and confirm it does not decrypt there (proving the key really is tied to this machine's keychain, not embedded in the file).

Troubleshooting

• Forgot the master password (vault mode) — there is no recovery; this is by design (a recoverable master password would mean it isn't really the only thing protecting the data).
  • Removing/resetting the vault means starting the host list over.
• Switched from auto to vault mode and now prompted unexpectedly — expected the first time; that's the whole point of the mode change.

Purpose

Require a Windows Hello / Touch ID gesture specifically before a saved Password Manager entry's plaintext password is ever unmasked or copied — an extra gate on top of whichever Personal Vault mode you're using, scoped to just this one sensitive action rather than the whole app.

How to do it

1. 1Open Settings → Encrypted Vault.
   • If your machine has working Windows Hello (or Touch ID on a Mac) — enrolled, not just present as hardware — expect to see a checkbox reading exactly "Require Windows Hello to reveal passwords" (or "Require Touch ID to reveal passwords" on macOS).
2. 2If that section is missing entirely, look for a note in its place explaining why (not enrolled, no hardware) — that's the availability check correctly hiding an option that wouldn't work, not a bug.
3. 3Check the box to turn the gate on.

How to verify

1. 1If you don't already have one, open More → Password Manager , click + Add , fill in a name/username/password, and save.
2. 2Click the reveal button (the eye icon) on that row.
   • Expect a real Windows Hello (or Touch ID) prompt to pop up immediately — not a silent unmask.
3. 3Complete the gesture.
   • Expect the password to unmask AND the button's icon itself to flip from the eye icon to a covered-eye icon (its hide state).
4. 4Click again to re-hide it.
   • Expect this to happen instantly with NO prompt — hiding is never gated, only revealing is.
5. 5Click reveal on a masked row again, but this time cancel/dismiss the Hello prompt instead of completing it.
   • Expect the password to stay masked and a toast to appear, starting with a lock icon and reading exactly "Canceled." — not a silent failure.
6. 6Click the copy button (the clipboard icon) on a masked row.
   • Expect the same gesture prompt, and on success, a toast starting with a clipboard icon and reading exactly "Password copied" .
7. 7Go back to Settings → Encrypted Vault and uncheck the toggle.
   • Reveal and copy a password again — expect both to work instantly with no prompt at all, confirming the toggle genuinely turns the gate off rather than just hiding its UI.

Troubleshooting

• Checkbox never appears — confirm Windows Hello (or Touch ID) is actually enrolled in your OS settings, not just that the hardware exists; presence and enrollment are different things and only enrollment satisfies the availability check.
• Reveal succeeds with no prompt even though the toggle is checked — this would be a real bug (the gate silently not applying); worth reporting rather than assuming it's expected.

Purpose

• Keep a team's shared host list in sync using storage you already have — Dropbox, OneDrive, a self-hosted WebDAV folder, or any shared filesystem path — with no MangoSSH-operated server anywhere in the picture.
• push pull This device Shared folder / URL Dropbox, OneDrive, WebDAV… Teammate's device Team Vault has two trust modes: a shared passphrase (simpler), or per-device keypairs with individual approve/revoke (stronger — a revoked device's key is actually rotated out, not just "asked nicely" to stop syncing).

How to do it

1. 1Open Settings → Team Vault.
2. 2Create a team : pick a shared folder (or URL) and give it a Team Passphrase (simple mode) — or use keypair mode for per-device approval and individually-revocable access.
3. 3Join an existing team : point at the same folder/URL; in passphrase mode, entering the right passphrase joins immediately; in keypair mode, your device sends a join request that an existing admin member must approve.
4. 4Once set up, hosts pushed by any member sync to everyone else's copy the next time they sync (manual or on the schedule you configure).

How to verify

1. 1On Device A, create the team (or join it), add a distinctively-named test host (e.g. "TEAM-SYNC-TEST"), and trigger a sync (manual button, or wait for the configured interval).
2. 2On Device B (already a team member), trigger a sync there too.
   • Expect "TEAM-SYNC-TEST" to appear in Device B's own sidebar within that sync — check the timestamp/host count shown in the Team Vault pane to confirm it actually pulled fresh data, not stale cache.
3. 3Keypair mode only : from Device A (as admin), open the member list and revoke Device B.
   • On Device B, attempt a sync.
   • Expect it to fail with an access-denied-style message rather than silently succeeding — this is the proof revocation is real, not just cosmetic.

Troubleshooting

• Sync doesn't pick up a teammate's change — this is manual/periodic, not instant real-time; trigger a sync explicitly, or check your configured auto-sync interval.
• Keypair mode: stuck "waiting for approval" — an existing admin member has to actively approve the join request from their own device; nothing happens until they do.
• Lost every device's access (keypair mode) — this is exactly what the recovery code generated at team-creation time is for; without it, and with every device gone, the team vault cannot be recovered by design (same non-recoverable-by-design principle as the master password above).

Purpose

• The same zero-knowledge sync protocol as Team Vault, but backed by a real server you run (e.g. on a small VPS) instead of a shared folder — useful once folder-sync propagation delay/conflicts become a real problem for a bigger team.
• This was previously just called "Cloud Vault" — renamed to Self Hosting Vault (display text only) once MangoSSH added a second, MangoSSH-operated hosted option (below) under the freed-up "Cloud Vault" name.

How to do it

1. 1Deploy the cloud-server component yourself (Docker Compose provided) on infrastructure you control.
2. 2Open Settings → Self Hosting Vault, enter your server's URL, and either create a new vault (you become its admin, and get a one-time recovery code — save it immediately) or join an existing one by vault ID.

How to verify

1. 1After docker compose up , create a new vault from a first device — expect a one-time recovery code to be shown; copy it somewhere safe immediately (it is never shown again).
2. 2Add a distinctively-named test host and push.
   • In a separate terminal, run docker compose logs -f on the server and expect to see a request line corresponding to that push arrive within a second or two of clicking sync.
3. 3From a second device, join using the same vault ID, and expect the test host to pull down and appear in that device's sidebar without you re-entering the host's details.
4. 4Deliberately enter the WRONG vault ID once from a third device and expect a clear "vault not found"-style error rather than a silent hang.

Troubleshooting

• Can't reach the server from a device — this is standard server/network troubleshooting (firewall, port, TLS termination in front of it) — nothing MangoSSH-specific once the server itself is confirmed running.
• Lost the recovery code and every admin device — same non-recoverable-by-design outcome as Team Vault's keypair mode; the server never has the key material to help you recover it even if you had full database access.

Purpose

• The same protocol as Self Hosting Vault, but on a server MangoSSH itself runs — for when you don't want to provision or maintain a VPS at all.
• Gated by a lightweight email account (identity/billing/recovery only — sign-in is a one-time 6-digit emailed code, never a password) and, during the current beta, a manually-toggled "paying tier" flag rather than live billing.

How to do it

1. 1Open Settings → Cloud Vault, enter your email, and enter the 6-digit code sent to it.
2. 2If your account is on the paying tier, proceed exactly like Self Hosting Vault from here (create/join a vault) — the Server URL is pre-filled and locked to MangoSSH's hosted endpoint.
3. 3If not yet on the paying tier, you'll see an upgrade prompt instead of the vault setup flow.

How to verify

1. 1Enter your email and click whatever sends the code.
   • Expect a 6-digit code to arrive in your inbox within roughly a minute.
2. 2Enter the code.
   • Expect Settings → Cloud Vault to now show your email as linked — reopen that Settings pane after restarting the app and confirm the linked email is still shown (proving it's persisted, not just an in-memory session state).
3. 3If your account isn't on the paying tier yet, confirm you see an upgrade prompt in place of the create/join vault UI — not a broken or empty form.

Troubleshooting

• Code email never arrives — check spam first; codes are short-lived (expire after a few minutes) and rate-limited, so request a fresh one rather than retrying a stale one repeatedly.
• "Upgrade to enable" even though you believe you're paying — during this beta, tier flips are manual on MangoSSH's side; this is a support/billing question, not a local misconfiguration.

Purpose

Store general logins (name, username, password, URL, notes) that aren't tied to any specific SSH/RDP host — the same everyday job as Bitwarden/1Password, built into MangoSSH and encrypted through the same Personal Vault key.

How to do it

1. 1Open More → Password Manager .
2. 2Click + Add , fill in Name/Username/Password/URL/Notes/Folder (a free-text tag, not a real folder tree), and optionally click Generate next to the password field (length + character-class options) — a live strength meter updates as you type or generate.
3. 3Use the search box to filter by name/username/URL/folder as you type.
4. 4Use the reveal, copy, .
   • edit, and delete actions per row.

How to verify

1. 1Click + Add, type a short weak password (e.g. "abc") into the Password field, and expect the strength meter to show Weak/red.
   • Clear it and click Generate instead — expect a long random string to fill the field AND the meter to jump to Strong/green immediately.
2. 2Save the entry, then use the search box to type part of its name.
   • Expect the list to filter down to matching rows as you type, not just after pressing Enter.
3. 3Click on the entry.
   • Expect a "Password copied" toast, then paste (Ctrl+V) into any text field and confirm the pasted value matches the generated password exactly.
4. 4Click .
   • to edit the entry, change the Notes field only, save, and confirm the password itself is unchanged (re-copy it and compare).
5. 5Click to delete the entry, confirm the delete prompt, and confirm it's gone from the list immediately without needing to reopen Password Manager.

Troubleshooting

• "Vault is locked" placeholder instead of your list — Personal Vault is in vault mode and currently locked; unlock it in Settings → Encrypted Vault first (the Password Manager shares that same lock state, it has no separate one).
• Entries not shared with Team/Cloud Vault — expected in the current version; the Password Manager is Personal-Vault-only for now, not part of any multi-device sync tier.