Skip to content

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

Refactor one-time AK migration flow (#2159)

Leendert de Borstf5e1d1274db5
diff --git a/apps/browser-extension/src/utils/VaultSyncService.ts b/apps/browser-extension/src/utils/VaultSyncService.ts
index e0adcefbb..4d72dfa64 100644
--- a/apps/browser-extension/src/utils/VaultSyncService.ts
+++ b/apps/browser-extension/src/utils/VaultSyncService.ts
@@ -307,7 +307,6 @@ type ManifestWriteDto = {
currentRevision: number;
credentialsCount: number;
blobReferences: BlobRefDto[];
- encryptedVek?: string;
encryptionPublicKey?: string;
};
@@ -1390,11 +1389,6 @@ export class VaultSyncService {
currentRevision: candidate.currentRevision,
credentialsCount: (candidate.manifest.tables.Items ?? []).length,
blobReferences: Object.entries(candidate.blobs).map(([hash, blob]) => ({ hash, category: blob.kind })),
- /*
- * Set only on the KEK/VEK migration push, where the server creates the vault key alongside this personal-manifest revision.
- * A migration always forces a personal-manifest write (see the gate above), so the key can never be stranded without one.
- */
- ...(candidate.isPersonal && migration ? { encryptedVek: migration.encryptedVek } : {}),
...(manifestKey ? { encryptionPublicKey: manifestKey.PublicKey } : {}),
});
writtenManifestFingerprints[candidate.manifestId] = fingerprint;
@@ -1455,7 +1449,7 @@ export class VaultSyncService {
buckets: bucketDtos,
newBlobs: [] as BlobDto[],
emailRouting,
- // LEGACY: only the one-time KEK/VEK migration push carries a key hierarchy for the server to store.
+ // Legacy: only the one-time KEK/VEK migration push carries a key hierarchy for the server to store.
accountKeys: migration?.accountKeys ?? null,
};
diff --git a/apps/browser-extension/src/utils/legacy/LegacyStorageModelMigration.ts b/apps/browser-extension/src/utils/legacy/LegacyStorageModelMigration.ts
index aa28ae7de..8ba03f511 100644
--- a/apps/browser-extension/src/utils/legacy/LegacyStorageModelMigration.ts
+++ b/apps/browser-extension/src/utils/legacy/LegacyStorageModelMigration.ts
@@ -174,12 +174,12 @@ export function legacyUnstampedRowAdoption(personalManifestId: string): { adoptU
export type LegacyAccountKeyMigration = {
/** The new VEK: everything this push writes is encrypted with it, and the caller adopts it as the session key. */
contentKey: string;
- /** The new VEK encrypted with the Account Key; sent on the personal-manifest write so the server stores it. */
- encryptedVek: string;
- /** The rest of the hierarchy, sent as-is in the write payload. */
+ /** The whole hierarchy, sent as-is in the write payload. */
accountKeys: {
/** The Account Key encrypted with the password-derived KEK. */
encryptedAccountKey: string;
+ /** The new VEK encrypted with the Account Key. */
+ encryptedVek: string;
/** Public half of the new account keypair, used by others to grant this user access to a shared manifest. */
accountPublicKey: string;
/** Private half of the new account keypair, encrypted with the Account Key. */
@@ -210,9 +210,9 @@ export async function prepareLegacyAccountKeyMigration(kek: string): Promise<Leg
return {
contentKey,
- encryptedVek: await EncryptionUtility.encryptVaultEncryptionKey(contentKey, accountKey),
accountKeys: {
encryptedAccountKey: await EncryptionUtility.encryptVaultEncryptionKey(accountKey, kek),
+ encryptedVek: await EncryptionUtility.encryptVaultEncryptionKey(contentKey, accountKey),
accountPublicKey: accountKeyPair.publicKey,
encryptedAccountPrivateKey: await EncryptionUtility.symmetricEncrypt(accountKeyPair.privateKey, accountKey),
},
@@ -226,11 +226,5 @@ export async function prepareLegacyAccountKeyMigration(kek: string): Promise<Leg
* @param migration - the hierarchy that was pushed
*/
export async function completeLegacyAccountKeyMigration(migration: LegacyAccountKeyMigration): Promise<void> {
- await VaultKeyService.adoptLocalAccountKeys({
- encryptedAccountKey: migration.accountKeys.encryptedAccountKey,
- encryptedVek: migration.encryptedVek,
- accountPublicKey: migration.accountKeys.accountPublicKey,
- encryptedAccountPrivateKey: migration.accountKeys.encryptedAccountPrivateKey,
- accountPrivateKey: migration.accountPrivateKey,
- });
+ await VaultKeyService.adoptLocalAccountKeys({ ...migration.accountKeys, accountPrivateKey: migration.accountPrivateKey });
}
diff --git a/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs b/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs
index f201d887d..ef6fcb935 100644
--- a/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs
+++ b/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs
@@ -318,34 +318,27 @@ public class VaultController(
// The caller's own manifest is the one owned by their personal group; a personal group owns no other.
var personalWrite = resolved.FirstOrDefault(r => r.Row.OwnerGroupId == user.PersonalGroupId).Write;
- /*
- * Account-key migration: when writing the personal manifest the first time, the client needs to generate a VEK,
- * encrypt it with the AccountKey, and store it in the personal manifest. AccountKeys blobs (KEK-encrypted AK + AK-encrypted account keypair).
- * A shared-manifest write must never carry one. We reject rather than silently ignore, so a misdirected key can never be dropped unnoticed.
- * TODO: these guards can be removed once all users have migrated and we don't support legacy users anymore.
- */
- if (resolved.Any(r => r.Row.OwnerGroupId != user.PersonalGroupId && !string.IsNullOrEmpty(r.Write.EncryptedVek)))
- {
- return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_NOT_FOUND, 400));
- }
-
- var migrationEncryptedVek = personalWrite?.EncryptedVek;
+ // Account-key migration: a legacy vault's first manifest-v1 push includes a newly created Account Key hierarchy,
+ var accountKeys = model.AccountKeys;
var hasExistingUnlockKey = await context.UserUnlockKeys.AnyAsync(x => x.UserId == user.Id && x.Type == UnlockMethodType.Password);
- if (!string.IsNullOrEmpty(migrationEncryptedVek) && hasExistingUnlockKey)
+ if (accountKeys != null)
{
- return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_ALREADY_EXISTS, 400));
- }
+ if (hasExistingUnlockKey)
+ {
+ return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_ALREADY_EXISTS, 400));
+ }
- // A personal-manifest push from a not-yet-migrated user must carry the encrypted VEK to migrate the vault into the manifest-v1 format.
- if (personalWrite != null && string.IsNullOrEmpty(migrationEncryptedVek) && !hasExistingUnlockKey)
- {
- return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_NOT_FOUND, 400));
- }
+ if (personalWrite == null || !accountKeys.IsComplete)
+ {
+ return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_NOT_FOUND, 400));
+ }
- // The migration VEK and the account-key blobs only make sense together: the VEK is encrypted under the AK.
- var accountKeys = model.AccountKeys;
- var accountKeysComplete = accountKeys != null && !string.IsNullOrEmpty(accountKeys.EncryptedAccountKey) && !string.IsNullOrEmpty(accountKeys.AccountPublicKey) && !string.IsNullOrEmpty(accountKeys.EncryptedAccountPrivateKey);
- if (!string.IsNullOrEmpty(migrationEncryptedVek) && !accountKeysComplete)
+ if (!accountKeys.FitsStorageLimits)
+ {
+ return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_ERROR, 400));
+ }
+ }
+ else if (personalWrite != null && !hasExistingUnlockKey)
{
return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_NOT_FOUND, 400));
}
@@ -383,7 +376,7 @@ public class VaultController(
// 1) Upsert any new blob objects.
if (model.NewBlobs.Count > 0)
{
- if (!await TryUpsertBlobObjectsAsync(context, user.Id, model.NewBlobs, overwrite: !string.IsNullOrEmpty(migrationEncryptedVek)))
+ if (!await TryUpsertBlobObjectsAsync(context, user.Id, model.NewBlobs, overwrite: accountKeys != null))
{
await tx.RollbackAsync();
return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_NOT_UP_TO_DATE, 400));
@@ -453,16 +446,23 @@ public class VaultController(
row.CreatedAt = timeProvider.UtcNow;
// Create the account-key hierarchy atomically with this write on the migration (first push after
- // the client re-encrypted the vault under a fresh VEK). Move the SRP credentials off the manifest row.
- if (!string.IsNullOrEmpty(migrationEncryptedVek))
+ // the client re-encrypted the vault under a fresh VEK).
+ if (accountKeys != null)
{
+ // Check if the user already has an unlock key: if so, reject the write.
+ if (await context.UserUnlockKeys.AnyAsync(x => x.UserId == user.Id && x.Type == UnlockMethodType.Password))
+ {
+ await tx.RollbackAsync();
+ return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_ALREADY_EXISTS, 400));
+ }
+
context.UserUnlockKeys.Add(new UserUnlockKey
{
Id = Guid.NewGuid(),
UserId = user.Id,
Type = UnlockMethodType.Password,
Algorithm = VaultKeyAlgorithm.Aes256Gcm,
- EncryptedAccountKey = accountKeys!.EncryptedAccountKey!,
+ EncryptedAccountKey = accountKeys.EncryptedAccountKey!,
Metadata = new VaultKeyMetadata
{
Salt = row.Salt,
@@ -493,7 +493,7 @@ public class VaultController(
VaultManifestId = row.ManifestId,
Type = ManifestKeyType.AccountKey,
Algorithm = VaultKeyAlgorithm.Aes256Gcm,
- EncryptedVek = migrationEncryptedVek,
+ EncryptedVek = accountKeys.EncryptedVek!,
AccountKeyVersion = 0,
CreatedAt = timeProvider.UtcNow,
UpdatedAt = timeProvider.UtcNow,
@@ -510,7 +510,17 @@ public class VaultController(
manifestResults.Add(new ManifestWriteResult { ManifestId = mw.ManifestId, Revision = row.RevisionNumber });
}
- await context.SaveChangesAsync();
+ try
+ {
+ await context.SaveChangesAsync();
+ }
+ catch (DbUpdateException) when (accountKeys != null)
+ {
+ // A concurrent migration push won the race between the re-check above and this insert. Nothing was committed, so the client retries.
+ // TODO: remove once all users have migrated and we don't support legacy users anymore.
+ await tx.RollbackAsync();
+ return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_ALREADY_EXISTS, 400));
+ }
// 4) Add blob references for each manifest's new revision.
foreach (var (mw, row) in resolved)
diff --git a/apps/server/Databases/AliasServerDb/VaultManifestBase.cs b/apps/server/Databases/AliasServerDb/VaultManifestBase.cs
index 7b2e686bb..e8a4ee68e 100644
--- a/apps/server/Databases/AliasServerDb/VaultManifestBase.cs
+++ b/apps/server/Databases/AliasServerDb/VaultManifestBase.cs
@@ -19,6 +19,16 @@ using System.ComponentModel.DataAnnotations;
/// </summary>
public abstract class VaultManifestBase : IVaultRevision
{
+ /// <summary>
+ /// The legacy storage format, where the whole vault is one blob encrypted with the password-derived key.
+ /// </summary>
+ public const string LegacyStorageFormat = "sqlite-blob";
+
+ /// <summary>
+ /// The current storage format, where the vault is an encrypted manifest plus data buckets.
+ /// </summary>
+ public const string ManifestStorageFormat = "manifest-v1";
+
/// <summary>
/// Gets or sets the encrypted vault blob. Only the legacy sqlite-blob format populates this; on manifest-v1
/// revisions it is null. TODO: remove this column once the legacy model is fully deprecated.
diff --git a/apps/server/Services/AliasVault.TaskRunner/Program.cs b/apps/server/Services/AliasVault.TaskRunner/Program.cs
index ba9015db9..1a2eeec70 100644
--- a/apps/server/Services/AliasVault.TaskRunner/Program.cs
+++ b/apps/server/Services/AliasVault.TaskRunner/Program.cs
@@ -35,6 +35,7 @@ builder.Services.AddTransient<IMaintenanceTask, EmailCleanupTask>();
builder.Services.AddTransient<IMaintenanceTask, EmailQuotaCleanupTask>();
builder.Services.AddTransient<IMaintenanceTask, DisabledEmailCleanupTask>();
builder.Services.AddTransient<IMaintenanceTask, OrphanedEmailCleanupTask>();
+builder.Services.AddTransient<IMaintenanceTask, UnlockKeyHistoryCleanupTask>();
builder.Services.AddStatusHostedService<TaskRunnerWorker, AliasServerDbContext>(Assembly.GetExecutingAssembly().GetName().Name!);
diff --git a/apps/server/Services/AliasVault.TaskRunner/Tasks/UnlockKeyHistoryCleanupTask.cs b/apps/server/Services/AliasVault.TaskRunner/Tasks/UnlockKeyHistoryCleanupTask.cs
new file mode 100644
index 000000000..59cb3fffb
--- /dev/null
+++ b/apps/server/Services/AliasVault.TaskRunner/Tasks/UnlockKeyHistoryCleanupTask.cs
@@ -0,0 +1,58 @@
+//-----------------------------------------------------------------------
+// <copyright file="UnlockKeyHistoryCleanupTask.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.TaskRunner.Tasks;
+
+using AliasServerDb;
+using AliasVault.Shared.Server.Services;
+
+/// <summary>
+/// A maintenance task that deletes archived unlock keys which have fallen outside the retention window.
+///
+/// This is the backstop, not the guarantee: the task runs once a day at the configured maintenance time, so the
+/// consumers of the archive apply the same window themselves and an expired row is already unusable before this
+/// task gets to remove it.
+/// </summary>
+public class UnlockKeyHistoryCleanupTask : IMaintenanceTask
+{
+ private readonly ILogger<UnlockKeyHistoryCleanupTask> _logger;
+ private readonly IAliasServerDbContextFactory _dbContextFactory;
+ private readonly ServerSettingsService _settingsService;
+
+ /// <summary>
+ /// Initializes a new instance of the <see cref="UnlockKeyHistoryCleanupTask"/> class.
+ /// </summary>
+ /// <param name="logger">The logger.</param>
+ /// <param name="dbContextFactory">The database context factory.</param>
+ /// <param name="settingsService">The server settings service.</param>
+ public UnlockKeyHistoryCleanupTask(
+ ILogger<UnlockKeyHistoryCleanupTask> logger,
+ IAliasServerDbContextFactory dbContextFactory,
+ ServerSettingsService settingsService)
+ {
+ _logger = logger;
+ _dbContextFactory = dbContextFactory;
+ _settingsService = settingsService;
+ }
+
+ /// <inheritdoc />
+ public string Name => "Unlock Key History Cleanup";
+
+ /// <inheritdoc />
+ public async Task ExecuteAsync(CancellationToken cancellationToken)
+ {
+ var settings = await _settingsService.GetAllSettingsAsync();
+ await using var dbContext = await _dbContextFactory.CreateDbContextAsync(cancellationToken);
+
+ var deletedCount = await UnlockKeyHistoryPolicy.DeleteExpiredAsync(dbContext.UserUnlockKeysHistory, settings.UnlockKeyHistoryRetentionDays, DateTime.UtcNow, cancellationToken);
+
+ if (deletedCount > 0)
+ {
+ _logger.LogInformation("Deleted {Count} archived unlock keys older than {Days} days", deletedCount, UnlockKeyHistoryPolicy.EffectiveRetentionDays(settings.UnlockKeyHistoryRetentionDays));
+ }
+ }
+}
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/AccountKeysUpload.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/AccountKeysUpload.cs
index d49b05fe1..1be9190d4 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/AccountKeysUpload.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/AccountKeysUpload.cs
@@ -8,16 +8,39 @@
namespace AliasVault.Shared.Models.WebApi.V2.Vault;
/// <summary>
-/// Upload request for the encrypted Account Key and KEK derivation parameters for the given unlock method.
+/// One-time migration push for a legacy vault to the manifest-v1 format: an Account Key encrypted with the password-derived KEK.
+/// TODO: remove once the legacy sqlite-blob format is fully deprecated and we don't support legacy users anymore.
/// </summary>
public class AccountKeysUpload
{
+ /// <summary>Maximum accepted length of <see cref="EncryptedAccountKey"/> and <see cref="EncryptedVek"/>.</summary>
+ public const int MaxWrappedKeyLength = 255;
+
+ /// <summary>Maximum accepted length of <see cref="AccountPublicKey"/>.</summary>
+ public const int MaxPublicKeyLength = 2000;
+
+ /// <summary>Maximum accepted length of <see cref="EncryptedAccountPrivateKey"/>.</summary>
+ public const int MaxEncryptedPrivateKeyLength = 4000;
+
/// <summary>Gets or sets the Account Key encrypted with the KEK derived from the unlock method.</summary>
public string? EncryptedAccountKey { get; set; }
- /// <summary>Gets or sets the encrypted VEK.</summary>
+ /// <summary>Gets or sets the vault encryption key encrypted with the Account Key, as base64(IV | ciphertext | authTag).</summary>
+ public string? EncryptedVek { get; set; }
+
+ /// <summary>Gets or sets the public half (JWK) of the account keypair, which others encrypt shared-manifest grants for this user with.</summary>
public string? AccountPublicKey { get; set; }
/// <summary>Gets or sets the account private key encrypted with the Account Key.</summary>
public string? EncryptedAccountPrivateKey { get; set; }
+
+ /// <summary>
+ /// Gets a value indicating whether all four fields are present. A partial upload is not usable.
+ /// </summary>
+ public bool IsComplete => !string.IsNullOrEmpty(EncryptedAccountKey) && !string.IsNullOrEmpty(EncryptedVek) && !string.IsNullOrEmpty(AccountPublicKey) && !string.IsNullOrEmpty(EncryptedAccountPrivateKey);
+
+ /// <summary>
+ /// Gets a value indicating whether every field fits its storage column, so an oversized value is a validation error instead of a database exception.
+ /// </summary>
+ public bool FitsStorageLimits => (EncryptedAccountKey?.Length ?? 0) <= MaxWrappedKeyLength && (EncryptedVek?.Length ?? 0) <= MaxWrappedKeyLength && (AccountPublicKey?.Length ?? 0) <= MaxPublicKeyLength && (EncryptedAccountPrivateKey?.Length ?? 0) <= MaxEncryptedPrivateKeyLength;
}
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/ManifestWrite.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/ManifestWrite.cs
index cbed9b748..e3b325598 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/ManifestWrite.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/ManifestWrite.cs
@@ -1,4 +1,4 @@
-//-----------------------------------------------------------------------
+//-----------------------------------------------------------------------
// <copyright file="ManifestWrite.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.
@@ -35,13 +35,4 @@ public class ManifestWrite
/// Gets or sets the public half of this manifest's active RSA key pair (used to e.g. encrypt incoming emails).
/// </summary>
public string? EncryptionPublicKey { get; set; }
-
- /// <summary>
- /// Gets or sets the encrypted VEK of the vault encryption key encrypted with the password-derived KEK using AES-256-GCM.
- /// Set on the legacy user's first manifest-v1 write, where the client re-encrypts the whole vault under a fresh VEK;
- /// the server creates the password VaultKey for this manifest in the same transaction. Null on every subsequent write.
- /// Only valid on the write targeting the caller's personal manifest; a shared-manifest write carrying it is rejected rather than silently ignored.
- /// TODO: remove once the legacy sqlite-blob format is fully deprecated and we don't support legacy users anymore.
- /// </summary>
- public string? EncryptedVek { get; set; } // base64(IV | ciphertext | authTag)
}
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultWriteRequest.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultWriteRequest.cs
index ce19f183c..e9c961db1 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultWriteRequest.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultWriteRequest.cs
@@ -28,7 +28,7 @@ public class VaultWriteRequest
public EmailRoutingPush? EmailRouting { get; set; }
/// <summary>
- /// Gets or sets the encrypted Account Key and KEK derivation parameters for the given unlock method.
+ /// Gets or sets a newly created account key hierarchy. Only sent for the one-time legacy vault's migration push (pre-0.31.0).
/// </summary>
public AccountKeysUpload? AccountKeys { get; set; }
}