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

Sync and authenticate with SSH keys on the client

Browse Source 
Completes the client half of SSH keys: they sync alongside hosts, appear in
their own list, and can be selected to authenticate a connection instead of
typing a password.

The reconciler and the repository were Host-typed throughout, so the choice was
to generalise them or to keep a second copy per item type. Generalised, because
ItemReconciler's whole premise is that the pull and the push paths must answer
the same collision the same way — two copies would drift the first time one of
them was fixed. What is genuinely per-type now arrives through
IItemKind<TSecret>: the cipher, the merge, the plaintext columns, and the noun
to use when telling a person what happened to their item. Generic where the
server's IItemKind is not, and for the reason that reverses there — the client
needs the concrete type, because it merges field by field.

The pull filter is derived from the same registry that builds the reconcilers.
That is the specific failure being designed out: an item type that encrypts,
merges and lists perfectly and is never once requested from the server, so it
works on the machine that made it and exists nowhere else.

No client cache migration. The item table's primary key and the outbox's unique
index already carry the entity type, and AadResourceTypes already mapped SshKey
— so a host and a key may share an id and never see each other's rows, which
SshKeySyncTests now arranges deliberately.

A key hands the server nothing in plaintext. There is a public_key_fingerprint
column and it would be accepted; leaving it null is deliberate. A fingerprint is
not secret but it is a stable identifier for a key pair, so filling it would let
an operator tell which of their users hold the same key and correlate one across
vaults, for a column nothing reads. The design allows itself one plaintext
concession — the relay address, which the relay cannot work without — and this
is not that.

A key is chosen per connection rather than bound to a host, which works the way
ssh -i does. Binding one needs a field on HostSecret and therefore a payload
schema bump, which makes every host written afterwards read-only on an older
build; worth doing deliberately rather than as a side effect of adding keys.

Three things this found, all of them by being falsified rather than by review:

- Making the reconciler generic silently turned a record comparison into
  reference equality, because == on a type parameter is not value equality. The
  effect would have been a conflict recorded on every pass for an unacknowledged
  create that had in fact landed. Sabotaging the fix left all 73 tests passing —
  nothing covered that branch — so ConflictMatrixTests now has
  AnUnacknowledgedCreateThatDidLand_IsDroppedQuietly, which fails without it.

- A test asserting that a blank passphrase reaches SSH.NET as null was vacuous:
  it exercised the editor, not the credential path, and passed with the guard
  deleted. Resolved by making SshKeySecret.Passphrase normalise an empty string
  to null, so there is one spelling of one state — which also keeps two clients
  from producing different payload bytes for an identical key. That exposed a
  wider gap: SshKeySecret, its codec and its merge had no direct unit tests at
  all. They have 25 now.

- The reason first given for that normalisation was false. It claimed SSH.NET
  rejects a passphrase supplied for an unprotected key; measured against a real
  sshd it ignores it and authenticates anyway. Corrected everywhere it was
  stated and recorded in docs/platform-flags.md. The same test file also closes
  a real hole: SshPrivateKeyCredential had never been exercised against a
  server, because the existing key test builds SSH.NET's auth method directly
  and bypasses the path a vault-held key actually takes.

Only one editor may be open at a time. Both sit in the same 340-pixel column as
Auto rows and their heights together exceed it at the window's minimum size, so
two open editors put the lower one's Save and Cancel past the bottom edge — the
same failure this window already shipped once with the setup screens. Expressed
as a state rule because that is the only form of it this repository can check:
nothing here loads a .axaml. The refusal keeps what was typed, since in the key
editor that is a pasted private key the user may have nowhere else.

The end-to-end slice now carries a key as well as a host, so both item types go
through the real API, the real PostgreSQL and the real crypto in one pass — the
three hand-kept mappings between enums that do not line up are the reason that
is worth doing rather than trusting the unit suites.

