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
src/DodoSSH.Api/Features/Teams/VaultGrantService.cs
+206 -9
View File
@@ -152,6 +152,13 @@ internal sealed class VaultGrantService(
}
/// <summary>Lists who can open a vault.</summary>
/// <remarks>
/// One row per holder, not one per grant. A rotated vault holds several grants per member — one per
/// generation, which is what lets them read its history — and a listing that showed each of them
/// would answer "who can open this" with the same person three times. The row carries the best key
/// they hold: the live grant at the highest generation, or, for somebody whose access has been
/// withdrawn, the most recent grant they had, so the withdrawal is still visible.
/// </remarks>
internal async Task<VaultGrantsResponse> ListGrantsAsync(
Vault vault,
CancellationToken cancellationToken)
@@ -163,13 +170,25 @@ internal sealed class VaultGrantService(
.ToListAsync(cancellationToken)
.ConfigureAwait(false);
var holders = grants
.GroupBy(g => g.RecipientUserId!.Value)
.Select(group => group
.OrderByDescending(g => g.RevokedAtUtc is null)
.ThenByDescending(g => g.KeyGeneration)
.First())
// The order the first grant of each holder was made in, so the list reads as the vault was
// shared rather than reshuffling itself every time somebody is re-wrapped.
.OrderBy(g => grants.Find(first => first.RecipientUserId == g.RecipientUserId)!.CreatedAtUtc)
.ToList();
return new VaultGrantsResponse(
VaultId: vault.Id,
KeyGeneration: (uint)vault.KeyGeneration,
RekeyRequired: vault.RekeyRequired,
Grants:
[
.. grants.Select(g => new VaultGrantSummary(
.. holders.Select(g => new VaultGrantSummary(
g.RecipientUserId!.Value,
g.RecipientUser?.Email,
g.RecipientUser?.DisplayName,
@@ -183,10 +202,18 @@ internal sealed class VaultGrantService(
/// <summary>Wraps a vault key to another member.</summary>
/// <remarks>
/// Re-issuing to a recipient who already holds a live grant replaces it in place rather than
/// inserting a second row, because the unique index permits exactly one live grant per recipient
/// per generation — and because the operation somebody is actually performing when they do this
/// is "wrap it again", after a rotation or a botched first attempt.
/// <para>
/// Re-issuing to a recipient who already holds a live grant <em>for that generation</em> replaces it
/// in place rather than inserting a second row, because the unique index permits exactly one live
/// grant per recipient per generation — and because the operation somebody is actually performing
/// when they do this is "wrap it again", after a botched first attempt.
/// </para>
/// <para>
/// A recipient may hold one grant per generation at once, and after a rotation they need to: an item
/// is sealed under whatever generation was current when it was written, so somebody given only the
/// newest key would find everything older unreadable. Which generations get wrapped is the sharing
/// client's decision — it is the only party that can tell which ones it holds.
/// </para>
/// </remarks>
internal async Task IssueGrantAsync(
UserAccount actor,
@@ -199,10 +226,12 @@ internal sealed class VaultGrantService(
var granterKey = await RequireCurrentKeyAsync(actor.Id, cancellationToken)
.ConfigureAwait(false);
var generation = (int)request.KeyGeneration;
var existing = await database.VaultKeyGrants
.SingleOrDefaultAsync(
g => g.VaultId == vault.Id
&& g.KeyGeneration == vault.KeyGeneration
&& g.KeyGeneration == generation
&& g.RecipientUserId == request.RecipientUserId
&& g.RevokedAtUtc == null,
cancellationToken)
@@ -212,7 +241,7 @@ internal sealed class VaultGrantService(
{
Id = Guid.CreateVersion7(),
VaultId = vault.Id,
KeyGeneration = vault.KeyGeneration,
KeyGeneration = generation,
Kind = GrantKind.Member,
RecipientUserId = request.RecipientUserId,
CreatedAtUtc = clock.GetUtcNow(),
@@ -239,7 +268,7 @@ internal sealed class VaultGrantService(
await database.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
TeamLog.GrantIssued(
logger, vault.Id, vault.KeyGeneration, request.RecipientUserId, actor.Id);
logger, vault.Id, generation, request.RecipientUserId, actor.Id);
}
/// <summary>
@@ -270,7 +299,11 @@ internal sealed class VaultGrantService(
RequireDigest(request.RecipientKeyFingerprint, "recipient key fingerprint");
RequireDigest(request.KeyLogHead, "key log head");
if (request.KeyGeneration != (uint)vault.KeyGeneration)
// Any generation the vault has actually reached, not only the current one — sharing a rotated
// vault means handing over its history as well as its present. A generation ahead of the
// current one is refused: nothing is sealed under it, so the grant would open nothing, and
// accepting it would let a client move the vault forward without the transaction that does so.
if (request.KeyGeneration is 0 || request.KeyGeneration > (uint)vault.KeyGeneration)
{
throw new VaultGrantInvalidException(
$"This vault is at key generation {vault.KeyGeneration}. A grant for generation "
@@ -309,6 +342,170 @@ internal sealed class VaultGrantService(
}
}
/// <summary>
/// Moves a vault to a fresh key generation, wrapped to the caller.
/// </summary>
/// <returns>The vault as the caller now sees it, at the generation this call created.</returns>
/// <remarks>
/// <para>
/// <b>What the server contributes is the moment, not the key.</b> It cannot generate a vault key, tell
/// that the one it is handed differs from the old one, or check that the caller held the old one at
/// all. What it can do — and what nothing else can — is advance the generation exactly once, so two
/// admins rotating the same vault at the same time do not both walk away believing they succeeded.
/// The stale one's generation is no longer one past the current, and it is refused.
/// </para>
/// <para>
/// <b>Earlier grants are left standing.</b> They are what the remaining members read the vault's
/// history with: an item carries the generation it was sealed under, and nothing here re-encrypts
/// items — only a client holding both keys could. The departed member is cut off by the revocation
/// that removal already performed, which takes every generation they held.
/// </para>
/// <para>
/// The rekey flag is cleared here rather than when the last member is re-wrapped, because it records
/// that a membership change left the vault owing a rotation, and the rotation is this. Who still
/// needs the new key is a different question, and the grant list answers it by generation.
/// </para>
/// </remarks>
internal async Task<VaultSummary> RekeyAsync(
UserAccount actor,
Vault vault,
int permissions,
RekeyVaultRequest request,
CancellationToken cancellationToken)
{
var key = await RequireRotatableAsync(actor, vault, request, cancellationToken)
.ConfigureAwait(false);
var now = clock.GetUtcNow();
var generation = (int)request.KeyGeneration;
AddSelfGrant(actor, vault, key, generation, request, now);
vault.KeyGeneration = generation;
vault.RekeyRequired = false;
vault.RekeyReason = RekeyReason.None;
vault.UpdatedAtUtc = now;
try
{
// One SaveChanges, so the row and the grant land together. The vault's xmin concurrency
// token is what makes the generation check above binding rather than advisory: a second
// rotation that read the same generation fails here instead of overwriting this one.
await database.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
}
catch (DbUpdateConcurrencyException)
{
// Reported as the same refusal the pre-check gives, because it is the same situation seen a
// moment later — and a 500 about a concurrency token would tell the user nothing they could
// act on. Retrying is safe: the caller generates a fresh key and reads the generation again.
throw new VaultGrantInvalidException(
"Somebody else rotated this vault while this rotation was being recorded. Read it again "
+ "and rotate from the generation they left behind.");
}
TeamLog.VaultRekeyed(logger, vault.Id, generation, actor.Id);
var prior = await database.VaultKeyGrants
.Where(g => g.VaultId == vault.Id
&& g.RecipientUserId == actor.Id
&& g.KeyGeneration < generation
&& g.State == GrantState.Active
&& g.RevokedAtUtc == null)
.OrderBy(g => g.KeyGeneration)
.Select(g => new VaultKeyWrap((uint)g.KeyGeneration, g.WrappedKey))
.ToListAsync(cancellationToken)
.ConfigureAwait(false);
return new VaultSummary(
VaultId: vault.Id,
Name: vault.Name,
IsPersonal: false,
TeamId: vault.TeamId,
KeyGeneration: request.KeyGeneration,
Permissions: permissions,
WrappedVaultKey: request.WrappedVaultKey,
RekeyRequired: false,
PriorKeyWraps: prior);
}
/// <summary>Records the rotating client's grant for the generation it has just created.</summary>
private void AddSelfGrant(
UserAccount actor,
Vault vault,
UserKey key,
int generation,
RekeyVaultRequest request,
DateTimeOffset now) =>
database.VaultKeyGrants.Add(new VaultKeyGrant
{
Id = Guid.CreateVersion7(),
VaultId = vault.Id,
KeyGeneration = generation,
Kind = GrantKind.Member,
RecipientUserId = actor.Id,
RecipientKeyFingerprint = key.FingerprintSha256,
WrappedKey = request.WrappedVaultKey,
GranterUserId = actor.Id,
GranterKeyFingerprint = key.FingerprintSha256,
// No key log head, as every self-grant carries none: there is no third party whose key
// could have been substituted when you wrap something to yourself.
KeyLogHead = null,
Signature = request.GrantSignature,
State = GrantState.Active,
CreatedAtUtc = now,
});
/// <summary>
/// Everything that can be checked about a rotation before it is recorded.
/// </summary>
/// <returns>The caller's current identity key, which the new grant is filed against.</returns>
private async Task<UserKey> RequireRotatableAsync(
UserAccount actor,
Vault vault,
RekeyVaultRequest request,
CancellationToken cancellationToken)
{
if (vault.OwnerKind != VaultOwnerKind.Team || vault.TeamId is null)
{
throw new VaultGrantInvalidException(
"Only a team vault can be rotated. A personal vault has one reader, so a rotation "
+ "would re-wrap a key to the same person and change nothing about who can read it.");
}
RequireWrappedKey(request.WrappedVaultKey);
RequireSignature(request.GrantSignature);
if (request.KeyGeneration != (uint)vault.KeyGeneration + 1)
{
throw new VaultGrantInvalidException(
$"This vault is at key generation {vault.KeyGeneration}, so the next one is "
+ $"{vault.KeyGeneration + 1} and not {request.KeyGeneration}. Read the vault again — "
+ "somebody else has rotated it since you last looked.");
}
var key = await RequireCurrentKeyAsync(actor.Id, cancellationToken).ConfigureAwait(false);
// Held now, not merely permitted. The new key has to be wrapped from the old one, and an
// account that cannot open the current generation cannot have done that — so a request from
// one is either a mistake or an attempt to strand every other member behind a key nobody has.
var holdsCurrent = await database.VaultKeyGrants
.AnyAsync(
g => g.VaultId == vault.Id
&& g.KeyGeneration == vault.KeyGeneration
&& g.RecipientUserId == actor.Id
&& g.State == GrantState.Active
&& g.RevokedAtUtc == null,
cancellationToken)
.ConfigureAwait(false);
return holdsCurrent
? key
: throw new VaultGrantInvalidException(
"You hold no key to this vault at its current generation, so you cannot rotate it. Ask "
+ "a member who does.");
}
/// <summary>
/// Withdraws a member's key grant.
/// </summary>