From 0c56c89f74ea7e21af168cfe54770de9532f3264 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicolas=20=E2=80=9CNiols=E2=80=9D=20Jeannerod?=
 <nicolas.jeannerod@moduscreate.com>
Date: Tue, 4 Feb 2025 12:45:47 +0100
Subject: [PATCH] Document adding a contributor

---
 infra/README.org  | 12 +++++++++++-
 keys/README.md    | 32 ++++++++++++++++++++++++++++++++
 secrets/README.md |  5 +++++
 3 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 keys/README.md

diff --git a/infra/README.org b/infra/README.org
index d426a0d6..8029f4b0 100644
--- a/infra/README.org
+++ b/infra/README.org
@@ -1,6 +1,9 @@
 #+title: Infra
 
 This directory contains the definition of the VMs that host our infrastructure.
+
+* NixOps4
+
 Their configuration can be updated via NixOps4. Run
 
 #+begin_src sh
@@ -26,14 +29,21 @@ Then, given a deployment (eg. ~git~), run
 nixops4 apply <deployment>
 #+end_src
 
+Alternatively, to run the ~default~ deployment, run
+
+#+begin_src sh
+nixops4 apply
+#+end_src
+
 * Deployments
 
+- default :: Contains everything
 - ~git~ :: Machines hosting our Git infrastructure, eg. Forgejo and its actions
   runners
 - ~web~ :: Machines hosting our online content, eg. the website or the wiki
 - ~other~ :: Machines without a specific purpose
 
-* Procolix machines
+* Machines
 
 These machines are hosted on the Procolix Proxmox instance, to which
 non-Procolix members of the project do not have access. They host our stable
diff --git a/keys/README.md b/keys/README.md
new file mode 100644
index 00000000..707b8088
--- /dev/null
+++ b/keys/README.md
@@ -0,0 +1,32 @@
+# Keys
+
+This directory contains the SSH public keys of both contributors to the projects
+and systems that we administrate. Keys are used both for [secrets](../secrets)
+decryption and [infra](../infra) management.
+
+Which private keys can be used to decrypt secrets is defined in
+[`secrets.nix`](../secrets/secrets.nix) as _all the contributors_ as well as the
+specific systems that need access to the secret in question. Adding a
+contributor of system's key to a secret requires rekeying the secret, which can
+only be done by some key that had already access to it. (Alternatively, one can
+overwrite a secret without knowing its contents.)
+
+In infra management, the systems' keys are used for security reasons; they
+identify the machine that we are talking to. The contributor keys are used to
+give access to the `root` user on these machines, which allows, among other
+things, to deploy their configurations with NixOps4.
+
+## Adding a contributor
+
+Adding a contributor consists of three steps:
+
+1. The contributor in question adds a file with their key to the
+   `./contributors` directory, and opens a pull request with it.
+
+2. An already-existing contributor rekeys the secrets, taking that new key into
+   account. See [../secrets#adding-a-contributor].
+
+3. An already-existing contributor redeploys the infrastructure to take into
+   account the new access. See [../infra].
+
+4. The pull request is accepted and merged.
diff --git a/secrets/README.md b/secrets/README.md
index 08b135e8..a80ef16d 100644
--- a/secrets/README.md
+++ b/secrets/README.md
@@ -49,3 +49,8 @@ As an example, let us add a secret in a file “cheeses” whose content should
    service that you are using must be able to read from a file at runtime, and
    if the NixOS default module options do not provide that, you must find a way
    around it.
+
+### Adding a contributor
+
+See [../keys]. Rekeying can be done by running `agenix --rekey` (or `-r` for
+short) in the current directory. This requires access to the secrets.