Move the keys when a membership changes, not just the flag

Adding somebody to a team granted them nothing readable and removing them
rotated nothing. Both were honest — the interface said so in as many words — and
both left the actual work to a button somebody had to remember to press, on a
machine that happened to hold the key. Adding now wraps every team vault this
machine can open to the new member, and removing revokes their grants and moves
each of those vaults to a fresh key that goes to whoever is left.

The rotation is where the design had to be decided rather than written. A vault
key is per generation and an item carries the generation it was sealed under, so
advancing the vault and withdrawing the old grants would make everything already
stored unreadable to everybody, including whoever pressed the button. So earlier
grants are kept: a member holds one per generation, /me serves them as
PriorKeyWraps, and VaultKeyring holds a key per generation — the newest for
writing, the item's own for reading, chosen per item on every read path. Sharing
issues one grant per generation held, because a recipient handed only the current
key would open the vault to find most of it undecryptable; revocation takes every
generation, because leaving the history behind leaves them able to read
everything written before the rotation.

The bump itself is one server transaction. POST /vaults/{id}/rekey must name
exactly current + 1 and the vault's xmin token makes that binding, so two admins
rotating at once do not both walk away believing they succeeded — the second is
refused and told to read the vault again. The server contributes the moment and
no cryptography: it cannot generate the key, cannot tell that the one it is
handed differs from the old one, and checks that the caller held the old one the
only way it can, by requiring a live grant at the current generation.

What this does not do is re-encrypt what is already stored, and the product says
so rather than the reassuring version: everything written from the rotation
onwards is unreadable to the person who left, and nothing about the past changes.
That half is deferred and is safe to add incrementally precisely because a vault
at mixed generations stays readable. ADR 0010 records the alternatives — revoking
the old grants, chaining each key under its successor, re-sealing every item in
one request against a server that caps a push at 500 operations — and why each
was rejected.

Two things fell out of the change rather than being asked for. The grant listing
would have shown a member once per generation, so it now returns one row per
holder carrying the best key they hold, which is what makes a row below the
vault's generation mean "still owed the new key". And MarkUnreadable gives up the
write target as well as reporting: a client whose vault was rotated elsewhere
would otherwise have gone on sealing items under its superseded key — readable to
its author, unreadable to everybody else, with nothing to show for it.
This commit is contained in:
2026-08-03 23:05:40 +02:00
parent e82a25c912
commit d5b1a73182
35 changed files with 2838 additions and 173 deletions
+37 -1
View File
@@ -404,6 +404,37 @@ public sealed record IssueVaultGrantRequest(
byte[] GrantSignature,
DateTimeOffset GrantedAt);
/// <summary>
/// Moves a vault to a fresh key, wrapped to the caller.
/// </summary>
/// <remarks>
/// <para>
/// The new key is generated by a client that already holds the current one, and arrives sealed to that
/// same client — the server can neither produce it nor tell that it differs from the old one. What the
/// server does is decide the moment it takes effect: the generation advances in one transaction, so
/// there is no instant at which two clients disagree about which generation is current.
/// </para>
/// <para>
/// <b>Grants for earlier generations are kept, not revoked.</b> Every item still carries the generation
/// it was sealed under, so withdrawing them would make the vault's whole history unreadable to the
/// people who are still in it. The departed member's grants are revoked — that is what
/// <c>RevokeGrantAsync</c> and removal from the team already do — and this is what stops them reading
/// anything written from here on. It does not reach back; see ADR 0001.
/// </para>
/// </remarks>
/// <param name="KeyGeneration">
/// The generation being created. Must be exactly one past the vault's current one, so two clients
/// rotating at once cannot both believe they succeeded.
/// </param>
/// <param name="WrappedVaultKey">The new vault key, sealed to the caller's own encryption key.</param>
/// <param name="GrantSignature">Ed25519 signature over the canonical grant tuple.</param>
/// <param name="GrantedAt">Signing timestamp, part of the signed tuple.</param>
public sealed record RekeyVaultRequest(
uint KeyGeneration,
byte[] WrappedVaultKey,
byte[] GrantSignature,
DateTimeOffset GrantedAt);
/// <summary>One vault key grant, as the sharing interface sees it.</summary>
/// <remarks>
/// The wrapped key itself is deliberately not here. A member reads their own through
@@ -436,7 +467,12 @@ public sealed record VaultGrantSummary(
/// compares against rather than inferring from <see cref="VaultGrantSummary.State"/> alone.
/// </param>
/// <param name="RekeyRequired">Whether a membership change has left this vault needing a rekey.</param>
/// <param name="Grants">Every grant, including revoked ones.</param>
/// <param name="Grants">
/// One row per holder, including those whose access has been withdrawn. Not one per grant: a rotated
/// vault leaves a member holding one grant per generation, and the row carries the best of them — so
/// <see cref="VaultGrantSummary.KeyGeneration"/> below <paramref name="KeyGeneration"/> means they have
/// not been wrapped the current key yet, rather than that one of their grants is old.
/// </param>
public sealed record VaultGrantsResponse(
Guid VaultId,
uint KeyGeneration,