Vaults, access and roles

A team’s items live in vaults. Who may open a vault, and what they may do there, comes from their role, from any extra vaults given to them, and from what the vault itself allows. Every change to any of it is signed into the team’s record and checked by every member’s app.

Vaults

A vault is a shared store inside a team, with its own key and its own list of who may open it. You see only the vaults you can open. Their names are encrypted, and “You can’t see the names of vaults you don’t open.”

While a team is on screen, the Hosts page lets you pick a vault:

• On a computer: the vault button at the top of the Hosts page shows All vaults or the vault on screen. It opens a list of All vaults and each vault you open, with how many hosts each holds, Read-only next to a vault you cannot add to, and a lock on an owners-only vault. With more than seven vaults, Find a vault searches them. Manage vaults at the foot opens the Vaults page. With more than one vault, the button’s tooltip says where new items go, for example “New items go to Shared”.
• On a phone: chips above the host list show All vaults and each vault, with how many hosts it holds. A lock on a chip, with the tooltip Read-only, marks a vault you cannot add to. With more than one vault, the line “New items go to Shared” says where new items go.

Picking a vault shows only its hosts. It also becomes the vault new items go to, as long as you may add there.

To move a host, choose Move to vault in the host’s menu. Moving needs delete in the vault it leaves and add in the vault it goes to.

Add a vault

You can add vaults if you are an owner or an admin, or if your role has Add vaults (they manage the ones they add).

1. Open the Team pages, then Vaults, and choose New vault (at the top of the page on a computer, under the list on a phone). On a phone, the New vault chip above the host list and New vault in the space switcher do the same.
2. Under Vault name, type a name, for example “Production”.
3. Owners only: tick Owners only for a vault no admin or role ever reaches. See Owners-only vaults.
4. Choose Create vault.

A new vault opens to the owners, to the admins (unless it is owners-only) and to whoever made it. Someone below Admin who makes a vault gets Manage on it. Nobody else gets the vault until an owner adds it to their role or someone who manages it gives it to them as an extra vault.

A new vault allows SFTP and port forwarding, not agent forwarding. A team holds up to 200 vaults.

Access levels

What someone may do in a vault is a set of switches. The four levels are presets of them, each including the one before:

Level	What it allows
Connect	Connect to the vault’s hosts, with SFTP and port forwarding where the vault allows them. Passwords and keys stay hidden.
Use	Also see and copy the vault’s passwords, passphrases and private keys.
Edit	Also add, change and delete items.
Manage	Also the vault’s name and what it allows, giving it to people below you, and replacing its key.

Agent forwarding is a switch of its own and part of no level. A role can add it per vault where the vault allows it.

A set of switches that matches no level shows as Custom, and a vault someone cannot open as None.

What Connect does not show

At Connect, a key’s secrets show as “Hidden. Your access to this key’s vault is Connect: ZestSSH uses it to connect, and you can’t see, copy or change it.” ZestSSH also refuses the uses that would hand the secret over:

• Mosh and Eternal Terminal need the key as a file: “Connect with SSH instead.”
• A password goes only to hosts you can’t change, so nobody can point a host at a server of their own and read it there.
• Test connection does not send a hidden password to an address typed in.

These are rules of the ZestSSH app, not of encryption: to connect with a key, the device holds it. Give Connect to people you would trust with the key on their device, and change the key when they leave.

The Vaults page

Open the Team pages, then Vaults. On a computer, Vaults in the rail opens it too. With more than seven vaults, Find a vault at the top searches them. Owners-only vaults come last: “Owners-only vaults are hidden from everyone else, and no role can reach them.”

On a computer

Each vault is a row with its name and a line of what it holds and who opens it, for example “12 hosts · 3 roles can open it”, or “Owners only · 2 hosts” for an owners-only vault. Marks after it say what is on in it: Owners only, Certificates, Session logs, Sessions watched, Asks before revealing, and SFTP, Port forwarding or Agent forwarding where the vault allows them. Where it applies, a status sits next to the name: Closed, Closes soon or Offline pass.

