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

Add the encrypted local cache and the sync client

Browse Source 
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.
This commit is contained in:
jaap-jan
2026-07-29 10:27:37 +02:00
parent a878c2b6bb
commit 8d2416a602
72 changed files with 11313 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/DodoSSH.Client.Storage.Tests/CacheStoreTests.cs
+401
View File
@@ -0,0 +1,401 @@
using DodoSSH.Contracts;
using DodoSSH.Crypto;
using Microsoft.EntityFrameworkCore;
using static DodoSSH.Client.Storage.Tests.CacheHarness;
namespace DodoSSH.Client.Storage.Tests;
/// <summary>
/// The item mirror, the vault list, the sync cursor, and the conflict log.
/// </summary>
public sealed class CacheStoreTests : IAsyncLifetime
{
private CacheHarness harness = null!;
/// <inheritdoc />
public async ValueTask InitializeAsync() => harness = await CreateAsync();
/// <inheritdoc />
public ValueTask DisposeAsync()
{
harness.Dispose();
return ValueTask.CompletedTask;
}
// ---- Items ----
[Fact]
public async Task AnItem_RoundTripsItsCiphertextByteForByte()
{
// Not "equivalent" — identical. The AAD binds the row, so re-encrypting locally would work but
// would throw away the ability to notice the server handing back bytes it should not have.
var entityId = Guid.CreateVersion7();
var item = Item(entityId, version: 4, changeSequence: 17, seed: 3);
await harness.Items.SaveAsync(item, Token);
var read = await harness.Items.FindAsync(VaultId, SyncEntityType.Host, entityId, Token);
read.ShouldNotBeNull();
read.Version.ShouldBe(4);
read.ChangeSequence.ShouldBe(17);
read.Payload.ShouldNotBeNull();
read.Payload.Envelope.ShouldBe(item.Payload!.Envelope);
read.Payload.WrappedDataKey.ShouldBe(item.Payload.WrappedDataKey);
read.Payload.DataKeyId.ShouldBe(item.Payload.DataKeyId);
read.Payload.KeyGeneration.ShouldBe(item.Payload.KeyGeneration);
read.Payload.AadVersion.ShouldBe(item.Payload.AadVersion);
}
[Fact]
public async Task ThePlaintextFields_RoundTripAndAreNotReadableInTheDatabase()
{
// The server has to hold a relay-enabled host's address in the clear because it resolves it.
// This machine already holds the key that opens the payload, so leaving the address readable in
// a file that ends up in a backup buys nothing.
var entityId = Guid.CreateVersion7();
var fields = new SyncPlaintextFields(
RelayEnabled: true, Hostname: "bastion.internal", Port: 2222);
await harness.Items.SaveAsync(Item(entityId, fields: fields), Token);
var read = await harness.Items.FindAsync(VaultId, SyncEntityType.Host, entityId, Token);
read!.Fields.ShouldBe(fields);
var stored = await ReadRawFieldsAsync(entityId);
stored.ShouldNotBeNull();
System.Text.Encoding.UTF8.GetString(stored)
.Contains("bastion.internal", StringComparison.Ordinal)
.ShouldBeFalse("the hostname is stored in the clear");
}
[Fact]
public async Task ACacheRecord_CannotBeMovedToAnotherRow()
{
// Why the record is bound to its own row rather than only to the user. Swapping two rows would
// otherwise point one host's connection at another host's address.
var mine = Guid.CreateVersion7();
var other = Guid.CreateVersion7();
var sealedFields = harness.Protector.Protect(
CryptoSpec.AadResourceType.Host,
mine,
PlaintextFieldsCodec.Encode(new SyncPlaintextFields(true, "mine.internal", 22)));
harness.Protector
.TryUnprotect(CryptoSpec.AadResourceType.Host, other, sealedFields)
.ShouldBeNull();
harness.Protector
.TryUnprotect(CryptoSpec.AadResourceType.Credential, mine, sealedFields)
.ShouldBeNull();
harness.Protector
.TryUnprotect(CryptoSpec.AadResourceType.Host, mine, sealedFields)
.ShouldNotBeNull();
}
[Fact]
public async Task ARecordSealedUnderAnotherPassphrase_DoesNotOpen()
{
var entityId = Guid.CreateVersion7();
using var stranger = await CreateAsync(passphrase: "a completely different passphrase");
var sealedFields = stranger.Protector.Protect(
CryptoSpec.AadResourceType.Host, entityId, [1, 2, 3]);
harness.Protector
.TryUnprotect(CryptoSpec.AadResourceType.Host, entityId, sealedFields)
.ShouldBeNull();
}
[Fact]
public async Task SavingTwice_ReplacesRatherThanDuplicates()
{
var entityId = Guid.CreateVersion7();
await harness.Items.SaveAsync(Item(entityId, version: 1, seed: 1), Token);
await harness.Items.SaveAsync(Item(entityId, version: 2, seed: 9), Token);
var items = await harness.Items.ListAsync(VaultId, SyncEntityType.Host, false, Token);
items.ShouldHaveSingleItem().Version.ShouldBe(2);
}
[Fact]
public async Task ATombstone_IsHiddenFromTheListButStillFindable()
{
// The interface must not show a deleted host. The sync engine must still be able to tell a
// deleted item from one it has never seen — a row that simply vanished is indistinguishable
// from the latter, and would silently reappear.
var entityId = Guid.CreateVersion7();
await harness.Items.SaveAsync(Item(entityId, version: 1), Token);
await harness.Items.SaveAsync(Item(entityId, version: 2, deleted: true), Token);
(await harness.Items.ListAsync(VaultId, SyncEntityType.Host, false, Token)).ShouldBeEmpty();
var withDeleted = await harness.Items.ListAsync(VaultId, SyncEntityType.Host, true, Token);
withDeleted.ShouldHaveSingleItem().IsDeleted.ShouldBeTrue();
var found = await harness.Items.FindAsync(VaultId, SyncEntityType.Host, entityId, Token);
found.ShouldNotBeNull();
found.IsDeleted.ShouldBeTrue();
found.Payload.ShouldBeNull();
}
[Fact]
public async Task CollectingTombstones_LeavesLiveItemsAlone()
{
var live = Guid.CreateVersion7();
var dead = Guid.CreateVersion7();
await harness.Items.SaveAsync(Item(live, changeSequence: 1), Token);
await harness.Items.SaveAsync(Item(dead, changeSequence: 2, deleted: true), Token);
var cutoff = DateTimeOffset.FromUnixTimeSeconds(1_750_000_100);
var collected = await harness.Items.CollectTombstonesAsync(VaultId, cutoff, Token);
collected.ShouldBe(1);
var remaining = await harness.Items.ListAsync(VaultId, SyncEntityType.Host, true, Token);
remaining.ShouldHaveSingleItem().EntityId.ShouldBe(live);
}
// ---- Vaults ----
[Fact]
public async Task ReplacingTheVaultList_AddsUpdatesAndRemoves()
{
var keep = Guid.CreateVersion7();
var drop = Guid.CreateVersion7();
await harness.Vaults.ReplaceAllAsync(
[Vault(keep, "Personal", 1), Vault(drop, "Old team", 1)], Token);
await harness.Vaults.ReplaceAllAsync([Vault(keep, "Renamed", 2)], Token);
var vaults = await harness.Vaults.ListAsync(Token);
var only = vaults.ShouldHaveSingleItem();
only.VaultId.ShouldBe(keep);
only.Name.ShouldBe("Renamed");
only.KeyGeneration.ShouldBe(2u);
(await harness.Vaults.FindAsync(drop, Token)).ShouldBeNull();
}
[Fact]
public async Task AVaultsWrappedKey_IsCachedSoAnOfflineLaunchCanDecrypt()
{
// Without this, an offline start could unlock the identity bundle and still not open a single
// item.
var vaultId = Guid.CreateVersion7();
byte[] wrapped = [9, 9, 9, 9];
await harness.Vaults.ReplaceAllAsync(
[Vault(vaultId, "Personal", 1) with { WrappedVaultKey = wrapped }], Token);
var read = await harness.Vaults.FindAsync(vaultId, Token);
read!.WrappedVaultKey.ShouldBe(wrapped);
}
// ---- Unlock material ----
[Fact]
public async Task TheUnlockMaterial_SurvivesTheContextThatWroteIt()
{
// The offline unlock story, asserted rather than assumed: a fresh store over the same database
// reads back the salt and the wrapped bundle with no network involved.
var material = Material();
await harness.Unlock.SaveAsync(material, Token);
var reader = new UnlockStore(harness.Factory, TimeProvider.System);
var read = await reader.ReadAsync(Token);
read.ShouldNotBeNull();
read.UserId.ShouldBe(material.UserId);
read.WrappedPrivateKey.ShouldBe(material.WrappedPrivateKey);
read.KdfParameters.Salt.ShouldBe(material.KdfParameters.Salt);
read.KdfParameters.MemoryKibibytes.ShouldBe(material.KdfParameters.MemoryKibibytes);
read.KdfParameters.Passes.ShouldBe(material.KdfParameters.Passes);
}
[Fact]
public async Task SavingTheUnlockMaterialTwice_UpdatesTheSingleRow()
{
await harness.Unlock.SaveAsync(Material(), Token);
await harness.Unlock.SaveAsync(Material() with { Email = "changed@example.com" }, Token);
var read = await harness.Unlock.ReadAsync(Token);
read!.Email.ShouldBe("changed@example.com");
(await CountUnlockRowsAsync()).ShouldBe(1);
}
[Fact]
public async Task AnotherUsersMaterial_IsRefusedRatherThanMixedIn()
{
// Adopting it would offer an unlock prompt whose passphrase can never work, and would mix one
// user's items into another's vault list.
await harness.Unlock.SaveAsync(Material(), Token);
var other = Material() with { UserId = Guid.CreateVersion7() };
await Should.ThrowAsync<CacheIdentityMismatchException>(
async () => await harness.Unlock.SaveAsync(other, Token));
}
// ---- Sync state ----
[Fact]
public async Task AnUnknownVault_ReadsAsStartingFromTheBeginning()
{
// Not an error. A null cursor is exactly right for a vault this client has not synced, and is
// also the recovery path for a cache that had to be discarded.
var state = await harness.SyncState.ReadAsync(Guid.CreateVersion7(), Token);
state.Cursor.ShouldBeNull();
state.KeyGeneration.ShouldBe(0u);
}
[Fact]
public async Task TheCursor_IsStoredVerbatim()
{
// Opaque and integrity-tagged. A client that adjusted one could ask to resume from a position
// the server never granted; storing it untouched is the only correct handling.
const string Cursor = "v1.aGVsbG8gd29ybGQ.c2lnbmF0dXJl";
await harness.SyncState.SaveAsync(new StoredSyncState(VaultId, Cursor, 3), Token);
var read = await harness.SyncState.ReadAsync(VaultId, Token);
read.Cursor.ShouldBe(Cursor);
read.KeyGeneration.ShouldBe(3u);
}
[Fact]
public async Task ResettingAVault_DropsItsItemsButKeepsTheOutbox()
{
// Local unpushed changes are the only copy of the user's work. Clearing them along with the
// cache would turn a recoverable cache problem into lost work.
var entityId = Guid.CreateVersion7();
await harness.Items.SaveAsync(Item(entityId), Token);
await harness.Outbox.QueueAsync(Change(Guid.CreateVersion7()), Token);
await harness.SyncState.SaveAsync(new StoredSyncState(VaultId, "cursor", 1), Token);
await harness.SyncState.ResetAsync(VaultId, Token);
(await harness.Items.ListAsync(VaultId, SyncEntityType.Host, true, Token)).ShouldBeEmpty();
(await harness.SyncState.ReadAsync(VaultId, Token)).Cursor.ShouldBeNull();
(await harness.Outbox.TakeAsync(VaultId, 10, Token)).ShouldHaveSingleItem();
}
// ---- Conflicts ----
[Fact]
public async Task AConflictDetail_RoundTripsAndIsSealedAtRest()
{
// This is the one place the cache holds decrypted vault content on purpose: the value a merge
// displaced. It has to be readable to be useful, and it is as sensitive as the item it came
// from.
var entityId = Guid.CreateVersion7();
var detail = System.Text.Encoding.UTF8.GetBytes("""{"field":"Notes","discarded":"my secret"}""");
var id = await harness.Conflicts.RecordAsync(
VaultId, SyncEntityType.Host, entityId, ConflictKind.FieldOverridden, detail, Token);
var listed = (await harness.Conflicts.ListAsync(VaultId, false, Token)).ShouldHaveSingleItem();
listed.Id.ShouldBe(id);
listed.Kind.ShouldBe(ConflictKind.FieldOverridden);
listed.Detail.ShouldBe(detail);
var raw = await ReadRawConflictDetailAsync(id);
System.Text.Encoding.UTF8.GetString(raw!)
.Contains("my secret", StringComparison.Ordinal)
.ShouldBeFalse("the discarded value is stored in the clear");
}
[Fact]
public async Task AnAcknowledgedConflict_LeavesTheListButKeepsTheValue()
{
// Someone who dismisses a warning and realises a minute later that they wanted the other value
// should still be able to get it.
var id = await harness.Conflicts.RecordAsync(
VaultId, SyncEntityType.Host, Guid.CreateVersion7(), ConflictKind.FieldOverridden,
new byte[] { 1, 2, 3 }, Token);
(await harness.Conflicts.AcknowledgeAsync(id, Token)).ShouldBeTrue();
(await harness.Conflicts.ListAsync(VaultId, false, Token)).ShouldBeEmpty();
var all = (await harness.Conflicts.ListAsync(VaultId, true, Token)).ShouldHaveSingleItem();
all.Detail.ShouldBe(new byte[] { 1, 2, 3 });
}
[Fact]
public async Task AnUnacknowledgedConflict_CannotBeDiscarded()
{
var id = await harness.Conflicts.RecordAsync(
VaultId, SyncEntityType.Host, Guid.CreateVersion7(), ConflictKind.Undecryptable,
new byte[] { 1 }, Token);
(await harness.Conflicts.DiscardAsync(id, Token)).ShouldBeFalse();
await harness.Conflicts.AcknowledgeAsync(id, Token);
(await harness.Conflicts.DiscardAsync(id, Token)).ShouldBeTrue();
}
// ---- Helpers ----
private static CancellationToken Token => TestContext.Current.CancellationToken;
private static StoredVault Vault(Guid vaultId, string name, uint keyGeneration) =>
new(vaultId, name, IsPersonal: true, TeamId: null, keyGeneration, Permissions: 31,
WrappedVaultKey: [1, 2, 3], RekeyRequired: false);
private static StoredUnlockMaterial Material() =>
new(
"https://dodossh.example",
UserId,
"https://idp.example",
"alice",
"alice@example.com",
"Alice",
KeyGeneration: 1,
WrappedPrivateKey: [4, 5, 6, 7],
new KdfParameters("argon2id", [8, 9, 10, 11], 262144, 4, 1),
DateTimeOffset.FromUnixTimeSeconds(1_750_000_000));
private async Task<byte[]?> ReadRawFieldsAsync(Guid entityId)
{
var context = harness.Factory.CreateDbContext();
await using var scope = context.ConfigureAwait(false);
return await context.Set<CachedItemRow>()
.Where(row => row.EntityId == entityId)
.Select(row => row.ProtectedFields)
.SingleAsync(Token);
}
private async Task<byte[]?> ReadRawConflictDetailAsync(Guid id)
{
var context = harness.Factory.CreateDbContext();
await using var scope = context.ConfigureAwait(false);
return await context.Set<ConflictRow>()
.Where(row => row.Id == id)
.Select(row => row.Detail)
.SingleAsync(Token);
}
private async Task<int> CountUnlockRowsAsync()
{
var context = harness.Factory.CreateDbContext();
await using var scope = context.ConfigureAwait(false);
return await context.Set<UnlockMaterialRow>().CountAsync(Token);
}
}