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.

src/DodoSSH.Client.Shell/ViewModels/TeamsViewModel.cs

@@ -607,33 +607,134 @@ internal sealed partial class TeamsViewModel(
 
             InviteEmail = string.Empty;
 
+            // Before the reload, so the vault list this screen redraws already shows what they can
+            // open. The sharing is what makes the membership worth anything, and doing it here rather
+            // than leaving a SHARE KEY button to be pressed is the difference between adding a
+            // colleague and adding a colleague who then waits for somebody to notice.
+            var shared = await ShareWithAsync(server, team, member, cancellationToken)
+                .ConfigureAwait(true);
+
             await ReloadAsync(cancellationToken).ConfigureAwait(true);
 
-            Status = Describe(member);
+            Status = Describe(member, shared);
         }).ConfigureAwait(true);
     }
 
+    /// <summary>
+    /// Wraps every team vault this machine can open to somebody who has just been added.
+    /// </summary>
+    /// <returns>What to tell the user about the keys, or null when there was nothing to say.</returns>
+    /// <remarks>
+    /// <para>
+    /// Skipped outright for an account with no identity key: there is nothing to wrap to, and a
+    /// refusal per vault would bury that one fact under a list. Their row says so, and adding them was
+    /// still worth doing.
+    /// </para>
+    /// <para>
+    /// A failure here is reported and never thrown. The membership has already been recorded on the
+    /// server and is not undone by a key that could not be wrapped — so the honest outcome is "they are
+    /// in the team, and this vault still needs sharing", which is a state somebody can act on.
+    /// </para>
+    /// </remarks>
+    private async Task<string?> ShareWithAsync(
+        IVaultServer server,
+        TeamRowViewModel team,
+        TeamMemberSummary member,
+        CancellationToken cancellationToken)
+    {
+        if (!member.IsEnrolled)
+        {
+            return null;
+        }
+
+        if (session() is not { } open)
+        {
+            // Distinguished from holding no keys, because the two lead somewhere different: this one is
+            // fixed by unlocking, and the other by asking somebody who holds the vault.
+            return "Nothing was shared with them — a vault key is wrapped on an unlocked machine, and "
+                + "this keychain is locked.";
+        }
+
+        var reports = await open
+            .ShareTeamVaultsAsync(
+                server.Grants, server.Directory, team.TeamId, member.UserId, cancellationToken)
+            .ConfigureAwait(true);
+
+        if (reports.Count == 0)
+        {
+            return null;
+        }
+
+        var shared = reports.Where(report => report.Succeeded).ToList();
+        var refused = reports.Where(report => !report.Succeeded).ToList();
+
+        var sentence = shared.Count > 0
+            ? $"Shared {VaultCount(shared.Count)} with them: {Join(shared.Select(r => r.Name))}."
+            : null;
+
+        if (refused.Count == 0)
+        {
+            return sentence;
+        }
+
+        // Named one by one rather than counted. Each of these is a vault somebody now expects them to
+        // be able to open, and which one it is decides who has to fix it.
+        var reasons = refused.Select(report =>
+            $"'{report.Name}' ({report.Failure?.Message ?? report.Outcome?.Message})");
+
+        return (sentence is null ? string.Empty : sentence + " ")
+            + $"Could not share {Join(reasons)}.";
+    }
+
     /// <summary>
     /// What just happened to the account that was added, and what is still owed them.
     /// </summary>
     /// <remarks>
-    /// Both branches say out loud that nothing readable was granted, because the single most common
-    /// misunderstanding this design invites is that adding somebody gave them the vault. The unenrolled
-    /// branch says more, and has to: their row will sit in the list saying it holds no key, and without
-    /// this somebody would read that as the addition having half-failed rather than as a colleague who
-    /// has not finished setting their machine up. It is also the one case where SHARE KEY cannot be the
-    /// next step, so pointing at it would be pointing at a button that will refuse.
+    /// <para>
+    /// The enrolled branch reports what the keys did, because that is the half of "adding somebody"
+    /// that this machine performs and the half that can partly fail. A vault that could not be wrapped
+    /// is named there rather than left to be noticed when they say they cannot open it.
+    /// </para>
+    /// <para>
+    /// The unenrolled branch says more, and has to: their row will sit in the list saying it holds no
+    /// key, and without this somebody would read that as the addition having half-failed rather than as
+    /// a colleague who has not finished setting their machine up. Nothing was shared with them and
+    /// nothing could have been — there is no key to wrap to — so the membership is all there is yet.
+    /// </para>
     /// </remarks>
