Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add VaultSync models for canonicalize server push (#2159)

Leendert de Borst2bd2460e5fc0
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Exceptions/VaultTooLargeException.cs b/apps/server/AliasVault.Client/Services/VaultSync/Exceptions/VaultTooLargeException.cs
new file mode 100644
index 000000000..7a1b3e35d
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Exceptions/VaultTooLargeException.cs
@@ -0,0 +1,22 @@
+//-----------------------------------------------------------------------
+// <copyright file="VaultTooLargeException.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Exceptions;
+
+/// <summary>
+/// The server (or a reverse proxy in front of it) refused an upload because the request body exceeds its configured maximum.
+/// </summary>
+public sealed class VaultTooLargeException : Exception
+{
+ /// <summary>
+ /// Initializes a new instance of the <see cref="VaultTooLargeException"/> class.
+ /// </summary>
+ public VaultTooLargeException()
+ : base("The upload was rejected with HTTP 413 Request Entity Too Large.")
+ {
+ }
+}
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/AccountKeyHierarchy.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/AccountKeyHierarchy.cs
new file mode 100644
index 000000000..792c6530d
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/AccountKeyHierarchy.cs
@@ -0,0 +1,18 @@
+//-----------------------------------------------------------------------
+// <copyright file="AccountKeyHierarchy.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+using AliasVault.Shared.Models.WebApi.V2.Vault;
+
+/// <summary>
+/// A newly created account key hierarchy: the plaintext keys this session adopts and the wrapped chain the server stores.
+/// </summary>
+/// <param name="VaultEncryptionKey">The new VEK (base64), which becomes the session key.</param>
+/// <param name="AccountPrivateKey">The private half of the new account keypair as a JWK JSON string.</param>
+/// <param name="Keys">The wrapped chain, sent as-is on registration or the migration push.</param>
+public sealed record AccountKeyHierarchy(string VaultEncryptionKey, string AccountPrivateKey, AccountKeysUpload Keys);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedBlob.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedBlob.cs
new file mode 100644
index 000000000..be303819e
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedBlob.cs
@@ -0,0 +1,15 @@
+//-----------------------------------------------------------------------
+// <copyright file="CanonicalizedBlob.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// A blob the codec extracted while canonicalizing: its kind and plaintext bytes.
+/// </summary>
+/// <param name="Kind">The blob kind (favicon or attachment).</param>
+/// <param name="Bytes">The plaintext bytes.</param>
+internal sealed record CanonicalizedBlob(string Kind, byte[] Bytes);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedBucket.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedBucket.cs
new file mode 100644
index 000000000..0765ce864
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedBucket.cs
@@ -0,0 +1,16 @@
+//-----------------------------------------------------------------------
+// <copyright file="CanonicalizedBucket.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// One data bucket the codec produced.
+/// </summary>
+/// <param name="ManifestId">The manifest that owns the bucket.</param>
+/// <param name="Category">The bucket category name.</param>
+/// <param name="BucketJson">The bucket payload JSON.</param>
+internal sealed record CanonicalizedBucket(Guid ManifestId, string Category, string BucketJson);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedManifest.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedManifest.cs
new file mode 100644
index 000000000..d1eb4cc53
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedManifest.cs
@@ -0,0 +1,17 @@
+//-----------------------------------------------------------------------
+// <copyright file="CanonicalizedManifest.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// One manifest the codec produced, matched to the record it was written for.
+/// </summary>
+/// <param name="Record">The manifest record.</param>
+/// <param name="ManifestJson">The manifest payload JSON.</param>
+/// <param name="ItemCount">The number of Items rows the manifest carries.</param>
+/// <param name="Blobs">The blobs the manifest references, keyed by hash.</param>
+internal sealed record CanonicalizedManifest(ManifestRecord Record, string ManifestJson, int ItemCount, Dictionary<string, CanonicalizedBlob> Blobs);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedVault.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedVault.cs
new file mode 100644
index 000000000..684b0f1cc
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/CanonicalizedVault.cs
@@ -0,0 +1,15 @@
+//-----------------------------------------------------------------------
+// <copyright file="CanonicalizedVault.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// The local vault in manifest-v1 form: one manifest per record, personal first, plus the data buckets.
+/// </summary>
+/// <param name="Manifests">The manifests, personal first.</param>
+/// <param name="Buckets">The data buckets.</param>
+internal sealed record CanonicalizedVault(List<CanonicalizedManifest> Manifests, List<CanonicalizedBucket> Buckets);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/ManifestRecord.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/ManifestRecord.cs
new file mode 100644
index 000000000..c460bd1cd
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/ManifestRecord.cs
@@ -0,0 +1,19 @@
+//-----------------------------------------------------------------------
+// <copyright file="ManifestRecord.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// One manifest this vault can write, as resolved before canonicalizing. The personal manifest comes first.
+/// </summary>
+/// <param name="ManifestId">The manifest id.</param>
+/// <param name="IsPersonal">Whether this is the caller's own manifest.</param>
+/// <param name="Salt">The salt this manifest's blob hashes are derived with.</param>
+/// <param name="VaultEncryptionKey">The key this manifest encrypts with (base64).</param>
+/// <param name="Name">The display name written into the manifest; null for the personal manifest.</param>
+/// <param name="CanAdminister">Whether the caller may publish this manifest's email delivery key.</param>
+internal sealed record ManifestRecord(Guid ManifestId, bool IsPersonal, string Salt, string VaultEncryptionKey, string? Name, bool CanAdminister);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/PullAndMergeResult.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/PullAndMergeResult.cs
new file mode 100644
index 000000000..12265c0be
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/PullAndMergeResult.cs
@@ -0,0 +1,53 @@
+//-----------------------------------------------------------------------
+// <copyright file="PullAndMergeResult.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+using Microsoft.Data.Sqlite;
+
+/// <summary>
+/// What a pull-and-merge turned out to be.
+/// </summary>
+public enum PullAndMergeKind
+{
+ /// <summary>
+ /// The local vault was merged onto the server vault; <see cref="PullAndMergeResult.Database"/> holds the result.
+ /// </summary>
+ Merged,
+
+ /// <summary>
+ /// The server holds nothing to merge with (still the legacy sqlite-blob format, or a never-written manifest);
+ /// the local vault is pushed over it whole.
+ /// </summary>
+ NothingToMergeWith,
+}
+
+/// <summary>
+/// Result of a pull-and-merge.
+/// </summary>
+public sealed class PullAndMergeResult
+{
+ /// <summary>
+ /// Gets what the pull-and-merge produced.
+ /// </summary>
+ public required PullAndMergeKind Kind { get; init; }
+
+ /// <summary>
+ /// Gets the merged in-memory database. Set only for <see cref="PullAndMergeKind.Merged"/>; the caller owns it.
+ /// </summary>
+ public SqliteConnection? Database { get; init; }
+
+ /// <summary>
+ /// Gets the manifests whose local changes were dropped because the merged result failed validation.
+ /// </summary>
+ public List<Guid> FallbackManifestIds { get; init; } = [];
+
+ /// <summary>
+ /// Gets the local manifests the server no longer serves; their rows are gone from the merged vault.
+ /// </summary>
+ public List<Guid> DroppedLocalManifestIds { get; init; } = [];
+}
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/PullResult.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/PullResult.cs
index d832aa9b2..3b4395eca 100644
--- a/apps/server/AliasVault.Client/Services/VaultSync/Models/PullResult.cs
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/PullResult.cs
@@ -33,9 +33,4 @@ public sealed class PullResult
/// Gets the legacy data-model version string. Set only for <see cref="PullKind.LegacySqliteBlob"/>.
/// </summary>
public string? LegacyVersion { get; init; }
-
- /// <summary>
- /// Gets the revision of the personal manifest (or of the legacy blob).
- /// </summary>
- public required long Revision { get; init; }
}
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/PushOptions.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/PushOptions.cs
new file mode 100644
index 000000000..64e4142ea
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/PushOptions.cs
@@ -0,0 +1,15 @@
+//-----------------------------------------------------------------------
+// <copyright file="PushOptions.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// How a push writes.
+/// </summary>
+/// <param name="CreateVaultKey">Create the account key hierarchy as part of this push (the one-time legacy migration).</param>
+/// <param name="ForceFullWrite">Rewrite every manifest and bucket regardless of the content fingerprints.</param>
+public sealed record PushOptions(bool CreateVaultKey = false, bool ForceFullWrite = false);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/PushResult.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/PushResult.cs
new file mode 100644
index 000000000..f3f96b317
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/PushResult.cs
@@ -0,0 +1,15 @@
+//-----------------------------------------------------------------------
+// <copyright file="PushResult.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// Result of a push. Revision, fingerprint and blob bookkeeping happens inside the push; callers act on the status.
+/// </summary>
+/// <param name="Status">The outcome.</param>
+/// <param name="Reasons">What went wrong, for the log.</param>
+public sealed record PushResult(PushStatus Status, IReadOnlyList<string>? Reasons = null);
diff --git a/apps/server/AliasVault.Client/Services/VaultSync/Models/PushStatus.cs b/apps/server/AliasVault.Client/Services/VaultSync/Models/PushStatus.cs
new file mode 100644
index 000000000..404ff97e8
--- /dev/null
+++ b/apps/server/AliasVault.Client/Services/VaultSync/Models/PushStatus.cs
@@ -0,0 +1,34 @@
+//-----------------------------------------------------------------------
+// <copyright file="PushStatus.cs" company="aliasvault">
+// Copyright (c) aliasvault. All rights reserved.
+// Licensed under the AGPLv3 license. See LICENSE.md file in the project root for full license information.
+// </copyright>
+//-----------------------------------------------------------------------
+
+namespace AliasVault.Client.Services.VaultSync.Models;
+
+/// <summary>
+/// Outcome of a push.
+/// </summary>
+public enum PushStatus
+{
+ /// <summary>
+ /// Every changed manifest and bucket was written, or nothing had changed.
+ /// </summary>
+ Ok,
+
+ /// <summary>
+ /// The server holds newer state (or the vault holds rows this session cannot write); pull, merge and retry.
+ /// </summary>
+ Outdated,
+
+ /// <summary>
+ /// The server still reports blobs missing after they were re-uploaded once.
+ /// </summary>
+ MissingBlobs,
+
+ /// <summary>
+ /// The vault failed structural validation and was not uploaded.
+ /// </summary>
+ Rejected,
+}