Click a vault to open its pane on the right, and click it again or choose the cross to close it. The pane has, from the top:

• The vault’s name, how many hosts it holds and Your access, with Show its hosts and, where you manage it, Rename (the pencil). Show its hosts opens the Hosts page with only that vault’s hosts. Unlike picking the vault on the Hosts page, it does not change where new items go.
• Who can open it: each role with how many people have it and its level in the vault (None where it gives none), then anyone who holds the vault for a set time, with End now or Give it up. Owners see Edit in Roles, which opens the Roles page.
• Allowed on its hosts: SFTP (“Browse and move files”), Port forwarding (“Tunnels to and from its hosts”) and Agent forwarding (“Lets its hosts use your SSH agent”). Whoever manages the vault ticks them; everyone else sees what is on. A watched vault allows the terminal only.
• Certificates: the vault’s certificate authority. See Certificate authority.
• Protection: Ask again before revealing: “Showing or copying a password, passphrase or private key from this vault asks for the device PIN or a fingerprint first.” Whoever manages the vault switches it; everyone else sees On or Off.
• The vault’s offline limit, its session logs and its records, each described on its own page.
• Danger zone, for an owners-only vault and owners only: Open up. See Owners-only vaults.

On a phone

Each vault you open is a card with its name and a line such as “4 hosts · Your access: Use · Owners only”. Where it applies, a status sits next to the name: Closed, Closes soon, Offline pass or Certificates on.

• Show its hosts opens the Hosts page with only that vault’s hosts, and Rename renames it. Both are in the card’s More actions menu.
• What it allows opens the vault’s settings, and Fold away closes them. With three vaults or fewer, they start open.

Under Access, Allowed here (“What may be used on its hosts besides the terminal.”) has SFTP, Port forwarding and Agent forwarding. If you cannot change them, the card shows what is on, or Terminal only. Ask again before revealing sits below them, then the vault’s offline limit, its certificates, its session logs and its records.

What changes need

Switching off SFTP, port forwarding or agent forwarding switches it off for everyone in the vault, owners too: “SFTP isn’t allowed in this host’s vault.”

Whoever has Manage on a vault renames it and changes what it allows and Ask again before revealing. Changing what it allows, or Ask again before revealing, needs a sign-in from the last 10 minutes; ZestSSH asks with Confirm it’s you when yours is older. Renaming does not.

A vault’s session logs, watched sessions, its own offline limit and its certificate authority are the owners’ alone to change, whoever manages the vault.

Roles

Owner and Admin are fixed:

• Owner: “Everything, in every vault”. Owners are equals.
• Admin: “Every vault except owners-only ones, and everyone below Admin”.

Below them come the roles the owners make. Each has a name, a rank, powers in the team and a level in each vault. The rank is the order on the Roles page: owners come first, then admins, then the roles the owners make, highest first. People manage only those below them. A team has room for 30 roles of its own.

A role’s powers in the team:

• Invite people into roles below theirs
• Suspend and remove people below them
• Change the roles and end dates of people below them
• Add vaults (they manage the ones they add)

Whoever uses a power hands out no more than they hold: nobody can invite someone, or move them into a role, that opens more than they have themselves.

The Roles page

Only owners see the Roles page: “What each role can do, in the team and in each vault. People can only manage roles below their own.”

On a computer it is one table. A row for each role, Owner and Admin first (marked Built in), then the roles the owners made, highest first. Each row shows how many people have the role, and how many wait to join with it. The columns:

• What it can do in the team: Everything for owners, and for the other roles a chip for each power: Invite, Remove, Change roles and Add vaults. Click a chip of a role the owners made to switch that power on or off.
• A column for each vault, with how many hosts it holds, and the role’s level there. Owners-only vaults show as Owners only for every role but Owner.

To change a level, click it. The list of levels opens, each with what it means:

Level	What the list says
None	”Can’t see this vault or its hosts.”
Connect	”Connect without seeing passwords or keys. The app hides them, but without certificates the device still holds them.”
Use	”Also see and copy passwords and keys.”
Edit	”Also add, change and delete hosts.”
Manage	”Also change this vault’s settings.”