-    private static string Describe(TeamMemberSummary member)
+    private static string Describe(TeamMemberSummary member, string? shared)
     {
         var who = member.Email ?? member.DisplayName ?? "the account";
 
-        return member.IsEnrolled
-            ? $"Added {who} as a member. They cannot read anything yet — select a vault below and "
-                + "share its key."
-            : $"Added {who} as a member. They have no key yet, so their row says so and no vault can "
-                + "be shared with them until they finish signing in on their own machine. The "
+        if (!member.IsEnrolled)
+        {
+            return $"Added {who} as a member. They have no key yet, so their row says so and no vault "
+                + "can be shared with them until they finish signing in on their own machine. The "
                 + "membership is real in the meantime.";
+        }
+
+        return shared is null
+            ? $"Added {who} as a member. This machine holds no team vault key to give them — select a "
+                + "vault below and press SHARE KEY from one that does."
+            : $"Added {who} as a member. {shared}";
+    }
+
+    /// <summary>"1 vault" or "3 vaults", for a sentence that has to read either way.</summary>
+    private static string VaultCount(int count) =>
+        string.Create(CultureInfo.CurrentCulture, $"{count} vault{(count == 1 ? string.Empty : "s")}");
+
+    /// <summary>Joins names into a phrase a person would say, rather than a comma-separated list.</summary>
+    private static string Join(IEnumerable<string> parts)
+    {
+        var list = parts.ToList();
+
+        return list.Count switch
+        {
+            0 => string.Empty,
+            1 => list[0],
+            2 => $"{list[0]} and {list[1]}",
+            _ => string.Join(", ", list.Take(list.Count - 1)) + " and " + list[^1],
+        };
     }
 
     /// <summary>
@@ -917,7 +1018,14 @@ internal sealed partial class TeamsViewModel(
         }).ConfigureAwait(true);
     }
 
-    /// <summary>Removes a member, revoking every vault key grant they hold from this team.</summary>
+    /// <summary>
+    /// Removes a member, revoking their grants and rotating the vaults they could read.
+    /// </summary>
+    /// <remarks>
+    /// The removal and the rotation are separate acts and only the first is the server's. Nothing here
+    /// undoes the removal if the rotation fails, and nothing waits for it: the membership change is what
+    /// stops them fetching anything more, and it has already happened by then.
+    /// </remarks>
     [RelayCommand]
     private async Task RemoveMemberAsync(CancellationToken cancellationToken)
     {
@@ -928,22 +1036,110 @@ internal sealed partial class TeamsViewModel(
             return;
         }
 
+        // Read before the removal, because afterwards this list no longer contains them — and it is the
+        // list of who the new key goes to.
+        var remaining = Members
+            .Where(row => row.UserId != member.UserId)
+            .Select(row => row.UserId)
+            .ToList();
+
         await RunAsync(async () =>
         {
             await server.Teams
                 .RemoveTeamMemberAsync(team.TeamId, member.UserId, cancellationToken)
                 .ConfigureAwait(true);
 
+            var rotated = await RotateAfterRemovalAsync(server, team, remaining, cancellationToken)
+                .ConfigureAwait(true);
+
             await ReloadAsync(cancellationToken).ConfigureAwait(true);
 
             // The honest sentence, not the reassuring one. See ADR 0001: revocation is not retroactive,
-            // and a message implying otherwise is the one thing this screen must not say.
-            Status = $"Removed {member.Name}. They can no longer fetch this team's vaults, and anything "
-                + "they had already downloaded is still on their machine — rotate the credentials that "
-                + "matter.";
+            // and a message implying otherwise is the one thing this screen must not say. The rotation
+            // is described in the same breath for the same reason — it decides what happens next, not
+            // what already happened.
+            Status = $"Removed {member.Name}. {rotated} Anything they had already downloaded is still "
+                + "on their machine — rotate the credentials that matter.";
         }).ConfigureAwait(true);
     }
 
