DodoTech-Public/DodoSSH
Public Access
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

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

Browse Source 
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:
jaap-jan
2026-08-03 23:05:40 +02:00
parent e82a25c912
commit d5b1a73182
35 changed files with 2838 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/DodoSSH.Api.Tests/EndpointInventoryTests.cs
+4
View File
@@ -103,6 +103,10 @@ public sealed class EndpointInventoryTests(ApiFixture fixture)
"POST /api/v1/vaults/{vaultId:guid}/grants name=IssueVaultGrant tags=Vaults policies=Enrolled anon=False",
"DELETE /api/v1/vaults/{vaultId:guid}/grants/{userId:guid} name=RevokeVaultGrant tags=Vaults policies=Enrolled anon=False",
// Gated on Share inside the handler as the two writes above are, and additionally on holding the
// current key — which no policy could express, since it is a row in vault_key_grant.
"POST /api/v1/vaults/{vaultId:guid}/rekey name=RekeyVault tags=Vaults policies=Enrolled anon=False",
// Anonymous on purpose, and load-bearing: DodoSSH.SystemTests waits on /healthz/ready before any
// token exists, and an orchestrator probe that needs credentials reports the wrong thing.
// MapHealthChecks constrains no verb, hence ANY.
tests/DodoSSH.Api.Tests/TeamEndpointTests.cs
+226
View File
@@ -999,6 +999,198 @@ public sealed class TeamEndpointTests(ApiFixture fixture)
response.StatusCode.ShouldBe(HttpStatusCode.BadRequest);
}
/// <remarks>
/// The rotation itself: the generation advances, the caller holds the new key, and the flag a
/// removal set is cleared because the rotation it recorded has happened. What the server cannot do
/// is any part of the cryptography — the wrap arrives sealed and is stored as bytes.
/// </remarks>
[Fact]
public async Task RekeyingAVault_AdvancesTheGenerationAndWrapsItToTheCaller()
{
var owner = await EnrolledClientAsync("rotate-owner", "rotowner@example.com");
await EnrolledClientAsync("rotate-member", "rotmember@example.com");
var team = await CreateTeamAsync(owner, "Rotations");
var vaultId = await CreateVaultAsync(owner, team.TeamId);
var entry = await LookupAsync(owner, "rotmember@example.com");
await AddMemberAsync(owner, team.TeamId, entry.UserId, TeamMemberRole.Member);
await DeleteAsync(owner, MemberUrl(team.TeamId, entry.UserId));
var rotated = await RekeyAsync(owner, vaultId, generation: 2);
rotated.KeyGeneration.ShouldBe(2u);
rotated.RekeyRequired.ShouldBeFalse();
var grants = await ReadAsync<VaultGrantsResponse>(owner, $"/api/v1/vaults/{vaultId}/grants");
grants.KeyGeneration.ShouldBe(2u);
grants.RekeyRequired.ShouldBeFalse();
var me = await ReadAsync<MeResponse>(owner, MeUrl);
var summary = me.Vaults.Single(vault => vault.VaultId == vaultId);
summary.KeyGeneration.ShouldBe(2u);
summary.WrappedVaultKey.ShouldNotBeNull();
}
/// <remarks>
/// The reason a rotation does not have to re-encrypt anything to be safe, and the reason it cannot
/// throw the old grants away: every item still carries the generation it was sealed under, so the
/// caller has to go on holding every key they were given or the vault's history becomes unreadable
/// to the people who are still in the team.
/// </remarks>
[Fact]
public async Task ARotatedVault_StillServesTheCallerTheGenerationsItHasMovedPast()
{
var owner = await EnrolledClientAsync("history-owner", "histowner@example.com");
var team = await CreateTeamAsync(owner, "History");
var vaultId = await CreateVaultAsync(owner, team.TeamId);
await RekeyAsync(owner, vaultId, generation: 2);
await RekeyAsync(owner, vaultId, generation: 3);
var me = await ReadAsync<MeResponse>(owner, MeUrl);
var summary = me.Vaults.Single(vault => vault.VaultId == vaultId);
summary.KeyGeneration.ShouldBe(3u);
summary.PriorKeyWraps.ShouldNotBeNull();
summary.PriorKeyWraps.Select(wrap => wrap.KeyGeneration).ShouldBe([1u, 2u]);
}
/// <remarks>
/// The sharing list answers "who can open this", so a member appears once however many generations
/// they hold — and the generation on their row is the best key they have, which is what makes a row
/// below the vault's own generation mean "still owed the new key".
/// </remarks>
[Fact]
public async Task TheGrantListing_ShowsAMemberOnceWithTheBestKeyTheyHold()
{
var owner = await EnrolledClientAsync("listing-owner", "listowner@example.com");
await EnrolledClientAsync("listing-member", "listmember@example.com");
var team = await CreateTeamAsync(owner, "Listings");
var vaultId = await CreateVaultAsync(owner, team.TeamId);
var entry = await LookupAsync(owner, "listmember@example.com");
await AddMemberAsync(owner, team.TeamId, entry.UserId, TeamMemberRole.Member);
var issued = await owner.PostContractAsync(
$"/api/v1/vaults/{vaultId}/grants", GrantRequest(entry, generation: 1));
issued.EnsureSuccessStatusCode();
await RekeyAsync(owner, vaultId, generation: 2);
var grants = await ReadAsync<VaultGrantsResponse>(owner, $"/api/v1/vaults/{vaultId}/grants");
grants.KeyGeneration.ShouldBe(2u);
grants.Grants.Count.ShouldBe(2);
// The rotating owner holds both generations and is listed at the newer one.
grants.Grants.Single(g => g.RecipientUserId != entry.UserId).KeyGeneration.ShouldBe(2u);
// The member has not been re-wrapped, so their row says so by generation rather than by state.
var stale = grants.Grants.Single(g => g.RecipientUserId == entry.UserId);
stale.KeyGeneration.ShouldBe(1u);
stale.State.ShouldBe(VaultGrantState.Active);
}
/// <remarks>
/// Two admins rotating at once must not both succeed, or one of them ends up holding a key nobody
/// else has and every item they write is unreadable to the rest of the team. The generation is what
/// makes that decidable: the second request is no longer one past the current, and is refused with a
/// message that says to read the vault again.
/// </remarks>
[Fact]
public async Task ARekeyFromASupersededGeneration_IsRefused()
{
var owner = await EnrolledClientAsync("race-owner", "raceowner@example.com");
var team = await CreateTeamAsync(owner, "Races");
var vaultId = await CreateVaultAsync(owner, team.TeamId);
await RekeyAsync(owner, vaultId, generation: 2);
var stale = await owner.PostContractAsync(
$"/api/v1/vaults/{vaultId}/rekey", RekeyRequest(generation: 2));
await ShouldBeProblemAsync(stale, HttpStatusCode.BadRequest, ProblemCodes.InvalidVaultGrant);
}
/// <remarks>
/// A member with no key to the current generation cannot rotate. They could not have wrapped the
/// new key from the old one, so the request is either a mistake or a way to strand everybody else
/// behind a key nobody holds.
/// </remarks>
[Fact]
public async Task ARekeyByAMemberWhoHoldsNoKey_IsRefused()
{
var owner = await EnrolledClientAsync("keyless-owner", "klowner@example.com");
var member = await EnrolledClientAsync("keyless-member", "klmember@example.com");
var team = await CreateTeamAsync(owner, "Keyless");
var vaultId = await CreateVaultAsync(owner, team.TeamId);
var entry = await LookupAsync(owner, "klmember@example.com");
// Admin, so permission is not what stops them: what stops them is holding no key.
await AddMemberAsync(owner, team.TeamId, entry.UserId, TeamMemberRole.Admin);
var response = await member.PostContractAsync(
$"/api/v1/vaults/{vaultId}/rekey", RekeyRequest(generation: 2));
await ShouldBeProblemAsync(response, HttpStatusCode.BadRequest, ProblemCodes.InvalidVaultGrant);
}
/// <remarks>
/// Sharing a rotated vault means handing over its history too, so a grant for a generation the vault
/// has moved past is accepted. One for a generation it has not reached is not: nothing is sealed
/// under it, and accepting it would let a client move the vault forward outside the one transaction
/// that is allowed to.
/// </remarks>
[Fact]
public async Task AGrantForAnEarlierGeneration_IsAcceptedAndOneForALaterOneIsNot()
{
var owner = await EnrolledClientAsync("gen-owner", "genowner@example.com");
var member = await EnrolledClientAsync("gen-member", "genmember@example.com");
var team = await CreateTeamAsync(owner, "Generations");
var vaultId = await CreateVaultAsync(owner, team.TeamId);
var entry = await LookupAsync(owner, "genmember@example.com");
await AddMemberAsync(owner, team.TeamId, entry.UserId, TeamMemberRole.Member);
await RekeyAsync(owner, vaultId, generation: 2);
foreach (var generation in (uint[])[1, 2])
{
var accepted = await owner.PostContractAsync(
$"/api/v1/vaults/{vaultId}/grants", GrantRequest(entry, generation));
accepted.StatusCode.ShouldBe(HttpStatusCode.NoContent);
}
var ahead = await owner.PostContractAsync(
$"/api/v1/vaults/{vaultId}/grants", GrantRequest(entry, generation: 3));
await ShouldBeProblemAsync(ahead, HttpStatusCode.BadRequest, ProblemCodes.InvalidVaultGrant);
// Both grants are live at once, which is what lets the recipient read the vault's history and
// its present. A single row per recipient would have made one of them overwrite the other.
var me = await ReadAsync<MeResponse>(member, MeUrl);
var summary = me.Vaults.Single(vault => vault.VaultId == vaultId);
summary.KeyGeneration.ShouldBe(2u);
summary.PriorKeyWraps.ShouldNotBeNull().ShouldHaveSingleItem().KeyGeneration.ShouldBe(1u);
}
// ---- The directory and the key log ----
/// <remarks>
@@ -1171,6 +1363,40 @@ public sealed class TeamEndpointTests(ApiFixture fixture)
return vault.VaultId;
}
/// <remarks>
/// The wrap is the right shape and nothing more, for the reason <see cref="CreateVaultAsync"/> gives:
/// the server stores it opaquely, so a real seal here would be exercising the crypto library.
/// </remarks>
private static RekeyVaultRequest RekeyRequest(uint generation) =>
new(
KeyGeneration: generation,
WrappedVaultKey: new byte[110],
GrantSignature: new byte[64],
GrantedAt: DateTimeOffset.UnixEpoch);
private static IssueVaultGrantRequest GrantRequest(DirectoryEntry entry, uint generation) =>
new(
entry.UserId,
entry.Fingerprint,
KeyGeneration: generation,
WrappedVaultKey: new byte[110],
KeyLogHead: new byte[32],
GrantSignature: new byte[64],
GrantedAt: DateTimeOffset.UnixEpoch);
private static async Task<VaultSummary> RekeyAsync(
HttpClient client,
Guid vaultId,
uint generation)
{
var response = await client.PostContractAsync(
$"/api/v1/vaults/{vaultId}/rekey", RekeyRequest(generation));
response.EnsureSuccessStatusCode();
return (await response.Content.ReadContractAsync<VaultSummary>())!;
}
private async Task<DirectoryEntry> LookupAsync(HttpClient client, string email)
{
var address = addresses.GetValueOrDefault(email, email);