Skip to content

docs(secrets): name the second recipient's holder, and fix the roadmap's rejection (#294) #397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Gerrrt merged 1 commit into from
Sep 8, 2026
Merged

docs(secrets): name the second recipient's holder, and fix the roadmap's rejection (#294) #397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 8 additions & 5 deletions docs/roadmap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1525,11 +1525,14 @@ them name the condition that would change the answer.
work whose value is that it is not on the monitoring host. The wiki and
the firewall export copy it already has; the volume backup sets (#92) and
the dead man's switch watcher (#67) are added, decided here and built
under their own issues. **Rejected:** a second age recipient, because
`back-up-the-age-key.md` already answers that gap with an *offline* key
and a second person, and because a private key on `oracle` would put the
backups and the means to open them on one disk and retire the property
the off-host copy exists to have. Also rejected: the ADR-0007 stack, the
under their own issues. **Rejected:** a second age recipient *on `oracle`*,
because a private key there would put the backups and the means to open
them on one disk and retire the property the off-host copy exists to
have — narrowed by
[ADR-0024](adr/0024-hold-a-second-age-recipient-and-prove-each-one-separately.md),
which keeps that rejection and makes a second recipient held *off* the
estate the design (#106); its holder was decided on 2026-09-08 under
[#294](https://github.com/Gerrrt/HomeLab/issues/294). Also rejected: the ADR-0007 stack, the
ADR-0008 tier, bringing `wlp22s0` up to give the watcher an independent
path — that dual-homes a VLAN 99 host onto an untrusted segment — and
switching the machine off, which was never really on offer: the wiki had
Expand Down
23 changes: 17 additions & 6 deletions docs/runbooks/back-up-the-age-key.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,12 +278,23 @@ master password, and that takes everything in it at once.

## What this still does not solve

**One person.** ADR-0024 answers the copy and deliberately does not answer the
holder: whether somebody else should be able to open the estate's secrets is a
question about people, not about mechanism. What has changed is that the
mechanism is now built and exercised — a second holder is the same
`make secrets-add-recipient` with their public key, not a procedure to work out
on the day it matters.
**One person — decided 2026-09-08
([#294](https://github.com/Gerrrt/HomeLab/issues/294)).** ADR-0024 answered
the copy and deliberately left the holder open, because whether somebody else
should be able to open the estate's secrets is a question about people. The
answer is the **technical second named on the break-glass card**: they hold a
recipient of their own, generated where they keep it and never on this host,
which satisfies ADR-0023's off-estate constraint and the handover case in one
move. The location stays out of this repository, as the first key's does.

Whether their key is in `.sops.yaml` yet is read from the file
(`grep -A3 creation_rules .sops.yaml`), not from this paragraph. Adding it is
the procedure above — `make secrets-add-recipient` with their public half — and
then `make secrets-verify-backup` with *each* key, because a re-key that drops
a recipient is the failure mode here. What this still does not solve: their
copy cannot be proved from here on their behalf. `SecretsKeyBackupUnproven`
names the recipient that is overdue, and clearing it for theirs is a visit with
the removable medium, not a timer.

**Revocation is still rotation.** Removing a recipient and re-keying protects
values encrypted from then on. Every historical ciphertext in git stays readable
Expand Down
17 changes: 11 additions & 6 deletions docs/runbooks/successor-handover.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,12 +259,17 @@ grep -A3 creation_rules .sops.yaml # every key that can open the secrets
```

If a recipient there is one somebody else holds, the secrets are recoverable and
this is a phone call rather than a rotation.

**A handover is the moment to add one.** ADR-0024 answers the copy and
deliberately leaves the holder open, which is exactly the question a successor
is. Generate the keypair where *they* will keep it, and add its public half from
a host that can already decrypt:
this is a phone call rather than a rotation. Since 2026-09-08 the design is that
there is one: the **technical second named on the break-glass card** holds a
recipient of their own ([#294](https://github.com/Gerrrt/HomeLab/issues/294),
[`back-up-the-age-key.md`](back-up-the-age-key.md)). If `.sops.yaml` lists two
keys, the second is theirs, and the call is to them.

**A handover is the moment to add yours.** ADR-0024 built the mechanism and
[#294](https://github.com/Gerrrt/HomeLab/issues/294) named the second holder;
a successor is a third. Generate the keypair
where *you* will keep it, and add its public half from a host that can already
decrypt — theirs, if the one you were handed is gone:

```bash
make secrets-add-recipient PUBKEY=age1...
Expand Down