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.Client.Sync.Tests/VaultKeyringTests.cs
+238
View File
@@ -0,0 +1,238 @@
using DodoSSH.Client.Domain;
using DodoSSH.Client.Storage;
using DodoSSH.Contracts;
using DodoSSH.Crypto;
namespace DodoSSH.Client.Sync.Tests;
/// <summary>
/// Holding more than one generation of a vault's key at once.
/// </summary>
/// <remarks>
/// A rotation does not re-encrypt what is already stored, so a rotated vault holds items sealed under
/// two or three different keys and every read has to choose the one the item names. These are the tests
/// that say so: the alternative — one key per vault — reads a rotated vault's whole history as corrupt,
/// which is a data-loss bug that looks exactly like a decryption failure.
/// </remarks>
public sealed class VaultKeyringTests : IDisposable
{
private static readonly Guid VaultId = Guid.Parse("0192f0c8-1111-7c3d-8e4f-5a6b7c8d9e0f");
private static readonly Guid HostId = Guid.Parse("0192f0c8-2222-7c3d-8e4f-5a6b7c8d9e0f");
private readonly UserSecretBundle bundle =
UserSecretBundle.Create(DateTimeOffset.FromUnixTimeSeconds(1_700_000_000));
/// <inheritdoc />
public void Dispose() => bundle.Dispose();
[Fact]
public void AVaultWithNoHistory_HoldsExactlyOneGeneration()
{
var (vault, _) = Rotated(currentGeneration: 1);
using var keyring = VaultKeyring.Open(bundle, [vault]);
keyring.GenerationsHeld(VaultId).ShouldBe([1u]);
keyring.CanRead(VaultId).ShouldBeTrue();
keyring.Unopened.ShouldBeEmpty();
}
[Fact]
public void ARotatedVault_OpensEveryGenerationItWasGranted()
{
var (vault, keys) = Rotated(currentGeneration: 3);
using var keyring = VaultKeyring.Open(bundle, [vault]);
keyring.GenerationsHeld(VaultId).ShouldBe([1u, 2u, 3u]);
foreach (var (generation, key) in keys)
{
keyring.TryGetAt(VaultId, generation, out var held).ShouldBeTrue();
held.ToArray().ShouldBe(key);
}
}
/// <remarks>
/// Writes go under the newest key, always. Sealing a new item under a superseded one would produce
/// an item that nobody who joined after the rotation can read, and the author would have no way to
/// tell — their own keyring still holds the old key.
/// </remarks>
[Fact]
public void TheCurrentGeneration_IsTheNewestOneAndNotTheOldest()
{
var (vault, keys) = Rotated(currentGeneration: 3);
using var keyring = VaultKeyring.Open(bundle, [vault]);
keyring.TryGet(VaultId, out var current, out var generation).ShouldBeTrue();
generation.ShouldBe(3u);
current.ToArray().ShouldBe(keys[3u]);
}
/// <remarks>
/// The state a member is left in between somebody rotating a vault and somebody wrapping the new key
/// to them. They can still read what was there — their old grants stand — and they must not be able
/// to write, because anything they wrote would be sealed under a key the vault has moved past.
/// </remarks>
[Fact]
public void AMemberAwaitingTheNewKey_ReadsTheHistoryAndCannotWrite()
{
var (vault, keys) = Rotated(currentGeneration: 2);
var awaiting = vault with { WrappedVaultKey = null };
using var keyring = VaultKeyring.Open(bundle, [awaiting]);
keyring.CanRead(VaultId).ShouldBeFalse();
keyring.TryGet(VaultId, out _, out _).ShouldBeFalse();
keyring.Unopened.ShouldBe([VaultId]);
keyring.TryGetAt(VaultId, 1, out var first).ShouldBeTrue();
first.ToArray().ShouldBe(keys[1u]);
}
/// <remarks>
/// What the rotating client itself does: it generates the next key, the server accepts it, and the
/// keyring takes it without losing the one the vault's existing items are sealed under.
/// </remarks>
[Fact]
public void AdoptingANewGeneration_KeepsTheOneBeforeIt()
{
var (vault, keys) = Rotated(currentGeneration: 1);
using var keyring = VaultKeyring.Open(bundle, [vault]);
var next = VaultKeys.Create();
keyring.Adopt(VaultId, next, keyGeneration: 2);
keyring.TryGet(VaultId, out _, out var generation).ShouldBeTrue();
generation.ShouldBe(2u);
keyring.GenerationsHeld(VaultId).ShouldBe([1u, 2u]);
keyring.TryGetAt(VaultId, 1, out var first).ShouldBeTrue();
first.ToArray().ShouldBe(keys[1u]);
}
/// <remarks>
/// The whole point, at the layer that pays for it: an item written before a rotation still opens
/// after one. Sealed and opened through the real cipher, so the AAD's generation binding is
/// exercised rather than assumed.
/// </remarks>
[Fact]
public void AnItemSealedBeforeARotation_StillOpensAfterIt()
{
var (vault, _) = Rotated(currentGeneration: 1);
using var keyring = VaultKeyring.Open(bundle, [vault]);
keyring.TryGet(VaultId, out var vaultKey, out var generation).ShouldBeTrue();
var host = new HostSecret { Label = "web-01", Hostname = "web-01.example", Username = "ops" };
var payload = HostCipher.Seal(host, vaultKey.Span, HostId, generation, itemVersion: 1);
keyring.Adopt(VaultId, VaultKeys.Create(), keyGeneration: 2);
// Chosen by the payload's own generation, which is what every read path does.
keyring.TryGetAt(VaultId, payload.KeyGeneration, out var itemKey).ShouldBeTrue();
HostCipher.TryOpen(payload, itemKey.Span, HostId, itemVersion: 1)
.ShouldNotBeNull()
.Host.Label.ShouldBe("web-01");
// And the current key does not open it, which is why holding only that one would be a loss.
keyring.TryGet(VaultId, out var newest, out _).ShouldBeTrue();
HostCipher.TryOpen(payload, newest.Span, HostId, itemVersion: 1).ShouldBeNull();
}
/// <remarks>
/// What another client rotating the vault looks like from here: the key this session holds is
/// suddenly the previous generation. It goes on opening what it wrote, and it must stop being the
/// one new items are sealed under — an item written under a superseded key is readable to its
/// author and to nobody else, with nothing to show that anything went wrong.
/// </remarks>
[Fact]
public void AVaultRotatedElsewhere_StopsBeingWritableAndStaysReadable()
{
var (vault, keys) = Rotated(currentGeneration: 1);
using var keyring = VaultKeyring.Open(bundle, [vault]);
keyring.CanRead(VaultId).ShouldBeTrue();
// What RefreshVaultsAsync does when the server reports a generation this session has no grant
// for: the admit fails, and the vault is marked unreadable.
keyring.MarkUnreadable(VaultId);
keyring.CanRead(VaultId).ShouldBeFalse();
keyring.TryGet(VaultId, out _, out _).ShouldBeFalse();
keyring.TryGetAt(VaultId, 1, out var first).ShouldBeTrue();
first.ToArray().ShouldBe(keys[1u]);
}
/// <remarks>
/// A wrap that will not open is one unusable grant, not a broken vault. Skipping it leaves the
/// generations that did open readable; refusing them all would take the whole vault down over one
/// bad row.
/// </remarks>
[Fact]
public void AnUnopenableHistoricWrap_IsSkippedRatherThanFatal()
{
var (vault, _) = Rotated(currentGeneration: 2);
var corrupted = vault with
{
PriorKeyWraps = [new VaultKeyWrap(1, new byte[110])],
};
using var keyring = VaultKeyring.Open(bundle, [corrupted]);
keyring.CanRead(VaultId).ShouldBeTrue();
keyring.GenerationsHeld(VaultId).ShouldBe([2u]);
keyring.TryGetAt(VaultId, 1, out _).ShouldBeFalse();
}
/// <summary>
/// A vault at <paramref name="currentGeneration"/>, with a distinct key wrapped for every generation
/// up to it.
/// </summary>
private (StoredVault Vault, Dictionary<uint, byte[]> Keys) Rotated(uint currentGeneration)
{
var keys = new Dictionary<uint, byte[]>();
var prior = new List<VaultKeyWrap>();
byte[]? current = null;
for (var generation = 1u; generation <= currentGeneration; generation++)
{
var key = VaultKeys.Create();
var wrapped = VaultKeys.WrapTo(key, bundle.EncryptionPublicKey, VaultId, generation);
keys[generation] = key;
if (generation == currentGeneration)
{
current = wrapped;
}
else
{
prior.Add(new VaultKeyWrap(generation, wrapped));
}
}
var vault = new StoredVault(
VaultId,
"Platform secrets",
IsPersonal: false,
TeamId: Guid.CreateVersion7(),
currentGeneration,
Permissions: 31,
current,
RekeyRequired: false,
prior);
return (vault, keys);
}
}