Skip to content

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

Refactor (#2159)

Leendert de Borst1558f40fc081
diff --git a/apps/browser-extension/src/utils/VaultSyncService.ts b/apps/browser-extension/src/utils/VaultSyncService.ts
index 5e7d54512..e85bea302 100644
--- a/apps/browser-extension/src/utils/VaultSyncService.ts
+++ b/apps/browser-extension/src/utils/VaultSyncService.ts
@@ -174,7 +174,9 @@ type ManifestDto = {
ownerUsername?: string | null;
/** Whether the caller may grant/revoke access to this manifest and publish its email delivery key. */
canAdminister?: boolean;
- /** The manifest VEK encrypted with the caller's public key; set only on manifests granted by another user. */
+ /** How the caller's access to this manifest's VEK is wrapped. */
+ keyType?: string | null;
+ /** The manifest VEK encrypted with the caller's public key; set only on manifests we open through a grant. */
encryptedVek?: string | null;
/** Algorithm of `encryptedVek` (e.g. "rsa-oaep-sha256"). */
algorithm?: string | null;
@@ -202,6 +204,12 @@ function selectRootManifest(manifests: ManifestDto[] | undefined | null): Manife
*/
export const STORAGE_FORMAT_MANIFEST = 1;
+/** The manifest's VEK hangs off the account key hierarchy: the unlock chain produced it, nothing travels on the wire. */
+const MANIFEST_KEY_TYPE_ACCOUNT = 'accountkey';
+
+/** The manifest's VEK is encrypted to one of our public keys and carried on the manifest itself. */
+const MANIFEST_KEY_TYPE_GRANT = 'grantkey';
+
/**
* Raw snapshot returned by GET /v2/Vault.
*/
@@ -228,8 +236,8 @@ export type GetResponseDto = {
};
/**
- * One manifest element in a POST /v2/Vault write. Root targeting is explicit: set `isRoot: true` (and no `manifestId`) to write
- * the caller's root manifest or set `manifestId` (with `isRoot` false/omitted) to write a shared manifest.
+ * One manifest element in a POST /v2/Vault write. Every manifest is addressed by `manifestId`, root included; `isRoot`
+ * asserts what kind of target that id is and the server rejects the write when the two disagree.
*/
type ManifestWriteDto = {
isRoot?: boolean;
@@ -508,6 +516,7 @@ export class VaultSyncService {
/*
* Open every manifest in the snapshot through one path, root first.
*/
+ const accountKeyVeks = new Map<string, string>([[rootDto.manifestId, vek]]);
const resolved: ResolvedManifest[] = [];
const sessionSharedManifests: Record<string, SessionSharedManifest> = {};
/*
@@ -515,10 +524,13 @@ export class VaultSyncService {
* but not yet split into) still resolves to the folder the client renders it at.
*/
const priorFolderIds = new Map(Object.values(await SharingService.getSessionSharedManifests()).map(r => [r.manifestId, r.folderId]));
- for (const dto of [rootDto, ...(snapshot.manifests ?? []).filter(m => !m.isRoot)]) {
- // Safe on the non-root passes: the root is opened first and throws rather than leaving `resolved` empty.
- const manifestKey = dto.isRoot ? vek : await this.resolveGrantedVek(resolved[0].manifest, dto);
+ for (const dto of [rootDto, ...(snapshot.manifests ?? []).filter(m => m.manifestId !== rootDto.manifestId)]) {
+ const manifestKey = await this.resolveManifestVek(dto, accountKeyVeks, resolved[0]?.manifest ?? null);
if (!manifestKey || !dto.blob) {
+ // Same policy as a manifest that fails to open: a shared one only costs us that folder, the home one is the vault.
+ if (dto.manifestId === rootDto.manifestId) {
+ throw new Error(`VaultSyncService: no key resolved for the home manifest ${dto.manifestId} (key type "${dto.keyType ?? 'unspecified'}"), refusing to assemble.`);
+ }
continue;
}
@@ -727,7 +739,41 @@ export class VaultSyncService {
}
/**
- * Decrypt the VEK the server granted the caller on a non-root manifest.
+ * The key that opens one snapshot manifest.
+ * @param dto - the snapshot manifest
+ * @param accountKeyVeks - the VEKs already held per manifest id, keyed by the account key hierarchy
+ * @param rootManifest - the already-decrypted root manifest (the durable home of rotated private keys), or null when none is open yet
+ * @returns The manifest's VEK, or null when this client holds no key for it.
+ */
+ private async resolveManifestVek(dto: ManifestDto, accountKeyVeks: Map<string, string>, rootManifest: CodecManifest | null): Promise<string | null> {
+ // A server that predates the field says nothing, and there the home manifest is the account-key one by definition.
+ const keyType = dto.keyType ?? (dto.isRoot ? MANIFEST_KEY_TYPE_ACCOUNT : MANIFEST_KEY_TYPE_GRANT);
+
+ if (keyType === MANIFEST_KEY_TYPE_ACCOUNT) {
+ const accountKeyVek = accountKeyVeks.get(dto.manifestId);
+ if (!accountKeyVek) {
+ // Our unlock chain produced a VEK for a different manifest than the one this key is filed under.
+ devWarn(`[V2Pull] Manifest ${dto.manifestId} is unlocked by the account key hierarchy, but this session holds no key for it; skipping it.`);
+ return null;
+ }
+ return accountKeyVek;
+ }
+
+ if (keyType !== MANIFEST_KEY_TYPE_GRANT) {
+ devWarn(`[V2Pull] Manifest ${dto.manifestId} states an unknown key type "${keyType}" (newer server?), skipping it.`);
+ return null;
+ }
+
+ if (!rootManifest) {
+ devWarn(`[V2Pull] Manifest ${dto.manifestId} is opened through a grant, but no root manifest is open to resolve the private key from; skipping it.`);
+ return null;
+ }
+
+ return this.resolveGrantedVek(rootManifest, dto);
+ }
+
+ /**
+ * Decrypt the VEK the server granted the caller on a manifest.
* @param rootManifest - the already-decrypted root manifest, the durable home of rotated private keys
* @param dto - the snapshot manifest carrying the grant
*/
@@ -1012,8 +1058,8 @@ export class VaultSyncService {
devLog(`[V2Push] ${label}: raw ${formatKb(plaintext.length)} → compressed ${formatKb(compressedBytes)} → encrypted ${formatKb(ciphertext.length)}.`);
manifestWrites.push({
- // The root target is addressed by the flag alone (the server resolves it from the auth session), see ManifestWriteDto.
- ...(candidate.isRoot ? { isRoot: true } : { manifestId: candidate.manifestId }),
+ manifestId: candidate.manifestId,
+ isRoot: candidate.isRoot,
manifestBlob: ciphertext,
manifestCiphertextHash: ciphertextHash,
currentRevision: candidate.currentRevision,
diff --git a/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs b/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs
index 0cfc6187e..2128dd0fe 100644
--- a/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs
+++ b/apps/server/AliasVault.Api/Controllers/V2/VaultController.cs
@@ -139,10 +139,8 @@ public class VaultController(
.GroupBy(x => x.ManifestId)
.ToDictionary(g => g.Key, g => g.GroupBy(x => x.Hash, StringComparer.Ordinal).Select(h => new BlobReference { Hash = h.Key, Category = h.First().Category }).ToList());
- // The caller's grant on each non-root manifest: the manifest VEK encrypted with one of their public keys.
- var nonRootIds = latestManifests.Where(m => !m.IsRoot).Select(m => m.ManifestId).ToList();
- var grantsByManifest = await GetGrantsAsync(context, user.Id, nonRootIds);
- var encryptionPublicKeys = await GetEncryptionPublicKeysAsync(context, grantsByManifest.Values.Where(g => g.UserGrantKeyId != null).Select(g => g.UserGrantKeyId!.Value));
+ var accessKeysByManifest = await GetAccessKeysAsync(context, user.Id, manifestIds);
+ var encryptionPublicKeys = await GetEncryptionPublicKeysAsync(context, accessKeysByManifest.Values.Where(g => g.UserGrantKeyId != null).Select(g => g.UserGrantKeyId!.Value));
// A manifest owned by a group the caller does not own is one shared with them: stamp the owning user's name.
var foreignGroupIds = latestManifests.Where(m => !ownedGroupIds.Contains(m.OwnerGroupId)).Select(m => m.OwnerGroupId).Distinct().ToList();
@@ -154,7 +152,10 @@ public class VaultController(
var manifests = latestManifests.Select(m =>
{
- grantsByManifest.TryGetValue(m.ManifestId, out var grant);
+ accessKeysByManifest.TryGetValue(m.ManifestId, out var accessKey);
+
+ // An account-key row's ciphertext is not sent: the caller unwrapped that VEK from their password chain before this call.
+ var grant = accessKey != null && ManifestKeyTypes.CarriesEncryptedVek(accessKey.Type) ? accessKey : null;
return new Manifest
{
ManifestId = m.ManifestId,
@@ -166,6 +167,7 @@ public class VaultController(
BlobReferences = refsByManifest.TryGetValue(m.ManifestId, out var refs) ? refs : [],
OwnerUsername = ownerUsernamesByGroupId.GetValueOrDefault(m.OwnerGroupId),
CanAdminister = !m.IsRoot && administeredGroupIds.Contains(m.OwnerGroupId),
+ KeyType = accessKey != null ? ManifestKeyTypes.ToToken(accessKey.Type) : null,
EncryptedVek = grant?.EncryptedVek,
Algorithm = grant != null ? VaultKeyAlgorithms.ToToken(grant.Algorithm) : null,
EncryptionPublicKey = grant?.UserGrantKeyId != null ? encryptionPublicKeys.GetValueOrDefault(grant.UserGrantKeyId.Value) : null,
@@ -225,18 +227,22 @@ public class VaultController(
BlobReferences = blobRefs,
};
- // A non-root manifest is unlocked via the caller's grant (their encrypted VEK), whether they own it (self-grant)
- // or another user shared it with them. Attach that grant; only stamp OwnerUsername when it is shared with them.
- if (!latest.IsRoot)
+ // How this manifest's VEK reaches the caller.
+ var accessKey = (await GetAccessKeysAsync(context, user.Id, [latest.ManifestId])).GetValueOrDefault(latest.ManifestId);
+ manifest.KeyType = accessKey != null ? ManifestKeyTypes.ToToken(accessKey.Type) : null;
+ if (accessKey != null && ManifestKeyTypes.CarriesEncryptedVek(accessKey.Type))
{
- var grant = await context.VaultManifestAccessKeys.FirstOrDefaultAsync(k => k.UserId == user.Id && k.Type == ManifestKeyType.GrantKey && k.VaultManifestId == latest.ManifestId);
- manifest.EncryptedVek = grant?.EncryptedVek;
- manifest.Algorithm = grant != null ? VaultKeyAlgorithms.ToToken(grant.Algorithm) : null;
- if (grant?.UserGrantKeyId != null)
+ manifest.EncryptedVek = accessKey.EncryptedVek;
+ manifest.Algorithm = VaultKeyAlgorithms.ToToken(accessKey.Algorithm);
+ if (accessKey.UserGrantKeyId != null)
{
- manifest.EncryptionPublicKey = await context.UserGrantKeys.Where(k => k.Id == grant.UserGrantKeyId).Select(k => k.PublicKey).FirstOrDefaultAsync();
+ manifest.EncryptionPublicKey = await context.UserGrantKeys.Where(k => k.Id == accessKey.UserGrantKeyId).Select(k => k.PublicKey).FirstOrDefaultAsync();
}
+ }
+ // Ownership display and administer rights are only meaningful on a manifest that is not the caller's own home one.
+ if (!latest.IsRoot)
+ {
// Set owner username for shared manifests for display purposes.
var isOwnedByCaller = await context.GroupMembers.AnyAsync(gm => gm.GroupId == latest.OwnerGroupId && gm.UserId == user.Id && gm.Role == GroupRole.Owner);
if (!isOwnedByCaller)
@@ -313,38 +319,40 @@ public class VaultController(
return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_KEY_NOT_FOUND, 400));
}
- // Resolve + authorize each manifest write to its stored row.
+ /*
+ * Resolve + authorize each manifest write to its stored row.
+ */
var resolved = new List<(ManifestWrite Write, VaultManifest Row)>();
foreach (var mw in model.Manifests)
{
- if (mw.IsRoot)
+ VaultManifest? row;
+ if (mw.ManifestId != null)
{
- if (mw.ManifestId != null)
- {
- // Contradictory target (root + an id): refuse rather than guess which was intended.
- return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_NOT_UP_TO_DATE, 400));
- }
-
- var rootRow = await context.VaultManifests.FirstOrDefaultAsync(x => x.IsRoot && x.OwnerGroupId == user.PersonalGroupId);
- if (rootRow == null)
- {
- return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_NOT_UP_TO_DATE, 400));
- }
-
- resolved.Add((mw, rootRow));
- continue;
+ row = await WritableManifests(context, user.Id).FirstOrDefaultAsync(x => x.ManifestId == mw.ManifestId);
}
-
- if (mw.ManifestId == null)
+ else if (mw.IsRoot)
+ {
+ row = await context.VaultManifests.FirstOrDefaultAsync(x => x.IsRoot && x.OwnerGroupId == user.PersonalGroupId);
+ }
+ else
{
// A non-root write must name its manifest; a missing id must never fall through to the root.
return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_NOT_UP_TO_DATE, 400));
}
- var row = await AccessibleManifests(context, user.Id).FirstOrDefaultAsync(x => x.ManifestId == mw.ManifestId && !x.IsRoot);
if (row == null)
{
- return NotFound(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.SHARED_MANIFEST_NOT_FOUND, 404));
+ // A missing root is a state error on the caller's own vault; a missing shared manifest is a bad target.
+ return mw.IsRoot
+ ? BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_NOT_UP_TO_DATE, 400))
+ : NotFound(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.SHARED_MANIFEST_NOT_FOUND, 404));
+ }
+
+ // The target must agree with what its id resolved to, and a root write only ever means the caller's own
+ // personal root: refuse rather than guess which manifest was intended.
+ if (row.IsRoot != mw.IsRoot || (mw.IsRoot && row.OwnerGroupId != user.PersonalGroupId))
+ {
+ return BadRequest(ApiErrorCodeHelper.CreateValidationErrorResponse(ApiErrorCode.VAULT_NOT_UP_TO_DATE, 400));
}
resolved.Add((mw, row));
@@ -787,13 +795,26 @@ public class VaultController(
}
/// <summary>
- /// Gets the caller's grant on each of the given manifests: the manifest VEK encrypted to one of their account public keys.
+ /// The manifests a user can write to.
+ /// </summary>
+ /// <param name="context">Database context.</param>
+ /// <param name="userId">The calling user.</param>
+ /// <returns>Query over the manifests the user may write to, in any storage format.</returns>
+ private static IQueryable<VaultManifest> WritableManifests(AliasServerDbContext context, string userId)
+ {
+ return ManifestAccessHelper.AccessibleManifests(context, userId);
+ }
+
+ /// <summary>
+ /// Gets the caller's key row on each of the given manifests, whichever way that manifest's VEK is wrapped for
+ /// them: an account-key row (unlocked through their password chain) or a grant encrypted to one of their public
+ /// keys. An account-key row wins when a manifest has both, being the caller's own direct path to it.
/// </summary>
/// <param name="context">Database context.</param>
/// <param name="userId">The calling user.</param>
- /// <param name="manifestIds">The manifests to get grants for.</param>
- /// <returns>The grant per manifest id, empty when the caller holds none.</returns>
- private static async Task<Dictionary<Guid, VaultManifestAccessKey>> GetGrantsAsync(AliasServerDbContext context, string userId, IEnumerable<Guid> manifestIds)
+ /// <param name="manifestIds">The manifests to get key rows for.</param>
+ /// <returns>The key row per manifest id, empty when the caller holds none.</returns>
+ private static async Task<Dictionary<Guid, VaultManifestAccessKey>> GetAccessKeysAsync(AliasServerDbContext context, string userId, IEnumerable<Guid> manifestIds)
{
var ids = manifestIds.Distinct().ToList();
if (ids.Count == 0)
@@ -802,10 +823,10 @@ public class VaultController(
}
return (await context.VaultManifestAccessKeys
- .Where(k => k.UserId == userId && k.Type == ManifestKeyType.GrantKey && ids.Contains(k.VaultManifestId))
+ .Where(k => k.UserId == userId && ids.Contains(k.VaultManifestId))
.ToListAsync())
.GroupBy(k => k.VaultManifestId)
- .ToDictionary(g => g.Key, g => g.OrderByDescending(k => k.CreatedAt).ThenBy(k => k.Id).First());
+ .ToDictionary(g => g.Key, g => g.OrderBy(k => k.Type == ManifestKeyType.AccountKey ? 0 : 1).ThenByDescending(k => k.CreatedAt).ThenBy(k => k.Id).First());
}
/// <summary>
diff --git a/apps/server/Databases/AliasServerDb/ManifestKeyTypeDefinition.cs b/apps/server/Databases/AliasServerDb/ManifestKeyTypeDefinition.cs
new file mode 100644
index 000000000..41d689e9d
--- /dev/null
+++ b/apps/server/Databases/AliasServerDb/ManifestKeyTypeDefinition.cs
@@ -0,0 +1,29 @@
+//-----------------------------------------------------------------------
+// <copyright file="ManifestKeyTypeDefinition.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 AliasServerDb;
+
+/// <summary>
+/// The properties of a single <see cref="ManifestKeyType"/>.
+/// </summary>
+public sealed class ManifestKeyTypeDefinition
+{
+ /// <summary>
+ /// Gets the key type this definition describes.
+ /// </summary>
+ public required ManifestKeyType Type { get; init; }
+
+ /// <summary>
+ /// Gets the token that names the key type on the wire.
+ /// </summary>
+ public required string Token { get; init; }
+
+ /// <summary>
+ /// Gets a value indicating whether the wrapped VEK travels to the client along with the manifest.
+ /// </summary>
+ public required bool CarriesEncryptedVek { get; init; }
+}
diff --git a/apps/server/Databases/AliasServerDb/ManifestKeyTypes.cs b/apps/server/Databases/AliasServerDb/ManifestKeyTypes.cs
new file mode 100644
index 000000000..bbe03ef11
--- /dev/null
+++ b/apps/server/Databases/AliasServerDb/ManifestKeyTypes.cs
@@ -0,0 +1,110 @@
+//-----------------------------------------------------------------------
+// <copyright file="ManifestKeyTypes.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 AliasServerDb;
+
+/// <summary>
+/// The manifest key types this build supports, each with everything that varies per type.
+/// </summary>
+public static class ManifestKeyTypes
+{
+ /// <summary>
+ /// Every key type this build supports.
+ /// </summary>
+ private static readonly ManifestKeyTypeDefinition[] Definitions =
+ [
+ new ManifestKeyTypeDefinition
+ {
+ Type = ManifestKeyType.AccountKey,
+ Token = "accountkey",
+ CarriesEncryptedVek = false,
+ },
+ new ManifestKeyTypeDefinition
+ {
+ Type = ManifestKeyType.GrantKey,
+ Token = "grantkey",
+ CarriesEncryptedVek = true,
+ },
+ ];
+
+ private static readonly Dictionary<ManifestKeyType, ManifestKeyTypeDefinition> ByType = Definitions.ToDictionary(x => x.Type);
+ private static readonly Dictionary<string, ManifestKeyTypeDefinition> ByToken = Definitions.ToDictionary(x => x.Token, StringComparer.Ordinal);
+
+ /// <summary>
+ /// Initializes static members of the <see cref="ManifestKeyTypes"/> class.
+ /// </summary>
+ static ManifestKeyTypes()
+ {
+ var undefined = Enum.GetValues<ManifestKeyType>().Where(x => !ByType.ContainsKey(x)).ToList();
+ if (undefined.Count > 0)
+ {
+ throw new InvalidOperationException($"Manifest key type(s) without a definition: {string.Join(", ", undefined)}.");
+ }
+ }
+
+ /// <summary>
+ /// Returns the definition of a key type.
+ /// </summary>
+ /// <param name="type">The key type to look up.</param>
+ /// <returns>The definition.</returns>
+ public static ManifestKeyTypeDefinition GetDefinition(ManifestKeyType type)
+ {
+ if (!ByType.TryGetValue(type, out var definition))
+ {
+ throw new ArgumentOutOfRangeException(nameof(type), type, "Unknown manifest key type.");
+ }
+
+ return definition;
+ }
+
+ /// <summary>
+ /// Returns the token for a key type.
+ /// </summary>
+ /// <param name="type">The key type to convert.</param>
+ /// <returns>The token.</returns>
+ public static string ToToken(ManifestKeyType type) => GetDefinition(type).Token;
+
+ /// <summary>
+ /// Whether a key type's wrapped VEK is carried to the client alongside the manifest.
+ /// </summary>
+ /// <param name="type">The key type to check.</param>
+ /// <returns>True when the manifest carries the encrypted VEK.</returns>
+ public static bool CarriesEncryptedVek(ManifestKeyType type) => GetDefinition(type).CarriesEncryptedVek;
+
+ /// <summary>
+ /// Parses a token.
+ /// </summary>
+ /// <param name="token">The token to parse.</param>
+ /// <param name="type">The parsed key type.</param>
+ /// <returns>True when the token names a key type this build supports.</returns>
+ public static bool TryParse(string? token, out ManifestKeyType type)
+ {
+ if (token is null || !ByToken.TryGetValue(token, out var definition))
+ {
+ type = default;
+ return false;
+ }
+
+ type = definition.Type;
+ return true;
+ }
+
+ /// <summary>
+ /// Parses a token and returns the key type.
+ /// </summary>
+ /// <param name="token">The token to parse.</param>
+ /// <returns>The parsed key type.</returns>
+ public static ManifestKeyType Parse(string? token)
+ {
+ if (!TryParse(token, out var type))
+ {
+ throw new ArgumentOutOfRangeException(nameof(token), token, "Unknown manifest key type token.");
+ }
+
+ return type;
+ }
+}
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs
index c6c8f26d7..39597cd57 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/Manifest.cs
@@ -18,9 +18,7 @@ public class Manifest
public required Guid ManifestId { get; set; }
/// <summary>
- /// Gets or sets a value indicating whether this is the user's root manifest: the residual container that holds
- /// everything not carved out into another manifest. Sharing status is not encoded here — it is tracked
- /// separately (R2 access table); a non-root manifest is not necessarily shared.
+ /// Gets or sets a value indicating whether this is the user's root manifest.
/// </summary>
public required bool IsRoot { get; set; }
@@ -53,9 +51,12 @@ public class Manifest
public bool CanAdminister { get; set; }
/// <summary>
- /// Gets or sets the manifest VEK encrypted with the caller's public key, which they decrypt with their private
- /// key. Set on every non-root manifest the caller can open, whether they own it (their self-grant) or another
- /// user granted it to them. Null on the root manifest, which is unlocked through the account key hierarchy.
+ /// Gets or sets how the caller's access to this manifest's VEK is wrapped.
+ /// </summary>
+ public string? KeyType { get; set; }
+
+ /// <summary>
+ /// Gets or sets the manifest VEK encrypted with the caller's public key.
/// </summary>
public string? EncryptedVek { get; set; }
diff --git a/core/rust/src/vault_codec/manifest.rs b/core/rust/src/vault_codec/manifest.rs
index bbda5ad70..ccf11e785 100644
--- a/core/rust/src/vault_codec/manifest.rs
+++ b/core/rust/src/vault_codec/manifest.rs
@@ -213,6 +213,10 @@ pub struct CanonicalizeInput {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MaterializeInput {
+ /// Every manifest to materialize, the caller's own first. Order carries no privilege between
+ /// namespaces (each row routes by its own `ManifestId`); the first entry only supplies the
+ /// reported `migration_id`. Deserialization is positional, so a caller that skips
+ /// [`MaterializeInput::new`] must keep that order itself.
pub manifests: Vec<Manifest>,
#[serde(default)]
pub data_buckets: Vec<DataBucket>,
diff --git a/core/rust/src/vault_codec/materialize.rs b/core/rust/src/vault_codec/materialize.rs
index c95e2f585..0427604e6 100644
--- a/core/rust/src/vault_codec/materialize.rs
+++ b/core/rust/src/vault_codec/materialize.rs
@@ -25,8 +25,7 @@ use crate::error::{VaultError, VaultResult};
/// Materialize the vault's manifests into the table set the platform inserts. Every manifest arrives
/// in one list, each carrying its own data buckets; they are combined into a single table set with
-/// per-manifest logo scoping, key-scope filtering, and earlier-manifest-wins primary-key dedup.
-/// Every manifest's buckets merge into the same local tables.
+/// per-manifest logo scoping and key-scope filtering.
pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<MaterializedTables> {
let MaterializeInput { mut manifests, data_buckets, schema_columns } = input;
@@ -40,11 +39,7 @@ pub fn materialize_as_sqlite(input: MaterializeInput) -> VaultResult<Materialize
let manifest_records = manifest_bookkeeping_records(&manifests);
- /*
- * The caller's own manifest comes first (see `MaterializeInput::manifests`): it is the base every
- * other manifest is combined into, so on a collision in a table keyed by `Id` alone its row is the
- * one that survives, and its `migration_id` is the data-model version the vault reports.
- */
+ // The first manifest is the caller's own (see `MaterializeInput::new`).
let base = manifests.remove(0);
let others: Vec<Manifest> = manifests;