+    /// <summary>
+    /// Rotates every team vault this machine can open, handing each new key to the members who remain.
+    /// </summary>
+    /// <returns>What to tell the user about the keys. Never null — something always happened.</returns>
+    /// <remarks>
+    /// A vault this machine cannot open is not rotated and is not counted as a failure here: its key
+    /// belongs to somebody else, the server has flagged it as owing a rekey, and the vault row says so
+    /// until one of them does it.
+    /// </remarks>
+    private async Task<string> RotateAfterRemovalAsync(
+        IVaultServer server,
+        TeamRowViewModel team,
+        IReadOnlyList<Guid> remaining,
+        CancellationToken cancellationToken)
+    {
+        if (session() is not { } open)
+        {
+            return "Their key grants are withdrawn, so they can fetch nothing more. Unlock your "
+                + "keychain to rotate the vault keys themselves.";
+        }
+
+        var reports = await open
+            .RekeyTeamVaultsAsync(
+                server.Grants, server.Directory, team.TeamId, remaining, cancellationToken)
+            .ConfigureAwait(true);
+
+        if (reports.Count == 0)
+        {
+            return "Their key grants are withdrawn, so they can fetch nothing more. This machine holds "
+                + "no key to any of this team's vaults, so there was nothing here to rotate.";
+        }
+
+        var rotated = reports.Where(report => report.Rotated).ToList();
+        var failed = reports.Where(report => !report.Rotated).ToList();
+
+        var sentences = new List<string>();
+
+        if (rotated.Count > 0)
+        {
+            // Says what a rotation is and is not worth, because the word promises more than it can
+            // deliver: from here on they cannot read this vault, and what is already in it was sealed
+            // under the key they used to hold.
+            sentences.Add(
+                $"Rotated {VaultCount(rotated.Count)} — {Join(rotated.Select(r => r.Name))} — so nothing "
+                + "written from now on is readable to them.");
+
+            // The members who did not get the new key. They are still in the team and can still write,
+            // but until somebody wraps it to them they will find the vault stops updating.
+            // Distinct by id rather than by name, because two accounts can share a display name and
+            // collapsing them would tell somebody one person is owed a key when two are.
+            var missed = rotated
+                .SelectMany(report => report.NotShared.Select(entry => entry.UserId))
+                .Distinct()
+                .Select(Name)
+                .ToList();
+
+            if (missed.Count > 0)
+            {
+                sentences.Add(
+                    $"The new key did not reach {Join(missed)} — press SHARE KEY for them, or they "
+                    + "will stop seeing changes.");
+            }
+        }
+
+        if (failed.Count > 0)
+        {
+            sentences.Add(
+                $"Could not rotate {Join(failed.Select(r => $"'{r.Name}' ({r.Failure?.Message})"))}.");
+        }
+
+        return string.Join(" ", sentences);
+    }
+
+    /// <summary>What to call a member in a sentence, from the list this screen already has.</summary>
+    private string Name(Guid userId) =>
+        Members.FirstOrDefault(row => row.UserId == userId)?.Name ?? userId.ToString();
+
     /// <summary>Opens the name-a-vault form, aimed at the selected team.</summary>
     [RelayCommand]
     private void NewVault() => ArmNewVault(SelectedTeam?.TeamId);
@@ -1196,8 +1392,16 @@ internal sealed partial class TeamsViewModel(
                 .ShareVaultAsync(server.Grants, server.Directory, vault.VaultId, member.UserId, cancellationToken)
                 .ConfigureAwait(true);
 
+            // The generation count is said out loud when there is more than one, because it is the
+            // answer to a question somebody will have about a rotated vault: whether the person they
+            // just shared it with can see what was in it before the rotation.
+            var history = outcome.Generations > 1
+                ? $" All {outcome.Generations} generations of the key were wrapped, so they can read "
+                    + "what was in the vault before it was last rotated."
+                : string.Empty;
+
             Status = outcome.Shared
-                ? $"Shared '{vault.Name}' with {member.Name}. {outcome.Message}"
+                ? $"Shared '{vault.Name}' with {member.Name}. {outcome.Message}{history}"
                 : $"Did not share '{vault.Name}': {outcome.Message}";
         }).ConfigureAwait(true);
     }

src/DodoSSH.Client.Shell/ViewModels/VaultViewModel.cs

@@ -7025,7 +7025,12 @@ internal sealed partial class VaultViewModel(
 
         if (report.RekeyRequired)
         {
-            notes.Add("this keychain was rekeyed and your access needs re-issuing");
+            // What is readable and what is not, because the two differ and the difference is the whole
+            // of what somebody in this state needs to know: the keys they hold still open everything
+            // written before the rotation, and nothing written since.
+            notes.Add(
+                "this keychain was rekeyed — you can still read what was here, and need the new key "
+                + "before you can see anything written since");
         }
 
         return replayed + "Synchronised, but: " + string.Join("; ", notes) + ".";