Add managing-public-keys docHEADmaster

1 files changed, 103 insertions, 0 deletions

diff --git a/managing-public-keys.md b/managing-public-keys.md
new file mode 100644
index 0000000..1c73460
--- /dev/null
+++ b/managing-public-keys.md
@@ -0,0 +1,103 @@
+# Managing users' public keys
+
+Every collaborator's identity on this server is just an SSH public key
+file. There's no separate "user account" concept beyond that — adding,
+rotating, or revoking access is entirely a matter of editing files in
+`gitolite-admin/keydir/` and pushing. Admin-only.
+
+## Where keys live
+
+```
+gitolite-admin/keydir/<username>.pub
+```
+
+The filename (minus `.pub`) *is* the gitolite username — it's what you
+use in `conf/gitolite.conf` group/permission lines, and what shows up as
+`hello <username>, this is git@...` when they run `ssh git@... info`.
+
+## Adding a new collaborator
+
+```bash
+git clone git@git.veltar.systems:gitolite-admin
+cd gitolite-admin
+echo 'ssh-ed25519 AAAA... their-comment' > keydir/carol.pub
+# then grant access: add carol to a group or a repo stanza in
+# conf/gitolite.conf (see the main README for examples)
+git add keydir/carol.pub conf/gitolite.conf
+git commit -m "Add carol"
+git push
+```
+
+No server restart needed — pushing to `gitolite-admin` triggers gitolite
+to regenerate `/home/git/.ssh/authorized_keys` automatically. Public keys
+aren't secret, so they're fine to store as plain files in this repo — the
+only thing that actually needs protecting is the *private* half, which
+never leaves the collaborator's machine.
+
+**Verify authenticity before adding a key** — confirm out-of-band (a
+call, an in-person handoff, a channel you trust) that the key really came
+from that person and wasn't swapped for someone else's. Anyone who gets
+their key added here can push/pull whatever gitolite grants that
+username.
+
+## One person, multiple keys (laptop + phone + etc.)
+
+gitolite allows several key files per username, disambiguated by a
+suffix after `@`:
+
+```
+keydir/carol@laptop.pub
+keydir/carol@phone.pub
+```
+
+Both map to the same gitolite user `carol` — either key authenticates as
+her, with identical permissions. Useful for adding a second device
+without creating a second identity.
+
+## Rotating a key (lost/compromised device, routine rotation)
+
+```bash
+cd gitolite-admin
+# overwrite with the new key, or use the @suffix scheme above to add the
+# new one first and remove the old one once confirmed working
+echo 'ssh-ed25519 AAAA...new-key... carol@new-laptop' > keydir/carol.pub
+git add keydir/carol.pub
+git commit -m "Rotate carol's key"
+git push
+```
+
+The old private key stops working the moment this push lands — there's
+no grace period, no caching to worry about.
+
+## Revoking a collaborator entirely
+
+```bash
+cd gitolite-admin
+git rm keydir/carol.pub          # and keydir/carol@*.pub if she had more than one
+# also remove her from any @group lines and repo stanzas in
+# conf/gitolite.conf for config cleanliness (not strictly required for
+# security — without a key she can't authenticate at all — but avoids
+# stale references)
+git commit -m "Revoke carol's access"
+git push
+```
+
+**This does not delete anything she pushed.** Her personal repos (e.g.
+`personal/carol/...`, if she had creator rights) and any shared repos she
+had access to stay exactly as they are on disk — revoking a key only
+blocks future SSH access, it's not a data-deletion operation. If a repo
+needs to be handed to someone else or removed, that's a separate,
+manual step on gwaihir (see the main README's note on repo deletion).
+
+## Checking who has access to what
+
+Anyone can check their own access:
+```bash
+ssh git@git.veltar.systems info
+```
+As admin, you can check anyone's access to a specific repo without them
+needing to be present, from a shell on gwaihir itself:
+```bash
+su - git -c "gitolite access <repo> <username> R any"   # or W, or +
+```
+`DENIED` means no access; anything else means it's granted.