Vaults

Vaults let teams share secrets. Each vault has its own encryption key, and each member gets an individually wrapped copy — revoking a member takes effect immediately without re-encrypting vault secrets, and rotating the vault key afterwards locks them out cryptographically.

Vault roles

Role	Permissions
owner	Full control (one per vault)
admin	Can invite, promote, demote, and revoke members
member	Can read and write secrets

Creating a vault

ssh -A alice@keys.example.com vault create team

You become the owner of the vault.

Inviting members

ssh -A alice@keys.example.com vault invite team bob
# → 3f9ab2c1d4e5...   (64-character invite token)

Share the invite token with the user out-of-band (e.g. via a secure channel). Note that tokens passed as command arguments typically end up in shell history — see Security Notes.

Accepting an invitation

ssh -A bob@keys.example.com vault accept team 3f9ab2c1d4e5...

Promoting members

ssh -A alice@keys.example.com vault promote team bob

Promotes a member to admin.

Demoting members

ssh -A alice@keys.example.com vault demote team bob

Demotes an admin to member. The vault owner cannot be demoted.

Revoking members

ssh -A alice@keys.example.com vault revoke team bob

Removes a user from the vault entirely. Their wrapped vault key is deleted. The vault owner cannot be revoked.

Revocation removes access immediately, but it does not change the vault key. A revoked member who saved the key while they had access could still decrypt vault ciphertexts if they ever obtained them (for example from a leaked backup). Run vault rotate after revoking to close that door.

Rotating the vault key

ssh -A alice@keys.example.com vault rotate team

Generates a fresh vault key and re-encrypts every secret in the vault under it. Owners and admins can rotate. You will be prompted to type the vault name to confirm.

Each member's copy of the vault key is wrapped by their own SSH agent, and the server cannot re-wrap for agents that are not connected — so everyone except the rotator must re-join. vault rotate prints a fresh invite token for each of them, and their roles are preserved when they re-accept:

Vault "team" key rotated.

New invite tokens (expire in 72h0m0s; deliver securely, never through the vault itself):
  bob (member): 3f9ab2c1d4e5...
  carol (admin): 81c2d3e4f5a6...

Members redeem with: vault accept team <token>

Deliver each token out-of-band over a secure channel. Invitees who never accepted their original invite receive a fresh token too, since their old one wrapped the retired key.

If a token expires before it is redeemed, an owner or admin can issue a replacement with vault invite — re-inviting is allowed for members who have lost their key copy.

Listing members

ssh -A alice@keys.example.com vault members team

Destroying a vault

ssh -A alice@keys.example.com vault destroy team

This permanently deletes the vault and all its secrets. Only the vault owner can destroy a vault. You will be prompted to type the vault name to confirm — this action cannot be undone.

Vault secrets

Use colon syntax to target a vault — vault:path:

# Store a secret in the vault
ssh -A alice@keys.example.com set team:deploy/api-key

# Retrieve it
ssh -A bob@keys.example.com get team:deploy/api-key

# Delete a vault secret (prompts for confirmation)
ssh -A alice@keys.example.com del team:deploy/old-key

# List vault secrets
ssh alice@keys.example.com list team:

Workflow example

# Alice creates a shared vault
ssh -A alice@keys.example.com vault create team

# Alice invites Bob
ssh -A alice@keys.example.com vault invite team bob
# → 3f9ab2c1d4e5...   (64-character invite token)

# Bob accepts the invitation
ssh -A bob@keys.example.com vault accept team 3f9ab2c1d4e5...

# Alice stores a secret in the vault
ssh -A alice@keys.example.com set team:deploy/api-key

# Bob retrieves it
ssh -A bob@keys.example.com get team:deploy/api-key