Skip to content

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

Refactor and update docs (#2159)

Leendert de Borstc0160f5cd241
diff --git a/apps/server/AliasVault.Api/Controllers/V1/AuthController.cs b/apps/server/AliasVault.Api/Controllers/V1/AuthController.cs
index fc0c7326f..0c4f95eaf 100644
--- a/apps/server/AliasVault.Api/Controllers/V1/AuthController.cs
+++ b/apps/server/AliasVault.Api/Controllers/V1/AuthController.cs
@@ -566,7 +566,7 @@ public class AuthController(IAliasServerDbContextFactory dbContextFactory, UserM
}
/// <summary>
- /// Mobile login initiate endpoint (v1). Note: deprecated and removed on purpose, use the v2 API instead.
+ /// Mobile login initiate endpoint (v1). Removed, use the v2 API instead.
/// </summary>
/// <returns>IActionResult.</returns>
[HttpPost("mobile-login/initiate")]
@@ -577,7 +577,7 @@ public class AuthController(IAliasServerDbContextFactory dbContextFactory, UserM
}
/// <summary>
- /// Mobile login poll endpoint (v1). Note: deprecated and removed on purpose, use the v2 API instead.
+ /// Mobile login poll endpoint (v1). Removed, use the v2 API instead.
/// </summary>
/// <param name="requestId">The unique identifier for the login request.</param>
/// <returns>IActionResult.</returns>
@@ -589,7 +589,7 @@ public class AuthController(IAliasServerDbContextFactory dbContextFactory, UserM
}
/// <summary>
- /// Mobile login request details endpoint (v1). Note: deprecated and removed on purpose, use the v2 API instead.
+ /// Mobile login request details endpoint (v1). Removed, use the v2 API instead.
/// </summary>
/// <param name="requestId">The unique identifier for the login request.</param>
/// <returns>IActionResult.</returns>
@@ -601,7 +601,7 @@ public class AuthController(IAliasServerDbContextFactory dbContextFactory, UserM
}
/// <summary>
- /// Mobile login submit endpoint (v1). Note: deprecated and removed on purpose, use the v2 API instead.
+ /// Mobile login submit endpoint (v1). Removed, use the v2 API instead.
/// </summary>
/// <returns>IActionResult.</returns>
[HttpPost("mobile-login/submit")]
diff --git a/apps/server/Databases/AliasServerDb/EmailClaim.cs b/apps/server/Databases/AliasServerDb/EmailClaim.cs
index 59ee27317..dc8b65ca3 100644
--- a/apps/server/Databases/AliasServerDb/EmailClaim.cs
+++ b/apps/server/Databases/AliasServerDb/EmailClaim.cs
@@ -13,7 +13,7 @@ using Microsoft.EntityFrameworkCore;
/// <summary>
/// EmailClaim object. This object is used to reserve an email address. The claim is linked to every manifest that
/// has ever held the alias (see <see cref="Links"/>), each link saying whether that manifest still carries it; a
-/// claim whose links are all gone is a tombstone that blocks re-use of the address on purpose and by design.
+/// claim whose links are all gone is a tombstone that blocks re-use of the address by design.
/// </summary>
[Index(nameof(Address), IsUnique = true)]
public class EmailClaim
diff --git a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/MissingBlobsResponse.cs b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/MissingBlobsResponse.cs
index 99eff15de..fa1d702f6 100644
--- a/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/MissingBlobsResponse.cs
+++ b/apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/MissingBlobsResponse.cs
@@ -9,7 +9,7 @@ namespace AliasVault.Shared.Models.WebApi.V2.Vault;
/// <summary>
/// Response for POST /v2/Vault/blobs/missing. This contains the subset of the client-supplied hashes
-/// the server does NOT have stored for this user. The client only needs to upload the bytes for these.
+/// the server does not have stored for this user. The client only needs to upload the bytes for these.
/// </summary>
public class MissingBlobsResponse
{
diff --git a/core/models/build.sh b/core/models/build.sh
index 534d7942c..7f29da87b 100755
--- a/core/models/build.sh
+++ b/core/models/build.sh
@@ -7,32 +7,32 @@ set -u # Treat unset variables as errors
package_name="models"
package_path="."
-echo "πŸ“¦ Building $package_name..."
+echo "- Building $package_name..."
npm install
echo ""
-echo "πŸ”„ Generating vault key vocabulary (C#, TS, Swift, Kotlin)..."
+echo "- Generating vault key vocabulary (C#, TS, Swift, Kotlin)..."
node scripts/generate-key-vocabulary.cjs
npm run lint && npm run build
echo ""
-echo "πŸ”„ Generating vault table registry (Rust) and bucket categories (C#, Swift, Kotlin)..."
+echo "- Generating vault table registry (Rust) and bucket categories (C#, Swift, Kotlin)..."
node scripts/generate-vault-table-registry.cjs
npm run test
echo ""
-echo "πŸ”„ Generating platform-specific models (C#, Swift, Kotlin)..."
+echo "- Generating platform-specific models (C#, Swift, Kotlin)..."
node scripts/generate-field-keys.cjs
-echo "πŸ”„ Generating password-generator defaults (Rust, C#)..."
+echo "- Generating password-generator defaults (Rust, C#)..."
node scripts/generate-password-defaults.cjs
-echo "πŸ”„ Generating language reference (C#)..."
+echo "- Generating language reference (C#)..."
node scripts/generate-languages.cjs
-echo "πŸ”„ Generating app defaults (Swift, Kotlin)..."
+echo "- Generating app defaults (Swift, Kotlin)..."
node scripts/generate-app-defaults.cjs
-echo "βœ… Models build completed. TypeScript clients link this package as source (@aliasvault/models)."
\ No newline at end of file
+echo "Models build completed. TypeScript clients link this package as source (@aliasvault/models)."
diff --git a/core/models/scripts/lib/vault-table-registry-emit.cjs b/core/models/scripts/lib/vault-table-registry-emit.cjs
index 2d9346d46..a9d00331d 100644
--- a/core/models/scripts/lib/vault-table-registry-emit.cjs
+++ b/core/models/scripts/lib/vault-table-registry-emit.cjs
@@ -115,7 +115,7 @@ function emitRust(registry) {
use super::{BlobColumn, TableConfig};
-/// All tables that need LWW merge, in registry order. Order is load-bearing: a merge inserts rows
+/// All tables that need LWW merge, in registry order. Order matters: a merge inserts rows
/// in this order, so child tables must be listed after the table they reference (Items first).
/// Per-table rationale (merge key choices, natural keys) is documented in the TypeScript source.
pub static SYNCABLE_TABLES: &[TableConfig] = &[
diff --git a/core/models/src/vault/VaultTableRegistry.ts b/core/models/src/vault/VaultTableRegistry.ts
index 2987eae92..ab970251e 100644
--- a/core/models/src/vault/VaultTableRegistry.ts
+++ b/core/models/src/vault/VaultTableRegistry.ts
@@ -54,13 +54,13 @@ export type VaultTableDefinition = {
};
/**
- * All syncable client vault tables, in registry order. Order is load-bearing: a merge inserts rows
+ * All syncable client vault tables, in registry order. Order matters: a merge inserts rows
* in this order, so child tables must be listed after the table they reference (Items first).
*/
export const VAULT_TABLES: VaultTableDefinition[] = [
{ Name: 'Items', ManifestScoped: true, PrimaryKey: ['Id'], ItemChild: false },
/*
- * ItemStats is keyed by the item it describes: Id IS the item's id, so recording a use is an
+ * ItemStats is keyed by the item it describes: Id is the item's id, so recording a use is an
* upsert and two devices never create competing rows. Listed after Items so a merge inserts the
* item first.
*/
@@ -70,7 +70,7 @@ export const VAULT_TABLES: VaultTableDefinition[] = [
* FieldDefinitionId for custom ones; exactly one is set), so independently created rows of the
* same field are merged into one. Both sides are normalized first, which strips the derived id of every
* single-value row, so adding Id to the key makes a single-value row match by its field while a
- * multi-value row matches by its OWNED id: two devices each adding a login.url are two different
+ * multi-value row matches by its own id: two devices each adding a login.url are two different
* rows that must both survive, and the id, unlike ValueIndex, is stable under reordering.
*/
{
@@ -110,7 +110,7 @@ export const VAULT_TABLES: VaultTableDefinition[] = [
},
/*
* FieldHistories: every history row derives its id from (item, field, ChangedAt), so after
- * normalization the natural key IS the identity: concurrent changes union (distinct ChangedAt),
+ * normalization the natural key is the identity: concurrent changes union (distinct ChangedAt),
* same-millisecond snapshots converge.
*/
{
diff --git a/core/rust/src/vault_codec/scoped_assets.rs b/core/rust/src/vault_codec/scoped_assets.rs
index 8ba4dce8a..00558d60e 100644
--- a/core/rust/src/vault_codec/scoped_assets.rs
+++ b/core/rust/src/vault_codec/scoped_assets.rs
@@ -136,7 +136,7 @@ fn rewrite_logo_rows(tables: &mut HashMap<String, Vec<CodecRecord>>, scope: &str
/// Repair every `Items.LogoId` in this table set: follow `remap`, then null a reference that resolves
/// to no logo present here (dangling -> the FK's `ON DELETE SET NULL`). Callers run
/// [`reconcile_logo_references`] first, so by this point a reference that crossed a scope boundary has
-/// already been pulled into this scope and only genuinely dead references are left to `NULL`.
+/// already been pulled into this scope and only dead references are left to `NULL`.
fn repoint_items(tables: &mut HashMap<String, Vec<CodecRecord>>, remap: &HashMap<String, String>) {
let valid_ids = logo_ids(tables);
let Some(items) = tables.get_mut(ITEMS_TABLE) else { return };
diff --git a/core/rust/src/vault_codec/sharing.rs b/core/rust/src/vault_codec/sharing.rs
index a3b7f7ff8..e45bbe6f6 100644
--- a/core/rust/src/vault_codec/sharing.rs
+++ b/core/rust/src/vault_codec/sharing.rs
@@ -236,8 +236,8 @@ pub(super) fn partition_by_manifest(
}
/*
- * 3b. EncryptionKeys routes by stamp like every other table; it is called out only because dropping
- * a `Route::Gone` row here is load-bearing. Re-homing a dead manifest's keypair would resurrect it
+ * 3b. EncryptionKeys routes by stamp like every other table; it is called out only because a
+ * `Route::Gone` row here must be dropped. Re-homing a dead manifest's keypair would resurrect it
* on a future re-share (handing pre-share mail to the new members) and would let a tampered local
* DB pass a fabricated key row off as the writing manifest's own. Mail encrypted to a dropped key
* becomes unreadable, which is the intended outcome: the key is readable only by whoever currently
@@ -409,7 +409,7 @@ pub(super) fn combine_manifest_tables(
/*
* First-manifest-wins registry: table -> set of row identities already present. Every row is stamped
* by `claim_manifest_scope` above, tables this build does not know included, and the identity folds
- * the stamp in, so this can never fire across manifests; it only dedupes a genuinely duplicated row
+ * the stamp in, so this can never fire across manifests; it only dedupes a truly duplicated row
* inside one manifest.
*/
let mut seen: HashMap<String, HashSet<String>> = HashMap::new();
diff --git a/core/rust/src/vault_codec/sharing_tests.rs b/core/rust/src/vault_codec/sharing_tests.rs
index 532a2e271..cacbdd084 100644
--- a/core/rust/src/vault_codec/sharing_tests.rs
+++ b/core/rust/src/vault_codec/sharing_tests.rs
@@ -101,7 +101,7 @@ fn logo_sources(m: &Manifest) -> Vec<&str> {
/// exactly what the client's `FolderRepository.restampSubtree` writes when a folder starts being
/// shared, so fixtures carry the membership the codec now routes on.
///
-/// Logos are deliberately NOT stamped here, just as the client does not stamp them: a logo is a
+/// Logos are not stamped here, just as the client does not stamp them: a logo is a
/// per-manifest asset the codec reconciles itself (cloning a copy into every manifest whose items
/// reference it), so moving items between manifests never has to move logo rows.
fn stamp_subtree(mut tables: Vec<CodecTableData>, folder_id: &str, manifest_id: &str) -> Vec<CodecTableData> {
@@ -227,9 +227,7 @@ fn canonicalize_owner() -> CanonicalizedVault {
canonicalize_from_sqlite(input_with_shares(owner_tables(), vec![spec("f-shared")])).unwrap()
}
-// ─────────────────────────────────────────────────────────────────────────────
// Canonicalize: splitting
-// ─────────────────────────────────────────────────────────────────────────────
#[test]
fn split_moves_folder_subtree_and_items_into_shared_manifest() {
@@ -337,7 +335,7 @@ fn split_clones_a_tag_into_the_manifest_an_item_moved_into() {
#[test]
fn split_refuses_rows_that_name_no_manifest() {
/*
- * Membership IS the stamp, so a row that names no manifest is a client that could not say where its
+ * Membership is the stamp, so a row that names no manifest is a client that could not say where its
* data belongs. There is no fallback scope to demote it into: the push is refused, naming the table
* and row, rather than homing it somewhere plausible and hoping.
*/
@@ -397,7 +395,7 @@ fn sqlite_blob_migration_stamps_every_row_of_a_vault_that_has_no_manifest_id_col
* `ManifestId` column (so no row carries the key at all) is canonicalized and materialized straight
* back out, with no share in sight. Nothing stamps those rows beforehand, the column they would be
* stamped in does not exist yet, so canonicalize adopting them into the manifest being written from
- * IS the conversion. Every row must come out carrying a real manifest id: the materialized schema
+ * is the conversion. Every row must come out carrying a real manifest id: the materialized schema
* declares the column NOT NULL, so a single unstamped row fails the whole migration.
*/
let mut input = raw_input_with_shares(owner_tables_unstamped(), vec![]);
@@ -424,7 +422,7 @@ fn sqlite_blob_migration_stamps_every_row_of_a_vault_that_has_no_manifest_id_col
#[test]
fn split_scopes_logos_per_manifest_instead_of_copying_them() {
- // Logos are NOT reference-copied: each manifest gets its own row per domain, identified by its
+ // Logos are not reference-copied: each manifest gets its own row per domain, identified by its
// own scope. The owner's legacy rows carry no scope.
let out = canonicalize_owner();
let shared = &out.rest()[0].manifest;
@@ -591,7 +589,7 @@ fn split_routes_bucket_rows_to_the_manifest_that_owns_them() {
#[test]
fn combine_stamps_bucket_rows_with_the_manifest_that_delivered_them() {
/*
- * The mirror rule of "the shipping manifest IS the membership": a bucket arrives under one manifest,
+ * The mirror rule of "the shipping manifest is the membership": a bucket arrives under one manifest,
* so its rows claim that manifest. A bucket whose rows name someone else cannot move them there.
*/
let out = canonicalize_owner();
@@ -875,9 +873,7 @@ fn split_regrafts_overflow_columns_onto_shared_rows() {
assert!(rows(&out.first().manifest, "Items").iter().all(|r| !r.contains_key("FutureCol")));
}
-// ─────────────────────────────────────────────────────────────────────────────
// Materialize: combining
-// ─────────────────────────────────────────────────────────────────────────────
/// Materialized tables as a name > rows map for easy assertions.
fn materialized_map(m: &MaterializedTables) -> HashMap<String, Vec<CodecRecord>> {
@@ -1374,9 +1370,7 @@ fn combine_of_a_single_manifest_carries_only_its_own_rows() {
assert_eq!(ids(&map["Items"]), vec!["i-nofolder", "i-personal"]);
}
-// ─────────────────────────────────────────────────────────────────────────────
// Primary encryption key extraction
-// ─────────────────────────────────────────────────────────────────────────────
#[test]
fn extract_encryption_key_for_public_key_picks_matching_row_over_primary() {
@@ -1424,9 +1418,7 @@ fn extract_encryption_key_for_public_key_skips_deleted_and_returns_none_on_miss(
assert!(extract_encryption_key_for_public_key(&out.first().manifest, "pub-unknown").is_none());
}
-// ─────────────────────────────────────────────────────────────────────────────
// Wire-format compatibility
-// ─────────────────────────────────────────────────────────────────────────────
#[test]
fn manifest_specs_deserialize_from_camel_case_json() {
@@ -1580,7 +1572,7 @@ fn member_edit_repointing_the_item_at_a_personal_logo_keeps_the_shared_logo() {
fn member_whose_shared_logo_blob_never_arrived_does_not_wipe_the_folders_logo() {
// The member's pull could not resolve the shared logo's bytes (blob missing/undecryptable), so their
// local row sits there empty while their own personal row for that domain has real bytes. Their next
- // push must NOT publish the empty row as the folder's logo: that drops the last reference to the
+ // push must not publish the empty row as the folder's logo: that drops the last reference to the
// owner's blob and every member loses the image.
let owner = canonicalize_owner();
let mut tables = member_tables_after_pull(&owner);
@@ -1605,9 +1597,7 @@ fn member_whose_shared_logo_blob_never_arrived_does_not_wipe_the_folders_logo()
assert!(!shared.blobs.is_empty(), "and register them so the write keeps a live blob reference");
}
-// ─────────────────────────────────────────────────────────────────────────────
// Logo kinds: one row shape, one `Items.LogoId` pointer, three key spaces.
-// ─────────────────────────────────────────────────────────────────────────────
/// The scoped logo id for any `(scope, kind, source)`.
fn logo_id_of_kind(scope: &str, kind: &str, source: &str) -> String {
@@ -1720,7 +1710,6 @@ fn a_builtin_logo_survives_without_any_image_bytes() {
assert_eq!(shared_item["LogoId"], json!(scoped_id));
}
-// ─────────────────────────────────────────────────────────────────────────────
// Folder keypairs (manifest-stamped `EncryptionKeys` rows)
//
// One table serves every manifest: personal-stamped rows are the personal manifest's own delivery keys,
@@ -1728,7 +1717,6 @@ fn a_builtin_logo_survives_without_any_image_bytes() {
// personal key must never travel INTO a shared manifest, and a folder key must never travel OUT of
// its own. Both directions are attacks a folder co-owner can attempt by writing rows into a manifest
// the victim materializes.
-// ─────────────────────────────────────────────────────────────────────────────
/// A delivery keypair row stamped with `scope` (a manifest id, or a legacy folder-id stamp).
fn folder_key(id: &str, scope: &str, public_key: &str, is_primary: i32) -> CodecRecord {
@@ -1766,7 +1754,7 @@ fn split_routes_folder_keypair_into_its_manifest_and_never_the_personal_one() {
#[test]
fn split_drops_folder_keypair_whose_scope_is_not_shared() {
// A key row stamped for a manifest that is not part of this push (revoked, deleted, or fabricated
- // locally) has nowhere to go: it must be dropped, NOT fall back into the personal manifest, a stale
+ // locally) has nowhere to go: it must be dropped, not fall back into the personal manifest, a stale
// copy demoted into the personal manifest would resurrect the old keypair on a future re-share, and would
// leave a private delivery key in a namespace revocation cannot reach.
let out = canonicalize_from_sqlite(input_with_shares(
@@ -1960,9 +1948,7 @@ fn validate_rejects_misplaced_folder_keypairs_before_upload() {
assert!(validate_manifest(&out.first().manifest).ok);
}
-// ─────────────────────────────────────────────────────────────────────────────
// Cross-manifest routing: the same id in two manifests
-// ─────────────────────────────────────────────────────────────────────────────
//
// A manifest is a namespace, so two of them may each hold a row with the same `Id`, and they do, for
// ordinary reasons: a member moves a shared item into their own vault (the client re-stamps the row and
@@ -2172,9 +2158,7 @@ fn split_roundtrips_two_same_id_items_without_mixing_their_children() {
assert_eq!(field_values.len(), 2, "neither row was dropped or duplicated into the other manifest");
}
-// ─────────────────────────────────────────────────────────────────────────────
// Cross-manifest routing: the blanket invariant
-// ─────────────────────────────────────────────────────────────────────────────
#[test]
fn every_row_of_a_canonicalized_manifest_carries_that_manifests_own_stamp() {
diff --git a/core/rust/src/vault_model/generated.rs b/core/rust/src/vault_model/generated.rs
index 7c15d8821..0cb02934e 100644
--- a/core/rust/src/vault_model/generated.rs
+++ b/core/rust/src/vault_model/generated.rs
@@ -6,7 +6,7 @@
use super::{BlobColumn, TableConfig};
-/// All tables that need LWW merge, in registry order. Order is load-bearing: a merge inserts rows
+/// All tables that need LWW merge, in registry order. Order matters: a merge inserts rows
/// in this order, so child tables must be listed after the table they reference (Items first).
/// Per-table rationale (merge key choices, natural keys) is documented in the TypeScript source.
pub static SYNCABLE_TABLES: &[TableConfig] = &[