Teams and onboarding

Encryption & team onboarding

Access is a pull request — and a human vouch.

Every teammate must be admitted before they can decrypt. A stranger who clones the repo, encrypted files and all, can never open them — they were never added to the recipient set. The first encryptor is the prime, and holds the offline break-glass pair in a vault for the day every laptop is lost.

newcomer · sopsy join

# Alan Turing's MacBook — branch off maingit checkout -b sopsy/add/alan-turing# request to join, and stage the change with --gitsopsy join "Alan Turing" --git# …trade the thumb for --without-touch-id ➜ pending request written to .sopsy.yml ✔ git add .sopsy.yml .sopsy.sha — staged for you ◇ ready-to-paste commit + PR printed below ↓git commit -m "Request access" && git push

member · sopsy approve

# Any already-approved engineer — same branchgit fetch && git checkout sopsy/add/alan-turing# vouch out of band, then approve + stage with --gitsopsy approve "Alan Turing" --git# …or bare `sopsy approve` to triage every request ✔ re-keyed every secret for the new recipient ✔ staged the re-keyed files — commit + PR printedgit commit -m "Approve Alan Turing" && git push ✔ merge the PR — Alan can now decrypt

Add --git to any command that changes files — init, join,approve, edit, and everyrecipient mutation — and sopsy git adds exactly the files it touched (never your plaintext .env) and prints ready-to-paste commit and pull-request commands. The secrets themselves are written with the scriptable shorthandsopsy encrypt .env -o .env.encrypted — no editor required.

Team scenarios

One team, four people, one policy.

Ada, the VP of Engineering, sets the policy and holds the break-glass key. Alan prefers a YubiKey. Grace prefers the Secure Enclave on her MacBook. Dennis works on Linux and does not want hardware keys. Ada's--allow-stores choice decides whether Dennis can join at all, and with what.

Ada

sets the policy

VP of Engineering

$sopsy init -A onchip,exthardware

Hardware only: the Secure Enclave or a YubiKey. The policy is committed in .sopsy.yml.
Interactive init also creates the break-glass key. Ada saves it in the team vault and presses ENTER; sopsy deletes the local copy.
CI never runs init. It gets its own portable key with sopsy recipient ci.

Alan Turing

YubiKey

engineer

$sopsy join "Alan Turing" -s yubikey -c cached -b cached

-c cached: the PIN is asked once per session, until the YubiKey is unplugged.
-b cached: after the PIN, one touch, then not again for 15 seconds.
He pushes the pending entry; Ada runs sopsy approve "Alan Turing".

Grace Hopper

Secure Enclave

engineer

$sopsy join "Grace Hopper" -s enclave

Every decryption asks for Touch ID. Fine for an occasional sopsy edit.
A problem once tools decrypt on their own, in every worktree and every shell. See the caching tips below.

Dennis Ritchie

Linux, no hardware

engineer

$sopsy join "Dennis Ritchie"

Whether Dennis can join at all is Ada's call, made when she ran init.
Under the default hardware-only policy he is refused until he has a YubiKey, or Ada widens the policy.

Dennis joins from Linux: Ada's policy decides

Ada ran init withDennis runsResult

-A onchip,exthardwaresopsy join "Dennis Ritchie"Refused: no allowed store works on his machine. He needs a YubiKey, or Ada widens the policy.

-A onchip,exthardware,keychainsopsy join "Dennis Ritchie" -s keychainHis key lives in the Secret Service keyring (GNOME Keyring, KWallet), encrypted at rest. No plaintext key on disk.

-A anysopsy join "Dennis Ritchie" -s fileHis key is a plaintext file in keys.txt. Anyone who can read his home directory can decrypt every secret.

The repository order never puts a weaker store first: even under -A any, Grace's and Alan's auto still picks hardware. Changing the policy later is a reviewed pull request to .sopsy.yml.

Many worktrees, many prompts?

When every worktree's .envrc runs sopsy decrypt, every new shell means another Touch ID. Three ways out, from least to most strict:

Drop the Touch ID gate

Swap in an Enclave key without Touch ID. It still never leaves the chip, but any program running as you can decrypt silently.

sopsy recipient rotate -s enclave -t

PIN once, no touch

A YubiKey key that asks for the PIN once per session and never for a touch. Policies are fixed in the key, so rotate to change them.

sopsy recipient rotate -s yubikey -c cached -b never

Skip .env entirely

Decrypt into one command's environment. Nothing on disk, one prompt per launch instead of one per shell.

sopsy run -- bin/rails server