Add the encrypted local cache and the sync client

Three new client projects, and the wire-contract fix they needed. DodoSSH.Client.Domain holds the decrypted item model and the three-way merge, with no I/O at all — so the suite that decides whether a credential can be lost runs in milliseconds with nothing to mock. Scalars defer to the server on a genuine clash so every replica resolves the same triple identically and two clients cannot ping-pong; directives merge per name so two people each adding one both keep theirs; the jump chain merges as a whole value because its order is the route. Whatever loses is returned rather than dropped. DodoSSH.Client.Storage is EF Core on SQLite, no SQLCipher: the rows are already ciphertext, so an encrypted file would protect protected bytes at the cost of a native dependency. It keeps the server's state and the outbox in separate tables, which is what preserves the common ancestor a merge needs. One pending operation per item, enforced by a unique index. DodoSSH.Client.Sync is the pull/apply/push loop. Pulling never decrypts — a change with no local work pending is plumbed as ciphertext — so a first sync of thousands of items does not run twice as many AEAD operations for nothing. Contracts: EncryptedPayload gains WrappedDataKey and DataKeyId. The specification has required a per-item data key since crypto.md §3, the columns have existed since the first migration and DshAad.ItemPayload binds the id, but this record had nowhere to put either — so a spec-compliant item could not be transmitted at all. Found by writing the client that has to produce one. Also closes a hole in AadResourceType, which had no value for the HostTag and HostCredential that SyncEntityType has always listed. Four bugs the tests found, not review: - SQLite refuses to order or compare its own DateTimeOffset mapping, and throws at execution rather than model build. Collecting tombstones and listing conflicts are both that shape, so this was a crash waiting for the first user with a deleted host. Timestamps are integers now, by convention so a later field cannot be the one left unconverted. - SQLitePCLRaw 2.1.11, which EF resolves, is covered by GHSA-2m69-gcr7-jv3q. Pinned forward as a family. - Resurrecting content from a remote deletion cleared the original before queueing the copy. Two transactions, so a crash between them lost the work; reversed, and the rescued id is derived from the tombstone so a replay coalesces instead of duplicating. - Several equality assertions went through Shouldly's ShouldBe, which compares IEnumerable element-wise and so tested nothing about the Equals these types exist to provide. Corrected; the falsification that caught it went from 2 failures to 6. The push response's cursor is deliberately ignored. It sits after this client's own writes, so adopting it skips anything another client committed at a lower sequence in the window between a pull and a push — permanently. Re-reading one's own writes is idempotent and costs a page. The Contracts doc that invited the shortcut now says so. 593 tests, up from 448. The delete-versus-edit rules, the ancestor retention, the fresh operation id on coalesce and the cursor safeguard were each verified by breaking them and watching the right test fail.
2026-07-29 10:27:37 +02:00
1 parent a878c2b6bb
commit 8d2416a602
@@ -0,0 +1,196 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using DodoSSH.Client.Domain;
+
+namespace DodoSSH.Client.Sync;
+
+/// <summary>Tuning for a sync pass.</summary>
+/// <remarks>
+/// The push batch default is well below the server's own cap. A smaller batch means a conflict is
+/// discovered and merged sooner, and it bounds how much work one rejected batch delays.
+/// </remarks>
+public sealed record SyncOptions
+{
+    /// <summary>Changes requested per pull. The server clamps this.</summary>
+    public int PullPageSize { get; init; } = 500;
+
+    /// <summary>Operations sent per push. Must not exceed the server's advertised maximum.</summary>
+    public int MaxOperationsPerPush { get; init; } = 100;
+
+    /// <summary>
+    /// How many push rounds one pass may take.
+    /// </summary>
+    /// <remarks>
+    /// A bound rather than a loop until clear. Each round either applies, parks, or merges and advances
+    /// a version, so it does terminate — but against a vault someone else is writing to continuously it
+    /// could keep finding new conflicts, and a sync pass that never returns is worse than one that stops
+    /// and says so.
+    /// </remarks>
+    public int MaxPushRounds { get; init; } = 8;
+
+    /// <summary>
+    /// How many times an operation may be dispatched before it is parked for a person to look at.
+    /// </summary>
+    public int MaxAttemptsBeforeParking { get; init; } = 5;
+
+    /// <summary>
+    /// How many pages one pull may read.
+    /// </summary>
+    /// <remarks>
+    /// A backstop against a server that keeps saying there is more. At the default page size this is
+    /// half a million changes, well past any real vault, so reaching it means something is wrong rather
+    /// than merely large.
+    /// </remarks>
+    public int MaxPullPages { get; init; } = 1000;
+
+    /// <summary>The defaults.</summary>
+    public static SyncOptions Default { get; } = new();
+}
+
+/// <summary>What one sync pass did.</summary>
+/// <param name="VaultId">The vault.</param>
+/// <param name="Pulled">Changes received.</param>
+/// <param name="Pushed">Operations the server accepted.</param>
+/// <param name="Merged">Items where local and remote edits were reconciled.</param>
+/// <param name="Resurrected">
+/// Items someone else deleted while this machine had unpushed edits. The tombstone stands and the local
+/// content survives under a new id; nothing is discarded.
+/// </param>
+/// <param name="DeletesAbandoned">
+/// Local deletions dropped because the other side edited the item instead. An edit outlives a removal:
+/// re-deleting costs a click, and a discarded edit may be irrecoverable.
+/// </param>
+/// <param name="Parked">Operations the server refused, now waiting on a person.</param>
+/// <param name="Unreadable">Items whose payload would not decrypt.</param>
+/// <param name="ServerKeyGeneration">The generation the server reports for this vault.</param>
+/// <param name="RekeyRequired">
+/// True when the server's generation is ahead of the key this client holds, so items cannot be read
+/// until new grants arrive.
+/// </param>
+/// <param name="ServerTimeSkewMs">
+/// Difference between the server's clock and this machine's. Recorded, never acted on — the merge uses
+/// versions and a retained ancestor, so a skewed clock must not be able to decide which edit wins.
+/// </param>
+/// <param name="RoundsExhausted">
+/// True when the push loop hit <see cref="SyncOptions.MaxPushRounds"/> with work still outstanding. Not
+/// a failure: the next pass continues from here.
+/// </param>
+public sealed record SyncReport(
+    Guid VaultId,
+    int Pulled,
+    int Pushed,
+    int Merged,
+    int Resurrected,
+    int DeletesAbandoned,
+    int Parked,
+    int Unreadable,
+    uint ServerKeyGeneration,
+    bool RekeyRequired,
+    long ServerTimeSkewMs,
+    bool RoundsExhausted)
+{
+    /// <summary>Whether anything happened that a user should be told about.</summary>
+    public bool NeedsAttention =>
+        Resurrected > 0 || DeletesAbandoned > 0 || Parked > 0 || Unreadable > 0 || RekeyRequired;
+}
+
+/// <summary>Accumulates a <see cref="SyncReport"/> while a pass runs.</summary>
+internal sealed class SyncReportBuilder(Guid vaultId)
+{
+    internal int Pulled { get; set; }
+
+    internal int Pushed { get; set; }
+
+    internal int Merged { get; set; }
+
+    internal int Resurrected { get; set; }
+
+    internal int DeletesAbandoned { get; set; }
+
+    internal int Parked { get; set; }
+
+    internal int Unreadable { get; set; }
+
+    internal uint ServerKeyGeneration { get; set; }
+
+    internal bool RekeyRequired { get; set; }
+
+    internal long ServerTimeSkewMs { get; set; }
+
+    internal bool RoundsExhausted { get; set; }
+
+    internal SyncReport Build() =>
+        new(
+            vaultId,
+            Pulled,
+            Pushed,
+            Merged,
+            Resurrected,
+            DeletesAbandoned,
+            Parked,
+            Unreadable,
+            ServerKeyGeneration,
+            RekeyRequired,
+            ServerTimeSkewMs,
+            RoundsExhausted);
+}
+
+/// <summary>The record written to the conflict log when a merge had to override something.</summary>
+/// <param name="Field">Which field, as a path.</param>
+/// <param name="DiscardedSide">Whose intent was overridden: <c>Local</c> or <c>Remote</c>.</param>
+/// <param name="Kept">The value that survives.</param>
+/// <param name="Discarded">The value that lost.</param>
+/// <param name="DiscardedWasRemoval">Whether what lost was a deletion rather than a value.</param>
+public sealed record ConflictDetailEntry(
+    string Field,
+    string DiscardedSide,
+    string? Kept,
+    string? Discarded,
+    bool DiscardedWasRemoval);
+
+/// <summary>A conflict log entry.</summary>
+/// <param name="Summary">One line for a person to read.</param>
+/// <param name="Fields">Everything the merge overrode.</param>
+public sealed record ConflictDetail(string Summary, IReadOnlyList<ConflictDetailEntry> Fields);
+
+/// <summary>
+/// Serialises what a merge discarded, for the conflict log.
+/// </summary>
+/// <remarks>
+/// The bytes crossing into <c>ConflictStore</c> are plaintext vault content and are sealed there under
+/// the LocalCacheKey. Deliberately its own format rather than the item payload's: this is local
+/// bookkeeping and is never pushed, so it has no compatibility obligation to any other client.
+/// </remarks>
+internal static class ConflictDetailCodec
+{
+    internal static byte[] Encode(string summary, IReadOnlyList<HostFieldConflict> conflicts) =>
+        JsonSerializer.SerializeToUtf8Bytes(
+            new ConflictDetail(
+                summary,
+                [.. conflicts.Select(c => new ConflictDetailEntry(
+                    c.Field,
+                    c.DiscardedSide.ToString(),
+                    c.Kept,
+                    c.Discarded,
+                    c.DiscardedWasRemoval))]),
+            ConflictJsonContext.Default.ConflictDetail);
+
+    internal static byte[] Encode(string summary) => Encode(summary, []);
+
+    /// <summary>Reads a detail back, for display.</summary>
+    internal static ConflictDetail? TryDecode(ReadOnlySpan<byte> utf8)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize(utf8, ConflictJsonContext.Default.ConflictDetail);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+}
+
+[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
+[JsonSerializable(typeof(ConflictDetail))]
+internal sealed partial class ConflictJsonContext : JsonSerializerContext;