Below them, Agent forwarding can be ticked for that vault. Where the vault does not allow it, the list says “Off in this vault.” with Change in Vaults, which opens the vault’s pane.

Drag a role by its handle to change its order (“Drag a role to change its order”). Each role’s menu has Edit, Move up, Move down and Delete.

On a phone, Roles is a list of the roles. Each role the owners made has Move up, Move down, Edit (the pencil) and Delete (the bin), and New role sits under the list.

Make or change a role

1. Open the Team pages, then Roles.
2. Choose New role, or Edit for a role.
3. Under Name, type its name, for example “Developers”.
4. Under People with this role can, tick its powers.
5. Under Vaults, pick a level for each vault, or None. Tick Agent forwarding where you want it; it is greyed out where “This vault doesn’t allow agent forwarding”. Owners-only vaults are not listed.
6. Choose Save, and sign in again if asked.

Every change on the Roles page, in the table or in the dialog, needs a sign-in from the last 10 minutes. A new role goes below every other. What members can open changes right away; anyone who loses a vault loses its key, and the key is replaced.

To delete a role, choose Delete, pick a role under Move its members to, then choose Delete role. The last role cannot be deleted: “Make another role first: its members need somewhere to go.”

How roles map to vaults

What a person may do in a vault is worked out from the team’s record:

• Owners: everything, in every vault.
• Admins: everything, in every vault except owners-only ones.
• Everyone else: the level their role gives in that vault, plus any extra vault given to them, plus any access given for a set time.

In every case the vault’s own Allowed here settings switch off SFTP, port forwarding or agent forwarding for everyone. A member’s panel on the Members page lists their level in each vault under Vault access.

Give someone extra vaults

Extra vaults give one person a vault, or more in a vault, on top of their role.

1. Open Members and open the person, then choose Extra vaults.
2. In Extra vaults for robin@example.com, tick a vault and pick a level.
3. Choose Save, and sign in again if asked.

You can give only vaults you Manage, no more than you have there, and only to people below you. Owners and admins get no extra vaults, since they already open every vault they may. Owners-only vaults cannot be given. An extra vault they hold that you do not manage shows “Given by someone who manages it”, and stays as it is.

Access for a set time

On the Overview, Access for a set time lets people below Admin choose Ask for access, and lets people who manage a vault choose Give access. It ends by itself:

• At most 30 days, and never Manage.
• Never for an owners-only vault, and never for owners or admins: “Owners and admins open every vault already.”
• Someone who manages the vault can End now; the person who holds it can Give it up. Ending it early does not take back what they saw: “Passwords and keys they opened there are still known to them.”

Owners-only vaults

An owners-only vault is for what no admin or role should reach, such as the keys of a certificate authority.

• Only owners open it. “Admins and roles never reach it.” No role and no extra vault can include it.
• Owners-only is set when the vault is made, with Owners only in New vault.
• It can be opened up, once. An owner opens the vault’s settings on the Vaults page and, under Danger zone, next to Open to admins and roles, chooses Open up, then Open it up: “Admins get it right away, and you can give it to roles and people. It can’t be made owners-only again.”
• A vault that keeps a certificate authority’s key stays owners-only. See Certificate authority.
• It needs an owner who can still sign in. With a sole owner who loses access, vaults only owners can open stay locked. Keep two owners.

Limits

• What Connect hides, Ask again before revealing and the export rules are kept by the app. A device that may connect with a key holds it.
• What was seen stays seen. Lowering someone’s level, or ending their access, does not take back a secret they could see.
• Names follow access. Where you cannot open a vault, ZestSSH calls it “a vault you can’t open”.
• Changes need a recent sign-in. Changing roles, extra vaults or what a vault allows asks for a sign-in from the last 10 minutes.

Next steps

• Create a team and invite people: offer a role and vaults in an invitation.
• Join a team with a code: offer a role and vaults with a one-time code.
• Suspend, remove and leave: take access away and replace keys.
• Teams overview: roles at a glance, encryption and seats.