735 tests green, including the container-backed SSH and end-to-end suites. Zero
warnings, dotnet format clean.
This commit is contained in:
jaap-jan
2026-07-29 20:27:23 +02:00
parent 586cb303d5
commit e3fd3e1728
26 changed files with 2804 additions and 505 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/DodoSSH.Client.Sync/HostRepository.cs
+21 -280
View File
@@ -1,299 +1,40 @@
using DodoSSH.Client.Domain;
using DodoSSH.Client.Storage;
using DodoSSH.Contracts;
namespace DodoSSH.Client.Sync;
/// <summary>A host as the interface should show it.</summary>
/// <param name="EntityId">The item id.</param>
/// <param name="Host">The decrypted host.</param>
/// <param name="Version">
/// The server version this is based on. Zero for an item that has never been accepted.
/// </param>
/// <param name="HasUnsyncedChanges">
/// Whether this reflects a local edit the server has not accepted yet. Worth showing: it is the
/// difference between "saved" and "saved here".
/// </param>
/// <param name="IsBlocked">
/// Whether the pending change was refused and is waiting on a person, so it will not retry on its own.
/// </param>
/// <param name="IsReadOnly">
/// Whether this host was written by a newer client and so must not be edited here, because re-encoding
/// it would drop fields this build cannot represent.
/// </param>
public sealed record VaultHost(
Guid EntityId,
HostSecret Host,
int Version,
bool HasUnsyncedChanges,
bool IsBlocked,
bool IsReadOnly);
/// <summary>The hosts in a vault, and what could not be read.</summary>
/// <param name="Hosts">The readable hosts, newest change last.</param>
/// <param name="Unreadable">
/// How many items would not decrypt. Surfaced rather than swallowed: a non-zero count here after a
/// rekey is the signal that new grants are needed.
/// </param>
public sealed record HostListing(IReadOnlyList<VaultHost> Hosts, int Unreadable);
/// <summary>
/// Reading and writing hosts, as the interface sees them.
/// The hosts in a vault, decrypted, with unpushed local changes laid over them.
/// </summary>
/// <remarks>
/// <para>
/// The view is the mirror of the server's state with the outbox laid over it, which is what makes the
/// application feel local: an edit appears immediately and a delete disappears immediately, whether or
/// not the network is there. Nothing here talks to the server; the sync engine reconciles later.
/// </para>
/// <para>
/// Writes never touch the mirror. That separation is load-bearing — the mirror is the common ancestor a
/// three-way merge needs, and a repository that updated it on save would destroy the very state that
/// lets a conflict be merged instead of arbitrated.
/// </para>
/// A named facade over <see cref="VaultItemRepository{TSecret}"/>, which holds the logic and is shared
/// with <see cref="SshKeyRepository"/>. Two reasons it is a facade rather than the generic class itself:
/// callers read better for having asked for hosts by name, and the item kind that parameterises the
/// generic is internal to this assembly — exposing it would make the encoding and merge of every item
/// type part of the public surface for the sake of a constructor argument.
/// </remarks>
public sealed class HostRepository(ItemStore items, OutboxStore outbox, VaultKeyring keyring)
{
/// <summary>Reads every host the user should see in a vault.</summary>
public async Task<HostListing> ListAsync(Guid vaultId, CancellationToken cancellationToken)
{
if (!keyring.TryGet(vaultId, out var vaultKey, out _))
{
throw new VaultUnreadableException(vaultId);
}
private readonly VaultItemRepository<HostSecret> hosts =
new(HostKind.Instance, items, outbox, keyring);
var mirrored = await items
.ListAsync(vaultId, SyncEntityType.Host, includeDeleted: true, cancellationToken)
.ConfigureAwait(false);
/// <inheritdoc cref="VaultItemRepository{TSecret}.ListAsync" />
public Task<ItemListing<HostSecret>> ListAsync(Guid vaultId, CancellationToken cancellationToken) =>
hosts.ListAsync(vaultId, cancellationToken);
var pending = await outbox.ListAllAsync(vaultId, cancellationToken).ConfigureAwait(false);
/// <inheritdoc cref="VaultItemRepository{TSecret}.CreateAsync" />
public Task<Guid> CreateAsync(Guid vaultId, HostSecret host, CancellationToken cancellationToken) =>
hosts.CreateAsync(vaultId, host, cancellationToken);
var pendingByEntity = pending
.Where(operation => operation.EntityType == SyncEntityType.Host)
.ToDictionary(operation => operation.EntityId);
var hosts = new List<VaultHost>();
var unreadable = 0;
foreach (var item in mirrored)
{
if (pendingByEntity.Remove(item.EntityId, out var local))
{
AddPending(hosts, ref unreadable, vaultKey, local);
continue;
}
if (item.IsDeleted || item.Payload is null)
{
continue;
}
var opened = HostCipher.TryOpen(item.Payload, vaultKey.Span, item.EntityId, item.Version);
if (opened is null)
{
unreadable++;
continue;
}
hosts.Add(new VaultHost(
item.EntityId, opened.Host, item.Version, false, false, opened.IsReadOnly));
}
// Whatever is left has no mirror row yet: items created here and not yet accepted.
foreach (var local in pendingByEntity.Values)
{
AddPending(hosts, ref unreadable, vaultKey, local);
}
return new HostListing(hosts, unreadable);
}
/// <summary>
/// Adds a host, returning the id it was given.
/// </summary>
/// <remarks>
/// The id is generated here, not by the server, which is what lets a host be created with no network
/// at all — the point of the whole outbox. UUIDv7 so that ids sort by creation time, which keeps
/// index locality reasonable on the server side.
/// </remarks>
public async Task<Guid> CreateAsync(
Guid vaultId,
HostSecret host,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(host);
Validate(host);
var (vaultKey, generation) = Key(vaultId);
var entityId = Guid.CreateVersion7();
await outbox.QueueAsync(
new QueuedChange(
vaultId,
SyncEntityType.Host,
entityId,
SyncOperation.Upsert,
ExpectedVersion: null,
HostCipher.Seal(host, vaultKey.Span, entityId, generation, itemVersion: 1),
HostFields.From(host),
Ancestor: null),
cancellationToken).ConfigureAwait(false);
return entityId;
}
/// <summary>
/// Replaces a host's contents.
/// </summary>
/// <remarks>
/// The base is taken from the pending operation when there is one, and from the mirror otherwise.
/// Reading it the other way round would seal the payload at a version that does not match the
/// <c>expectedVersion</c> the coalesced row keeps — and because the AAD binds the item version, the
/// result would encrypt cleanly and never decrypt again.
/// </remarks>
public async Task UpdateAsync(
/// <inheritdoc cref="VaultItemRepository{TSecret}.UpdateAsync" />
public Task UpdateAsync(
Guid vaultId,
Guid entityId,
HostSecret host,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(host);
Validate(host);
CancellationToken cancellationToken) =>
hosts.UpdateAsync(vaultId, entityId, host, cancellationToken);
var (vaultKey, generation) = Key(vaultId);
var pending = await outbox
.FindAsync(vaultId, SyncEntityType.Host, entityId, cancellationToken)
.ConfigureAwait(false);
var expectedVersion = pending is not null
? pending.ExpectedVersion
: await MirrorVersionAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
var ancestor = pending?.Ancestor
?? await MirrorAncestorAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
await outbox.QueueAsync(
new QueuedChange(
vaultId,
SyncEntityType.Host,
entityId,
SyncOperation.Upsert,
expectedVersion,
HostCipher.Seal(
host, vaultKey.Span, entityId, generation, SyncVersions.NextVersion(expectedVersion)),
HostFields.From(host),
ancestor),
cancellationToken).ConfigureAwait(false);
}
/// <summary>
/// Deletes a host.
/// </summary>
/// <remarks>
/// Queued as a tombstone, never a local removal. An offline client that simply forgot the row would
/// be unable to tell the server anything, and the item would come back on the next pull.
/// </remarks>
public async Task DeleteAsync(Guid vaultId, Guid entityId, CancellationToken cancellationToken)
{
var pending = await outbox
.FindAsync(vaultId, SyncEntityType.Host, entityId, cancellationToken)
.ConfigureAwait(false);
var expectedVersion = pending is not null
? pending.ExpectedVersion
: await MirrorVersionAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
var ancestor = pending?.Ancestor
?? await MirrorAncestorAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
await outbox.QueueAsync(
new QueuedChange(
vaultId,
SyncEntityType.Host,
entityId,
SyncOperation.Delete,
expectedVersion,
Payload: null,
Fields: null,
ancestor),
cancellationToken).ConfigureAwait(false);
}
private static void Validate(HostSecret host)
{
if (!host.TryValidate(out var error))
{
throw new ArgumentException(error, nameof(host));
}
}
private static void AddPending(
List<VaultHost> hosts,
ref int unreadable,
ReadOnlyMemory<byte> vaultKey,
PendingOperation local)
{
if (local.Operation == SyncOperation.Delete)
{
// Gone as far as this machine is concerned, even before the server agrees.
return;
}
if (local.Payload is null)
{
unreadable++;
return;
}
var version = SyncVersions.NextVersion(local.ExpectedVersion);
var opened = HostCipher.TryOpen(local.Payload, vaultKey.Span, local.EntityId, version);
if (opened is null)
{
unreadable++;
return;
}
hosts.Add(new VaultHost(
local.EntityId,
opened.Host,
local.ExpectedVersion ?? 0,
HasUnsyncedChanges: true,
local.IsParked,
opened.IsReadOnly));
}
private (ReadOnlyMemory<byte> VaultKey, uint Generation) Key(Guid vaultId) =>
keyring.TryGet(vaultId, out var vaultKey, out var generation)
? (vaultKey, generation)
: throw new VaultUnreadableException(vaultId);
private async Task<int?> MirrorVersionAsync(
Guid vaultId,
Guid entityId,
CancellationToken cancellationToken)
{
var item = await items
.FindAsync(vaultId, SyncEntityType.Host, entityId, cancellationToken)
.ConfigureAwait(false);
// A null means the server has never seen this item, which is exactly what "create" is.
return item?.Version;
}
private async Task<StoredAncestor?> MirrorAncestorAsync(
Guid vaultId,
Guid entityId,
CancellationToken cancellationToken)
{
var item = await items
.FindAsync(vaultId, SyncEntityType.Host, entityId, cancellationToken)
.ConfigureAwait(false);
return item?.Payload is null
? null
: new StoredAncestor(item.Version, item.Payload, item.Fields);
}
/// <inheritdoc cref="VaultItemRepository{TSecret}.DeleteAsync" />
public Task DeleteAsync(Guid vaultId, Guid entityId, CancellationToken cancellationToken) =>
hosts.DeleteAsync(vaultId, entityId, cancellationToken);
}
src/DodoSSH.Client.Sync/ItemKinds.cs
+250
View File
@@ -0,0 +1,250 @@
using DodoSSH.Client.Domain;
using DodoSSH.Client.Storage;
using DodoSSH.Contracts;
namespace DodoSSH.Client.Sync;
/// <summary>A decrypted item, and whether this build may write it back.</summary>
/// <param name="Secret">The item.</param>
/// <param name="IsReadOnly">
/// Whether a newer client wrote it, in which case re-encoding it here would drop fields this build has
/// no concept of.
/// </param>
internal sealed record OpenedItem<TSecret>(TSecret Secret, bool IsReadOnly)
where TSecret : class, IVaultSecret;
/// <summary>A merged item, and everything that had to be overridden to produce it.</summary>
/// <param name="Merged">The item to store and push.</param>
/// <param name="Conflicts">Empty when the two sides were reconcilable field by field.</param>
internal sealed record MergedItem<TSecret>(
TSecret Merged,
IReadOnlyList<HostFieldConflict> Conflicts)
where TSecret : class, IVaultSecret;
/// <summary>
/// Everything about one item type that the shared sync path cannot know.
/// </summary>
/// <remarks>
/// <para>
/// The reconciler holds the six answers a collision can have — merge, adopt, resurrect, abandon, park,
/// refuse — and every one of them is identical for a host and for an SSH key. Only the encoding, the
/// merge and the plaintext columns differ, and those arrive through here. A second copy of the
/// reconciler per item type is the alternative, and it is not a real one: the file's whole premise is
/// that the pull and push paths must answer the same situation the same way, and two copies would drift
/// the moment one of them was fixed.
/// </para>
/// <para>
/// Generic, unlike the server's <c>IItemKind</c>, and for a reason that reverses there: the client
/// <em>does</em> need the concrete type. It merges two versions of an item field by field and hands the
/// result to a codec, so erasing the type would only move the downcasts inside the reconciler, where
/// they would be a cast per branch instead of none.
/// </para>
/// </remarks>
internal interface IItemKind<TSecret>
where TSecret : class, IVaultSecret
{
/// <summary>The type as the wire contract names it.</summary>
SyncEntityType EntityType { get; }
/// <summary>
/// What to call one of these when telling a person what happened to it.
/// </summary>
/// <remarks>
/// Lower case and singular, because every use is mid-sentence. This exists because the conflict log
/// is read by people: "this host could not be decrypted" is actively misleading when the item was a
/// private key, and a user who is told the wrong noun looks in the wrong place.
/// </remarks>
string Noun { get; }
/// <inheritdoc cref="HostCipher.TryOpen" />
OpenedItem<TSecret>? TryOpen(
EncryptedPayload payload,
ReadOnlySpan<byte> vaultKey,
Guid entityId,
int itemVersion);
/// <inheritdoc cref="HostCipher.Seal" />
EncryptedPayload Seal(
TSecret secret,
ReadOnlySpan<byte> vaultKey,
Guid entityId,
uint keyGeneration,
int itemVersion);
/// <summary>
/// The plaintext columns the server gets, or null when this type gives it nothing.
/// </summary>
/// <remarks>
/// Nullable rather than an all-defaults record, because the difference is visible on the wire and to
/// a reader: <c>SyncPlaintextFields</c> with nothing set still serialises <c>relayEnabled: false</c>,
/// which invites the belief that the type has a relay setting which happens to be off.
/// </remarks>
SyncPlaintextFields? Fields(TSecret secret);
/// <summary>Merges two divergent versions against the version they both started from.</summary>
MergedItem<TSecret> Merge(TSecret ancestor, TSecret local, TSecret remote);
/// <summary>The same item under a new name, for a resurrection.</summary>
TSecret Relabel(TSecret secret, string label);
}
/// <summary>
/// The item types this client synchronises.
/// </summary>
/// <remarks>
/// <para>
/// <b>One list, and the pull filter is derived from it.</b> The engine asks the server for exactly the
/// types in <see cref="Registry"/> and refuses to apply a change of any other type, so adding a kind
/// cannot leave the filter behind — which is the specific way this would otherwise break: an item type
/// that reads and writes perfectly in every unit test and is never once requested from the server.
/// </para>
/// <para>
/// A reconciler per type rather than one shared instance, because each closes the generic over its own
/// secret type. They are cheap — four fields and no state — and building them once per engine keeps the
/// per-change path a dictionary lookup.
/// </para>
/// </remarks>
internal static class ItemKinds
{
private static readonly (SyncEntityType Type, ReconcilerFactory Create)[] Registry =
[
(SyncEntityType.Host, static (outbox, conflicts, keyring) =>
new ItemReconciler<HostSecret>(HostKind.Instance, outbox, conflicts, keyring)),
(SyncEntityType.SshKey, static (outbox, conflicts, keyring) =>
new ItemReconciler<SshKeySecret>(SshKeyKind.Instance, outbox, conflicts, keyring)),
];
/// <summary>The types to ask the server for, in a fixed order.</summary>
internal static IReadOnlyList<SyncEntityType> SyncedTypes { get; } =
[.. Registry.Select(entry => entry.Type)];
private delegate IItemReconciler ReconcilerFactory(
OutboxStore outbox,
ConflictStore conflicts,
VaultKeyring keyring);
/// <summary>Builds one reconciler per synchronised type.</summary>
internal static Dictionary<SyncEntityType, IItemReconciler> Reconcilers(
OutboxStore outbox,
ConflictStore conflicts,
VaultKeyring keyring) =>
Registry.ToDictionary(
entry => entry.Type,
entry => entry.Create(outbox, conflicts, keyring));
}
/// <summary>Hosts.</summary>
internal sealed class HostKind : IItemKind<HostSecret>
{
internal static HostKind Instance { get; } = new();
/// <inheritdoc />
public SyncEntityType EntityType => SyncEntityType.Host;
/// <inheritdoc />
public string Noun => "host";
/// <inheritdoc />
public OpenedItem<HostSecret>? TryOpen(
EncryptedPayload payload,
ReadOnlySpan<byte> vaultKey,
Guid entityId,
int itemVersion)
{
var document = HostCipher.TryOpen(payload, vaultKey, entityId, itemVersion);
return document is null ? null : new OpenedItem<HostSecret>(document.Host, document.IsReadOnly);
}
/// <inheritdoc />
public EncryptedPayload Seal(
HostSecret secret,
ReadOnlySpan<byte> vaultKey,
Guid entityId,
uint keyGeneration,
int itemVersion) =>
HostCipher.Seal(secret, vaultKey, entityId, keyGeneration, itemVersion);
/// <inheritdoc />
public SyncPlaintextFields? Fields(HostSecret secret) => HostFields.From(secret);
/// <inheritdoc />
public MergedItem<HostSecret> Merge(HostSecret ancestor, HostSecret local, HostSecret remote)
{
var merged = HostSecretMerge.Merge(ancestor, local, remote);
return new MergedItem<HostSecret>(merged.Merged, merged.Conflicts);
}
/// <inheritdoc />
public HostSecret Relabel(HostSecret secret, string label)
{
ArgumentNullException.ThrowIfNull(secret);
return secret with { Label = label };
}
}
/// <summary>SSH keys.</summary>
internal sealed class SshKeyKind : IItemKind<SshKeySecret>
{
internal static SshKeyKind Instance { get; } = new();
/// <inheritdoc />
public SyncEntityType EntityType => SyncEntityType.SshKey;
/// <inheritdoc />
public string Noun => "SSH key";
/// <inheritdoc />
public OpenedItem<SshKeySecret>? TryOpen(
EncryptedPayload payload,
ReadOnlySpan<byte> vaultKey,
Guid entityId,
int itemVersion)
{
var document = SshKeyCipher.TryOpen(payload, vaultKey, entityId, itemVersion);
return document is null ? null : new OpenedItem<SshKeySecret>(document.Key, document.IsReadOnly);
}
/// <inheritdoc />
public EncryptedPayload Seal(
SshKeySecret secret,
ReadOnlySpan<byte> vaultKey,
Guid entityId,
uint keyGeneration,
int itemVersion) =>
SshKeyCipher.Seal(secret, vaultKey, entityId, keyGeneration, itemVersion);
/// <summary>
/// Nothing at all.
/// </summary>
/// <remarks>
/// The server has a <c>public_key_fingerprint</c> column and would accept one here, and this client
/// deliberately declines to fill it. A fingerprint is not a secret, but it is a stable identifier for
/// a key pair, and handing it over would let the operator tell which of their users hold the same key
/// and correlate one key across vaults — for a column nothing in the product reads. The design allows
/// itself exactly one plaintext concession, the relay address, and it is a concession because the
/// relay cannot work without it. This is not that. See ADR 0004.
/// </remarks>
/// <inheritdoc />
public SyncPlaintextFields? Fields(SshKeySecret secret) => null;
/// <inheritdoc />
public MergedItem<SshKeySecret> Merge(SshKeySecret ancestor, SshKeySecret local, SshKeySecret remote)
{
var merged = SshKeySecretMerge.Merge(ancestor, local, remote);
return new MergedItem<SshKeySecret>(merged.Merged, merged.Conflicts);
}
/// <inheritdoc />
public SshKeySecret Relabel(SshKeySecret secret, string label)
{
ArgumentNullException.ThrowIfNull(secret);
return secret with { Label = label };
}
}
src/DodoSSH.Client.Sync/ItemReconciler.cs
+174 -61
View File
@@ -13,7 +13,7 @@ namespace DodoSSH.Client.Sync;
/// Deterministic, from the original id and the version of the tombstone that displaced it. That matters
/// because applying a pulled change is at-least-once: the cursor is saved after the changes are applied,
/// so a process that dies in between re-applies them on the next start. A random id would resurrect the
/// same host twice and leave the user with duplicates to sort out; this way the second attempt produces
/// same item twice and leave the user with duplicates to sort out; this way the second attempt produces
/// the same id and coalesces into the same outbox row.
/// <para>
/// Not a UUIDv7, and that is fine — the server treats item ids as opaque, and the time ordering a v7 id
@@ -47,6 +47,32 @@ internal static class ResurrectionId
}
}
/// <summary>
/// Reconciles one item type, with the secret type erased so the engine can hold a table of them.
/// </summary>
/// <remarks>
/// The engine never needs the concrete type — it dispatches on the entity type a change carries and lets
/// the reconciler do the rest — so this interface is what it stores. The two members are the two places
/// the push and pull paths need type-specific crypto.
/// </remarks>
internal interface IItemReconciler
{
/// <summary>Reconciles a remote change against the operation pending for the same item.</summary>
Task ReconcileAsync(
Guid vaultId,
SyncChange remote,
PendingOperation pending,
SyncReportBuilder report,
CancellationToken cancellationToken);
/// <summary>Re-seals a queued change as a create, for a server that says it has no such row.</summary>
/// <returns>Null on success, or the reason the change could not be re-offered.</returns>
Task<string?> ReofferAsCreateAsync(
Guid vaultId,
PendingOperation pending,
CancellationToken cancellationToken);
}
/// <summary>
/// Decides what happens when a remote change collides with an unpushed local one.
/// </summary>
@@ -54,7 +80,10 @@ internal static class ResurrectionId
/// <para>
/// Shared by the pull and the push paths, because both meet the same six situations and must answer them
/// identically — a pull that merged one way and a push that merged the other would make the outcome
/// depend on which side happened to notice first.
/// depend on which side happened to notice first. Shared across item types for the same reason: a host
/// and an SSH key meet those six situations in exactly the same way, and the only differences —
/// encoding, merge, plaintext columns, what to call the thing — arrive through
/// <see cref="IItemKind{TSecret}"/>.
/// </para>
/// <para>
/// <b>The governing rule is that nothing is discarded silently.</b> Where the two sides can be
@@ -64,20 +93,29 @@ internal static class ResurrectionId
/// reconstruct.
/// </para>
/// </remarks>
internal sealed class ItemReconciler(
ItemStore items,
/// <remarks>
/// Takes no <see cref="ItemStore"/>, which is worth noticing rather than reading as an omission: nothing
/// here writes the mirror. Reconciling only ever revises the outbox and records conflicts, and the
/// server's own version of an item is written by <see cref="ItemMirror"/> before this is called.
/// </remarks>
internal sealed class ItemReconciler<TSecret>(
IItemKind<TSecret> kind,
OutboxStore outbox,
ConflictStore conflicts,
VaultKeyring keyring)
VaultKeyring keyring) : IItemReconciler
where TSecret : class, IVaultSecret
{
/// <summary>Reconciles a remote change against the operation pending for the same item.</summary>
internal Task ReconcileAsync(
public Task ReconcileAsync(
Guid vaultId,
SyncChange remote,
PendingOperation pending,
SyncReportBuilder report,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(remote);
ArgumentNullException.ThrowIfNull(pending);
if (remote.Operation == SyncOperation.Delete)
{
return pending.Operation == SyncOperation.Delete
@@ -91,6 +129,49 @@ internal sealed class ItemReconciler(
: MergeAsync(vaultId, remote, pending, report, cancellationToken);
}
/// <summary>
/// Re-seals a queued change as a create, for a server that says it has no such row.
/// </summary>
/// <remarks>
/// The payload has to be re-sealed rather than re-sent: it was sealed at the version this client
/// predicted, and a create produces version 1, which the AAD binds.
/// </remarks>
/// <returns>Null on success, or the reason the change could not be re-offered.</returns>
public async Task<string?> ReofferAsCreateAsync(
Guid vaultId,
PendingOperation pending,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(pending);
if (!keyring.TryGet(vaultId, out var vaultKey, out var generation) || pending.Payload is null)
{
return "This item has no usable vault key.";
}
var local = kind.TryOpen(
pending.Payload,
vaultKey.Span,
pending.EntityId,
SyncVersions.NextVersion(pending.ExpectedVersion));
if (local is null)
{
return "The queued change could not be decrypted, so it could not be re-offered.";
}
await outbox.ReviseAsync(
pending.Sequence,
SyncOperation.Upsert,
expectedVersion: null,
kind.Seal(local.Secret, vaultKey.Span, pending.EntityId, generation, itemVersion: 1),
kind.Fields(local.Secret),
ancestor: null,
cancellationToken).ConfigureAwait(false);
return null;
}
/// <summary>
/// Reconciles a pending create that the server says already exists.
/// </summary>
@@ -98,7 +179,7 @@ internal sealed class ItemReconciler(
/// In practice this means an earlier push of the same create did land and its acknowledgement was
/// lost — a timeout, a dropped connection — after which the local row may also have been edited. The
/// resolution adopts the server's row as the base and re-offers the local content as an update, so
/// the newer local state wins and no duplicate host appears. A genuine id collision between two
/// the newer local state wins and no duplicate item appears. A genuine id collision between two
/// clients is the other reading, and is not achievable with UUIDv7; if it happened, the server's
/// values would be in the conflict log rather than gone.
/// </remarks>
@@ -117,11 +198,14 @@ internal sealed class ItemReconciler(
return;
}
var (local, remoteHost, vaultKey, generation) = opened.Value;
var (local, remoteSecret, vaultKey, generation) = opened.Value;
if (local == remoteHost)
// Through the comparer, not ==. Both secrets are records with value equality, but TSecret is a
// type parameter, so == would bind to reference equality at compile time and never be true —
// turning "our own create coming back" into a conflict record on every single pass.
if (EqualityComparer<TSecret>.Default.Equals(local, remoteSecret))
{
// Byte-for-byte the same host: this is our own create coming back. Nothing to do but stop
// Field for field the same item: this is our own create coming back. Nothing to do but stop
// trying to send it again.
await outbox.CompleteAsync(pending.Sequence, cancellationToken).ConfigureAwait(false);
return;
@@ -133,7 +217,7 @@ internal sealed class ItemReconciler(
await conflicts.RecordAsync(
vaultId,
SyncEntityType.Host,
kind.EntityType,
remote.EntityId,
ConflictKind.FieldOverridden,
ConflictDetails.Encode(
@@ -167,9 +251,9 @@ internal sealed class ItemReconciler(
return;
}
var (local, remoteHost, vaultKey, generation) = opened.Value;
var (local, remoteSecret, vaultKey, generation) = opened.Value;
var ancestor = HostCipher.TryOpen(
var ancestor = kind.TryOpen(
pending.Ancestor.Payload, vaultKey.Span, remote.EntityId, pending.Ancestor.Version);
if (ancestor is null)
@@ -182,17 +266,17 @@ internal sealed class ItemReconciler(
return;
}
var merged = HostSecretMerge.Merge(ancestor.Host, local, remoteHost);
var merged = kind.Merge(ancestor.Secret, local, remoteSecret);
await ReviseAsUpdateAsync(
vaultId, remote, pending, merged.Merged, vaultKey, generation, cancellationToken)
.ConfigureAwait(false);
if (merged.HasConflicts)
if (merged.Conflicts.Count > 0)
{
await conflicts.RecordAsync(
vaultId,
SyncEntityType.Host,
kind.EntityType,
remote.EntityId,
ConflictKind.FieldOverridden,
ConflictDetails.Encode(
@@ -211,7 +295,7 @@ internal sealed class ItemReconciler(
/// <remarks>
/// The tombstone is accepted — arguing with it would conflict for ever, since a delete beats a late
/// upsert on the server — and the local content is re-offered under a fresh id, labelled so the user
/// can see what happened. That is the whole of "never silently drop a host": the original goes, the
/// can see what happened. That is the whole of "never silently drop an item": the original goes, the
/// work does not.
/// </remarks>
private async Task ResurrectAsync(
@@ -230,7 +314,7 @@ internal sealed class ItemReconciler(
var local = pending.Payload is null
? null
: HostCipher.TryOpen(
: kind.TryOpen(
pending.Payload,
vaultKey.Span,
remote.EntityId,
@@ -244,7 +328,7 @@ internal sealed class ItemReconciler(
}
var restoredId = ResurrectionId.For(remote.EntityId, remote.Version);
var restored = local.Host with { Label = $"{local.Host.Label} (restored)" };
var restored = kind.Relabel(local.Secret, $"{local.Secret.Label} (restored)");
// Queued before the original is cleared, and that order matters. These are two separate
// transactions, so a process that dies between them has to fail in the direction that keeps the
@@ -254,12 +338,12 @@ internal sealed class ItemReconciler(
await outbox.QueueAsync(
new QueuedChange(
vaultId,
SyncEntityType.Host,
kind.EntityType,
restoredId,
SyncOperation.Upsert,
ExpectedVersion: null,
HostCipher.Seal(restored, vaultKey.Span, restoredId, generation, itemVersion: 1),
HostFields.From(restored),
kind.Seal(restored, vaultKey.Span, restoredId, generation, itemVersion: 1),
kind.Fields(restored),
Ancestor: null),
cancellationToken).ConfigureAwait(false);
@@ -268,11 +352,11 @@ internal sealed class ItemReconciler(
await conflicts.RecordAsync(
vaultId,
SyncEntityType.Host,
kind.EntityType,
remote.EntityId,
ConflictKind.RemoteDeleteResurrected,
ConflictDetails.Encode(
$"'{local.Host.Label}' was deleted elsewhere while this machine had unsaved changes. "
$"'{local.Secret.Label}' was deleted elsewhere while this machine had unsaved changes. "
+ $"The deletion stands and the local version was kept as '{restored.Label}'."),
cancellationToken).ConfigureAwait(false);
@@ -291,23 +375,23 @@ internal sealed class ItemReconciler(
await conflicts.RecordAsync(
vaultId,
SyncEntityType.Host,
kind.EntityType,
remote.EntityId,
ConflictKind.LocalDeleteOverridden,
ConflictDetails.Encode(
"This host was edited elsewhere after it was deleted here, so the deletion was not "
+ "applied. Delete it again if that is still what you want."),
$"This {kind.Noun} was edited elsewhere after it was deleted here, so the deletion was "
+ "not applied. Delete it again if that is still what you want."),
cancellationToken).ConfigureAwait(false);
report.DeletesAbandoned++;
}
/// <summary>Re-offers a host as an update against the server's current version.</summary>
/// <summary>Re-offers an item as an update against the server's current version.</summary>
private async Task ReviseAsUpdateAsync(
Guid vaultId,
SyncChange remote,
PendingOperation pending,
HostSecret host,
TSecret secret,
ReadOnlyMemory<byte> vaultKey,
uint generation,
CancellationToken cancellationToken)
@@ -318,14 +402,14 @@ internal sealed class ItemReconciler(
pending.Sequence,
SyncOperation.Upsert,
expectedVersion: remote.Version,
HostCipher.Seal(host, vaultKey.Span, remote.EntityId, generation, nextVersion),
HostFields.From(host),
kind.Seal(secret, vaultKey.Span, remote.EntityId, generation, nextVersion),
kind.Fields(secret),
new StoredAncestor(remote.Version, remote.Payload!, remote.PlaintextFields),
cancellationToken).ConfigureAwait(false);
}
/// <summary>Opens both sides of a collision, parking the operation if either will not open.</summary>
private async Task<(HostSecret Local, HostSecret Remote, ReadOnlyMemory<byte> VaultKey, uint Generation)?>
private async Task<(TSecret Local, TSecret Remote, ReadOnlyMemory<byte> VaultKey, uint Generation)?>
OpenPairAsync(
Guid vaultId,
SyncChange remote,
@@ -342,47 +426,63 @@ internal sealed class ItemReconciler(
return null;
}
var local = HostCipher.TryOpen(
var local = kind.TryOpen(
pending.Payload,
vaultKey.Span,
remote.EntityId,
SyncVersions.NextVersion(pending.ExpectedVersion));
var remoteHost = HostCipher.TryOpen(
var remoteSecret = kind.TryOpen(
remote.Payload, vaultKey.Span, remote.EntityId, remote.Version);
if (local is null || remoteHost is null)
if (local is null || remoteSecret is null)
{
await ParkAsync(vaultId, remote.EntityId, pending, report, cancellationToken)
.ConfigureAwait(false);
return null;
}
if (local.IsReadOnly || remoteHost.IsReadOnly)
if (local.IsReadOnly || remoteSecret.IsReadOnly)
{
// A newer client wrote fields this build cannot represent. Re-encoding would drop them, so
// the item is left alone until this client is updated.
await outbox.ParkAsync(
pending.Sequence,
"Written by a newer version of DodoSSH; update before editing this host.",
cancellationToken).ConfigureAwait(false);
await conflicts.RecordAsync(
vaultId,
SyncEntityType.Host,
remote.EntityId,
ConflictKind.TooNewToEdit,
ConflictDetails.Encode(
"This host was written by a newer version of DodoSSH. It can be read but not "
+ "merged here, because saving it would discard fields this version does not know "
+ "about."),
cancellationToken).ConfigureAwait(false);
report.Parked++;
await ParkAsTooNewAsync(vaultId, remote.EntityId, pending, report, cancellationToken)
.ConfigureAwait(false);
return null;
}
return (local.Host, remoteHost.Host, vaultKey, generation);
return (local.Secret, remoteSecret.Secret, vaultKey, generation);
}
/// <summary>
/// Leaves an item alone because a newer client wrote it.
/// </summary>
/// <remarks>
/// Re-encoding would drop fields this build cannot represent, so the item waits until this client is
/// updated. Parked rather than merged-and-hoped: the dropped field could be the one that matters.
/// </remarks>
private async Task ParkAsTooNewAsync(
Guid vaultId,
Guid entityId,
PendingOperation pending,
SyncReportBuilder report,
CancellationToken cancellationToken)
{
await outbox.ParkAsync(
pending.Sequence,
$"Written by a newer version of DodoSSH; update before editing this {kind.Noun}.",
cancellationToken).ConfigureAwait(false);
await conflicts.RecordAsync(
vaultId,
kind.EntityType,
entityId,
ConflictKind.TooNewToEdit,
ConflictDetails.Encode(
$"This {kind.Noun} was written by a newer version of DodoSSH. It can be read but not "
+ "merged here, because saving it would discard fields this version does not know "
+ "about."),
cancellationToken).ConfigureAwait(false);
report.Parked++;
}
private async Task ParkAsync(
@@ -394,16 +494,16 @@ internal sealed class ItemReconciler(
{
await outbox.ParkAsync(
pending.Sequence,
"The local or the server copy of this host could not be decrypted.",
$"The local or the server copy of this {kind.Noun} could not be decrypted.",
cancellationToken).ConfigureAwait(false);
await conflicts.RecordAsync(
vaultId,
SyncEntityType.Host,
kind.EntityType,
entityId,
ConflictKind.Undecryptable,
ConflictDetails.Encode(
"This host could not be decrypted, so the change made here could not be merged. "
$"This {kind.Noun} could not be decrypted, so the change made here could not be merged. "
+ "The vault key may have been rotated, or the stored payload may not belong to this "
+ "item."),
cancellationToken).ConfigureAwait(false);
@@ -411,9 +511,22 @@ internal sealed class ItemReconciler(
report.Unreadable++;
report.Parked++;
}
}
/// <summary>Writes the server's version of an item into the local mirror.</summary>
internal Task MirrorAsync(Guid vaultId, SyncChange change, CancellationToken cancellationToken) =>
/// <summary>Writes the server's version of an item into the local mirror.</summary>
/// <remarks>
/// Type-agnostic on purpose, and separate from the reconcilers for that reason: mirroring copies
/// ciphertext into a row and never decrypts, so there is nothing here for an item kind to decide. Making
/// it a method on a reconciler would have meant picking one arbitrarily, or having the engine look one up
/// for a change it can mirror without knowing anything about.
/// </remarks>
internal static class ItemMirror
{
internal static Task WriteAsync(
ItemStore items,
Guid vaultId,
SyncChange change,
CancellationToken cancellationToken) =>
items.SaveAsync(
new StoredItem(
vaultId,
src/DodoSSH.Client.Sync/SshKeyRepository.cs
+49
View File
@@ -0,0 +1,49 @@
using DodoSSH.Client.Domain;
using DodoSSH.Client.Storage;
namespace DodoSSH.Client.Sync;
/// <summary>
/// The SSH keys in a vault, decrypted, with unpushed local changes laid over them.
/// </summary>
/// <remarks>
/// <para>
/// Identical in shape to <see cref="HostRepository"/> and identical in implementation, because both are
/// facades over the same generic repository. The only thing that differs is the item kind, and with it
/// the cipher, the merge, and the fact that a key sends the server no plaintext columns at all.
/// </para>
/// <para>
/// <b>A key listed here has its private key in memory.</b> Listing is not a cheap metadata read: it
/// decrypts every key in the vault, so the caller holds the material for as long as it holds the listing.
/// That is the same bargain <see cref="HostRepository"/> makes for passwords in notes and the reason
/// <c>SshKeySecret</c> documents what managed strings do and do not give you — but it is worth stating
/// where the decryption actually happens, which is here.
/// </para>
/// </remarks>
public sealed class SshKeyRepository(ItemStore items, OutboxStore outbox, VaultKeyring keyring)
{
private readonly VaultItemRepository<SshKeySecret> keys =
new(SshKeyKind.Instance, items, outbox, keyring);
/// <inheritdoc cref="VaultItemRepository{TSecret}.ListAsync" />
public Task<ItemListing<SshKeySecret>> ListAsync(
Guid vaultId,
CancellationToken cancellationToken) =>
keys.ListAsync(vaultId, cancellationToken);
/// <inheritdoc cref="VaultItemRepository{TSecret}.CreateAsync" />
public Task<Guid> CreateAsync(Guid vaultId, SshKeySecret key, CancellationToken cancellationToken) =>
keys.CreateAsync(vaultId, key, cancellationToken);
/// <inheritdoc cref="VaultItemRepository{TSecret}.UpdateAsync" />
public Task UpdateAsync(
Guid vaultId,
Guid entityId,
SshKeySecret key,
CancellationToken cancellationToken) =>
keys.UpdateAsync(vaultId, entityId, key, cancellationToken);
/// <inheritdoc cref="VaultItemRepository{TSecret}.DeleteAsync" />
public Task DeleteAsync(Guid vaultId, Guid entityId, CancellationToken cancellationToken) =>
keys.DeleteAsync(vaultId, entityId, cancellationToken);
}
src/DodoSSH.Client.Sync/SyncEngine.cs
+43 -43
View File
@@ -33,7 +33,13 @@ public sealed class SyncEngine
private readonly VaultKeyring keyring;
private readonly TimeProvider clock;
private readonly SyncOptions options;
private readonly ItemReconciler reconciler;
/// <remarks>
/// One per synchronised item type, built once. The keys are also the pull filter — see
/// <see cref="ItemKinds"/> — so a type this engine cannot reconcile is never requested, and a type it
/// can reconcile cannot be left out of the request.
/// </remarks>
private readonly Dictionary<SyncEntityType, IItemReconciler> reconcilers;
/// <summary>Creates the engine.</summary>
public SyncEngine(
@@ -63,7 +69,7 @@ public sealed class SyncEngine
this.clock = clock;
this.options = options ?? SyncOptions.Default;
reconciler = new ItemReconciler(items, outbox, conflicts, keyring);
reconcilers = ItemKinds.Reconcilers(outbox, conflicts, keyring);
}
/// <summary>Runs a full pass over one vault.</summary>
@@ -127,7 +133,7 @@ public sealed class SyncEngine
{
var response = await api.SyncPullAsync(
vaultId,
new SyncPullRequest(state.Cursor, options.PullPageSize, [SyncEntityType.Host]),
new SyncPullRequest(state.Cursor, options.PullPageSize, ItemKinds.SyncedTypes),
cancellationToken).ConfigureAwait(false);
foreach (var change in response.Changes)
@@ -187,14 +193,16 @@ public sealed class SyncEngine
SyncReportBuilder report,
CancellationToken cancellationToken)
{
if (change.EntityType != SyncEntityType.Host)
if (!reconcilers.TryGetValue(change.EntityType, out var reconciler))
{
// Reserved in the contract but not yet syncable. Ignoring it keeps a newer server's extra
// entity types from breaking an older client's pull.
// Reserved in the contract but not yet syncable here. The pull filter already asks for only
// the types this build handles, so reaching this means a newer server sent something extra —
// and ignoring it keeps that from breaking an older client's pull. Not mirrored either: a row
// this build can never read is cache with no reader.
return;
}
await reconciler.MirrorAsync(vaultId, change, cancellationToken).ConfigureAwait(false);
await ItemMirror.WriteAsync(items, vaultId, change, cancellationToken).ConfigureAwait(false);
var pending = await outbox
.FindAsync(vaultId, change.EntityType, change.EntityId, cancellationToken)
@@ -394,14 +402,29 @@ public sealed class SyncEngine
return false;
}
if (!reconcilers.TryGetValue(operation.EntityType, out var reconciler))
{
// Only reachable if something queued a type this build does not synchronise, which the
// repositories cannot do. Parked rather than dropped, so the change is visible to a user
// instead of retried for ever against a path that cannot handle it.
await RejectAsync(
vaultId,
operation,
$"This version of DodoSSH cannot reconcile items of type {operation.EntityType}.",
report,
cancellationToken).ConfigureAwait(false);
return false;
}
if (result.ServerEntity is null)
{
// The version check failed but the server has no such row. Re-offer it as a create.
return await RetryAsCreateAsync(vaultId, operation, report, cancellationToken)
return await RetryAsCreateAsync(vaultId, reconciler, operation, report, cancellationToken)
.ConfigureAwait(false);
}
await reconciler.MirrorAsync(vaultId, result.ServerEntity, cancellationToken)
await ItemMirror.WriteAsync(items, vaultId, result.ServerEntity, cancellationToken)
.ConfigureAwait(false);
await reconciler
@@ -413,6 +436,7 @@ public sealed class SyncEngine
private async Task<bool> RetryAsCreateAsync(
Guid vaultId,
IItemReconciler reconciler,
PendingOperation operation,
SyncReportBuilder report,
CancellationToken cancellationToken)
@@ -424,44 +448,20 @@ public sealed class SyncEngine
return false;
}
if (!keyring.TryGet(vaultId, out var vaultKey, out var generation)
|| operation.Payload is null)
// Re-sealing needs the item's own cipher, so the reconciler does it. A reason back means the
// change can never be sent, not that it should be retried.
var failure = await reconciler
.ReofferAsCreateAsync(vaultId, operation, cancellationToken)
.ConfigureAwait(false);
if (failure is null)
{
await RejectAsync(
vaultId, operation, "This item has no usable vault key.", report, cancellationToken)
.ConfigureAwait(false);
return false;
return true;
}
var local = HostCipher.TryOpen(
operation.Payload,
vaultKey.Span,
operation.EntityId,
SyncVersions.NextVersion(operation.ExpectedVersion));
await RejectAsync(vaultId, operation, failure, report, cancellationToken).ConfigureAwait(false);
if (local is null)
{
await RejectAsync(
vaultId,
operation,
"The queued change could not be decrypted, so it could not be re-offered.",
report,
cancellationToken).ConfigureAwait(false);
return false;
}
// Re-sealed at version 1, because that is what the server assigns to a create and the AAD binds
// the version.
await outbox.ReviseAsync(
operation.Sequence,
SyncOperation.Upsert,
expectedVersion: null,
HostCipher.Seal(local.Host, vaultKey.Span, operation.EntityId, generation, itemVersion: 1),
HostFields.From(local.Host),
ancestor: null,
cancellationToken).ConfigureAwait(false);
return true;
return false;
}
/// <summary>Parks an operation the server will never accept, and says why.</summary>
src/DodoSSH.Client.Sync/VaultItemRepository.cs
+317
View File
@@ -0,0 +1,317 @@
using DodoSSH.Client.Domain;
using DodoSSH.Client.Storage;
using DodoSSH.Contracts;
namespace DodoSSH.Client.Sync;
/// <summary>One vault item as the interface should show it.</summary>
/// <param name="EntityId">The item id.</param>
/// <param name="Secret">The decrypted item.</param>
/// <param name="Version">
/// The server version this is based on. Zero for an item that has never been accepted.
/// </param>
/// <param name="HasUnsyncedChanges">
/// Whether this reflects a local edit the server has not accepted yet. Worth showing: it is the
/// difference between "saved" and "saved here".
/// </param>
/// <param name="IsBlocked">
/// Whether the pending change was refused and is waiting on a person, so it will not retry on its own.
/// </param>
/// <param name="IsReadOnly">
/// Whether this item was written by a newer client and so must not be edited here, because re-encoding
/// it would drop fields this build cannot represent.
/// </param>
public sealed record VaultItem<TSecret>(
Guid EntityId,
TSecret Secret,
int Version,
bool HasUnsyncedChanges,
bool IsBlocked,
bool IsReadOnly)
where TSecret : class, IVaultSecret;
/// <summary>The items of one kind in a vault, and what could not be read.</summary>
/// <param name="Items">The readable items.</param>
/// <param name="Unreadable">
/// How many items would not decrypt. Surfaced rather than swallowed: a non-zero count here after a
/// rekey is the signal that new grants are needed.
/// </param>
public sealed record ItemListing<TSecret>(IReadOnlyList<VaultItem<TSecret>> Items, int Unreadable)
where TSecret : class, IVaultSecret;
/// <summary>
/// Reading and writing one kind of vault item, as the interface sees them.
/// </summary>
/// <remarks>
/// <para>
/// The view is the mirror of the server's state with the outbox laid over it, which is what makes the
/// application feel local: an edit appears immediately and a delete disappears immediately, whether or
/// not the network is there. Nothing here talks to the server; the sync engine reconciles later.
/// </para>
/// <para>
/// Writes never touch the mirror. That separation is load-bearing — the mirror is the common ancestor a
/// three-way merge needs, and a repository that updated it on save would destroy the very state that
/// lets a conflict be merged instead of arbitrated.
/// </para>
/// <para>
/// Every read and write is scoped to <see cref="IItemKind{TSecret}.EntityType"/>, which is also what
/// keeps two kinds apart in storage: the item table is keyed on the type as well as the id, so a host and
/// a key could share an id and never see each other's rows.
/// </para>
/// </remarks>
internal sealed class VaultItemRepository<TSecret>(
IItemKind<TSecret> kind,
ItemStore items,
OutboxStore outbox,
VaultKeyring keyring)
where TSecret : class, IVaultSecret
{
/// <summary>Reads every item of this kind the user should see in a vault.</summary>
internal async Task<ItemListing<TSecret>> ListAsync(
Guid vaultId,
CancellationToken cancellationToken)
{
if (!keyring.TryGet(vaultId, out var vaultKey, out _))
{
throw new VaultUnreadableException(vaultId);
}
var mirrored = await items
.ListAsync(vaultId, kind.EntityType, includeDeleted: true, cancellationToken)
.ConfigureAwait(false);
var pending = await outbox.ListAllAsync(vaultId, cancellationToken).ConfigureAwait(false);
var pendingByEntity = pending
.Where(operation => operation.EntityType == kind.EntityType)
.ToDictionary(operation => operation.EntityId);
var listed = new List<VaultItem<TSecret>>();
var unreadable = 0;
foreach (var item in mirrored)
{
if (pendingByEntity.Remove(item.EntityId, out var local))
{
AddPending(listed, ref unreadable, vaultKey, local);
continue;
}
if (item.IsDeleted || item.Payload is null)
{
continue;
}
var opened = kind.TryOpen(item.Payload, vaultKey.Span, item.EntityId, item.Version);
if (opened is null)
{
unreadable++;
continue;
}
listed.Add(new VaultItem<TSecret>(
item.EntityId, opened.Secret, item.Version, false, false, opened.IsReadOnly));
}
// Whatever is left has no mirror row yet: items created here and not yet accepted.
foreach (var local in pendingByEntity.Values)
{
AddPending(listed, ref unreadable, vaultKey, local);
}
return new ItemListing<TSecret>(listed, unreadable);
}
/// <summary>
/// Adds an item, returning the id it was given.
/// </summary>
/// <remarks>
/// The id is generated here, not by the server, which is what lets an item be created with no network
/// at all — the point of the whole outbox. UUIDv7 so that ids sort by creation time, which keeps
/// index locality reasonable on the server side.
/// </remarks>
internal async Task<Guid> CreateAsync(
Guid vaultId,
TSecret secret,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(secret);
Validate(secret);
var (vaultKey, generation) = Key(vaultId);
var entityId = Guid.CreateVersion7();
await outbox.QueueAsync(
new QueuedChange(
vaultId,
kind.EntityType,
entityId,
SyncOperation.Upsert,
ExpectedVersion: null,
kind.Seal(secret, vaultKey.Span, entityId, generation, itemVersion: 1),
kind.Fields(secret),
Ancestor: null),
cancellationToken).ConfigureAwait(false);
return entityId;
}
/// <summary>
/// Replaces an item's contents.
/// </summary>
/// <remarks>
/// The base is taken from the pending operation when there is one, and from the mirror otherwise.
/// Reading it the other way round would seal the payload at a version that does not match the
/// <c>expectedVersion</c> the coalesced row keeps — and because the AAD binds the item version, the
/// result would encrypt cleanly and never decrypt again.
/// </remarks>
internal async Task UpdateAsync(
Guid vaultId,
Guid entityId,
TSecret secret,
CancellationToken cancellationToken)
{
ArgumentNullException.ThrowIfNull(secret);
Validate(secret);
var (vaultKey, generation) = Key(vaultId);
var pending = await outbox
.FindAsync(vaultId, kind.EntityType, entityId, cancellationToken)
.ConfigureAwait(false);
var expectedVersion = pending is not null
? pending.ExpectedVersion
: await MirrorVersionAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
var ancestor = pending?.Ancestor
?? await MirrorAncestorAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
await outbox.QueueAsync(
new QueuedChange(
vaultId,
kind.EntityType,
entityId,
SyncOperation.Upsert,
expectedVersion,
kind.Seal(
secret,
vaultKey.Span,
entityId,
generation,
SyncVersions.NextVersion(expectedVersion)),
kind.Fields(secret),
ancestor),
cancellationToken).ConfigureAwait(false);
}
/// <summary>
/// Deletes an item.
/// </summary>
/// <remarks>
/// Queued as a tombstone, never a local removal. An offline client that simply forgot the row would
/// be unable to tell the server anything, and the item would come back on the next pull.
/// </remarks>
internal async Task DeleteAsync(Guid vaultId, Guid entityId, CancellationToken cancellationToken)
{
var pending = await outbox
.FindAsync(vaultId, kind.EntityType, entityId, cancellationToken)
.ConfigureAwait(false);
var expectedVersion = pending is not null
? pending.ExpectedVersion
: await MirrorVersionAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
var ancestor = pending?.Ancestor
?? await MirrorAncestorAsync(vaultId, entityId, cancellationToken).ConfigureAwait(false);
await outbox.QueueAsync(
new QueuedChange(
vaultId,
kind.EntityType,
entityId,
SyncOperation.Delete,
expectedVersion,
Payload: null,
Fields: null,
ancestor),
cancellationToken).ConfigureAwait(false);
}
private static void Validate(TSecret secret)
{
if (!secret.TryValidate(out var error))
{
throw new ArgumentException(error, nameof(secret));
}
}
private void AddPending(
List<VaultItem<TSecret>> listed,
ref int unreadable,
ReadOnlyMemory<byte> vaultKey,
PendingOperation local)
{
if (local.Operation == SyncOperation.Delete)
{
// Gone as far as this machine is concerned, even before the server agrees.
return;
}
if (local.Payload is null)
{
unreadable++;
return;
}
var version = SyncVersions.NextVersion(local.ExpectedVersion);
var opened = kind.TryOpen(local.Payload, vaultKey.Span, local.EntityId, version);
if (opened is null)
{
unreadable++;
return;
}
listed.Add(new VaultItem<TSecret>(
local.EntityId,
opened.Secret,
local.ExpectedVersion ?? 0,
HasUnsyncedChanges: true,
local.IsParked,
opened.IsReadOnly));
}
private (ReadOnlyMemory<byte> VaultKey, uint Generation) Key(Guid vaultId) =>
keyring.TryGet(vaultId, out var vaultKey, out var generation)
? (vaultKey, generation)
: throw new VaultUnreadableException(vaultId);
private async Task<int?> MirrorVersionAsync(
Guid vaultId,
Guid entityId,
CancellationToken cancellationToken)
{
var item = await items
.FindAsync(vaultId, kind.EntityType, entityId, cancellationToken)
.ConfigureAwait(false);
// A null means the server has never seen this item, which is exactly what "create" is.
return item?.Version;
}
private async Task<StoredAncestor?> MirrorAncestorAsync(
Guid vaultId,
Guid entityId,
CancellationToken cancellationToken)
{
var item = await items
.FindAsync(vaultId, kind.EntityType, entityId, cancellationToken)
.ConfigureAwait(false);
return item?.Payload is null
? null
: new StoredAncestor(item.Version, item.Payload, item.Fields);
}
}