7185a57a
Document delegates: certificates under the collab-refs ceiling
a73x 2026-08-18 17:43
Commit message
README.md
| Old | New | ||
|---|---|---|---|
| @@ -454,6 +454,39 @@ A principal's name is the **basename** of its key file, directories ignored — | |||
| 454 | `laptop/alex.pub` and `desktop/alex.pub` are both `alex`, which is how one person | 454 | `laptop/alex.pub` and `desktop/alex.pub` are both `alex`, which is how one person |
| 455 | adds a second machine. | 455 | adds a second machine. |
| 456 | 456 | ||
| 457 | #### Delegates | ||
| 458 | |||
| 459 | A key in `keydir/` is a person. A certificate is a **delegate** of the person | ||
| 460 | it names, and may write `refs/collab/*` and nothing else. | ||
| 461 | |||
| 462 | `cadir/` mirrors `keydir/`, but answers the other question — not "which keys | ||
| 463 | are this person" but "which CAs may mint delegates of them": | ||
| 464 | |||
| 465 | ```text | ||
| 466 | settings.git | ||
| 467 | ├── keydir/xps14/alex.pub who you are | ||
| 468 | └── cadir/mint/alex.pub who may act as you | ||
| 469 | ``` | ||
| 470 | |||
| 471 | Any OpenSSH CA works. Mint a short-lived credential and hand it to an agent: | ||
| 472 | |||
| 473 | ```console | ||
| 474 | $ ssh-keygen -s mint -I claude-a -n alex -V +10m agent_key.pub | ||
| 475 | ``` | ||
| 476 | |||
| 477 | The cert's principal must name an enrolled person and its CA must be enrolled | ||
| 478 | *for that name* — `cadir/` lends identity, it never creates it. `access.conf` | ||
| 479 | is never consulted about delegates and cannot widen them: no rule grants a | ||
| 480 | certificate a branch, a release, or a repository creation. The same CA key | ||
| 481 | enrolled under two names is allowed (unlike `keydir/`, where one key under two | ||
| 482 | names is an authorization coin-flip): a certificate names its principal, so | ||
| 483 | the lookup runs the other way, and a shared CA is two explicit opt-ins. | ||
| 484 | |||
| 485 | Revocation is the roster: remove `cadir/mint/alex.pub` and the delegates it | ||
| 486 | minted die on their next command; remove the person's keys and their | ||
| 487 | delegates die with them. The cert's own expiry does the rest — there is no | ||
| 488 | revocation list to maintain. | ||
| 489 | |||
| 457 | ```text | 490 | ```text |
| 458 | @admins = alex | 491 | @admins = alex |
| 459 | @agents = claude-a claude-b | 492 | @agents = claude-a claude-b |