Skip to content

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

Update core models to include Rust type generation (#2159)

Leendert de Borst5ae9d27842fd
diff --git a/core/models/README.md b/core/models/README.md
index 526e0ceda..e7e484d91 100644
--- a/core/models/README.md
+++ b/core/models/README.md
@@ -19,20 +19,17 @@ Automatically generates platform-specific models from TypeScript sources:
| Source | Generated Output | Language |
|--------|-----------------|----------|
| `src/vault/FieldKey.ts` | `apps/server/Databases/AliasClientDb/Models/FieldKey.cs` | C# |
-| `src/vault/FieldKey.ts` | `apps/mobile-app/ios/AliasVault/VaultModels/FieldKey.swift` | Swift |
+| `src/vault/FieldKey.ts` | `apps/mobile-app/ios/VaultModels/FieldKey.swift` | Swift |
| `src/vault/FieldKey.ts` | `apps/mobile-app/android/.../vaultstore/models/FieldKey.kt` | Kotlin |
-### 3. Generated Vocabularies (Not TypeScript-Sourced)
-
-Two generators own a vocabulary outright and emit **all four** platforms, TypeScript included. Their outputs
-under `src/` are generated files: edit the generator, not the output.
+### 3. Registry and Vocabulary Generators
| Generator | Source of truth | Emits |
|-----------|-----------------|-------|
-| `scripts/generate-bucket-categories.cjs` | `core/rust/src/vault_codec/types.rs` (`BUCKET_TABLES`) | `VaultDataBucketCategory` |
+| `scripts/generate-vault-table-registry.cjs` | `src/vault/VaultTableRegistry.ts` | the Rust codec's datamodel registry, the C# `VaultTableRegistry`, and `VaultDataBucketCategory` (C#, Swift, Kotlin) |
| `scripts/generate-key-vocabulary.cjs` | the `VOCABULARIES` table inside the script | `UnlockMethodType`, `ManifestKeyType`, `VaultKeyAlgorithm` |
-The key vocabulary is the set of tokens naming how a vault key is protected — which unlock method encrypts a
+The key vocabulary is the set of tokens naming how a vault key is protected, which unlock method encrypts a
user's Account Key, how a manifest's VEK reaches a given user, and which algorithm a piece of key ciphertext
uses. Each token is a contract shared by the API, the database and every client, so it is declared once and
emitted per platform. A member's `token` is the only identifier that is persisted or transmitted; the C# enum
diff --git a/core/models/build.sh b/core/models/build.sh
index 90e9ff9cf..fa32d2824 100755
--- a/core/models/build.sh
+++ b/core/models/build.sh
@@ -16,16 +16,17 @@ package_path="."
echo "📦 Building $package_name..."
npm install
-echo ""
-echo "🔄 Generating vault data bucket categories (C#, TS, Swift, Kotlin) from Rust source..."
-# Run before the build so the generated TS lands in src/ and is compiled into dist/ (and linted).
-node scripts/generate-bucket-categories.cjs
-
echo ""
echo "🔄 Generating vault key vocabulary (C#, TS, Swift, Kotlin)..."
node scripts/generate-key-vocabulary.cjs
-npm run lint && npm run test && npm run build
+npm run lint && npm run build
+
+echo ""
+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)..."
diff --git a/core/models/scripts/generate-bucket-categories.cjs b/core/models/scripts/generate-bucket-categories.cjs
deleted file mode 100644
index 4d0ccddaf..000000000
--- a/core/models/scripts/generate-bucket-categories.cjs
+++ /dev/null
@@ -1,248 +0,0 @@
-#!/usr/bin/env node
-/**
- * Generates the VaultDataBucketCategory representation for C#, TypeScript, Swift, and Kotlin.
- *
- * The single source of truth is the Rust codec's `BUCKET_TABLES` static in
- * core/rust/src/vault_codec/types.rs, which owns the manifest-v1 table -> bucket-category mapping
- * shared by every platform. The distinct bucket categories are a projection of that mapping, so we
- * parse them straight out of the Rust source and emit the per-platform category types.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// Paths
-const REPO_ROOT = path.join(__dirname, '../../..');
-const RUST_SOURCE = path.join(REPO_ROOT, 'core/rust/src/vault_codec/types.rs');
-const CS_OUTPUT = path.join(REPO_ROOT, 'apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultDataBucketCategory.cs');
-const TS_OUTPUT = path.join(REPO_ROOT, 'core/models/src/vault/VaultDataBucketCategory.ts');
-const SWIFT_OUTPUT = path.join(REPO_ROOT, 'apps/mobile-app/ios/VaultModels/VaultDataBucketCategory.swift');
-const KOTLIN_OUTPUT = path.join(REPO_ROOT, 'apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/models/VaultDataBucketCategory.kt');
-
-/**
- * Human-readable description per category, keyed by the category name declared in Rust.
- * Purely presentational (the category set itself always comes from Rust); an unknown category
- * falls back to a generic description so a new bucket never breaks generation.
- */
-const CATEGORY_DESCRIPTIONS = {
- Settings: 'User client settings (sort order, autofill prefs, identity defaults, etc.).',
- Stats: 'Per-item usage statistics (last used, use counts).',
- EncryptionKeys: "The user's asymmetric keypairs, which are used for both email decryption and to unwrap shared-folder VEKs.",
-};
-const DEFAULT_DESCRIPTION = 'A manifest-v1 data bucket category.';
-
-const AUTOGEN_NOTE = 'core/rust/src/vault_codec/types.rs (BUCKET_TABLES)';
-const REGEN_HINT = "Run 'core/models/build.sh' (or 'node core/models/scripts/generate-bucket-categories.cjs') to regenerate.";
-
-/**
- * Parse the distinct bucket categories out of the Rust BUCKET_TABLES static, in declaration order.
- * Each entry is `("Table", "Category")`; the category is the second string literal.
- */
-function parseBucketCategories(rustSource) {
- const arrayMatch = rustSource.match(/BUCKET_TABLES\s*:\s*&\[[^\]]*\]\s*=\s*&\[([\s\S]*?)\];/);
- if (!arrayMatch) {
- throw new Error(`Could not find BUCKET_TABLES in ${RUST_SOURCE}`);
- }
-
- const categories = [];
- const entryRegex = /\(\s*"[^"]*"\s*,\s*"([^"]*)"\s*\)/g;
- let match;
- while ((match = entryRegex.exec(arrayMatch[1])) !== null) {
- const category = match[1];
- if (!categories.includes(category)) {
- categories.push(category);
- }
- }
-
- if (categories.length === 0) {
- throw new Error('Parsed zero categories from BUCKET_TABLES; the parser or the Rust format changed.');
- }
-
- return categories;
-}
-
-/**
- * Description for a category, falling back to a generic one for categories without an explicit entry.
- */
-function describe(category) {
- return CATEGORY_DESCRIPTIONS[category] || DEFAULT_DESCRIPTION;
-}
-
-/** Convert a PascalCase category to camelCase (Swift). */
-function toCamelCase(name) {
- return name.charAt(0).toLowerCase() + name.slice(1);
-}
-
-/** Convert a PascalCase category to SCREAMING_SNAKE_CASE (Kotlin). */
-function toScreamingSnakeCase(name) {
- return name.replace(/([A-Z])/g, '_$1').toUpperCase().replace(/^_/, '');
-}
-
-/**
- * Generate the C# enum. Serialized as its string name (JsonStringEnumConverter) and stored as a
- * string in the database, so the numeric backing is cosmetic; ordinals follow declaration order.
- */
-function generateCSharp(categories) {
- const members = categories
- .map((category, index) => ` /// <summary>${describe(category)}</summary>
- ${category} = ${index},`)
- .join('\n\n');
-
- return `// <auto-generated />
-// This file is auto-generated from ${AUTOGEN_NOTE}.
-// Do not edit this file directly. ${REGEN_HINT}
-
-namespace AliasVault.Shared.Models.WebApi.V2.Vault;
-
-using System.Text.Json.Serialization;
-
-/// <summary>
-/// Known data-bucket categories for the manifest-v1 storage format. Each value is one small, independently-versioned,
-/// user-scoped category of encrypted data kept out of the main vault content manifest so it syncs cheaply.
-/// Serialized as its string name on the wire (not the numeric value) and stored as a string in the database.
-/// Adding a new kind requires a server-side rollout first, because the server reasons about kinds for
-/// per-kind retention policies. The canonical list lives in the Rust codec's BUCKET_TABLES.
-/// </summary>
-[JsonConverter(typeof(JsonStringEnumConverter))]
-public enum VaultDataBucketCategory
-{
-${members}
-}
-`;
-}
-
-/**
- * Generate the TypeScript const object (consumed as-is by the browser extension and mobile app).
- */
-function generateTypeScript(categories) {
- const members = categories
- .map(category => ` /**
- * ${describe(category)}
- */
- ${category}: '${category}',`)
- .join('\n\n');
-
- return `/**
- * <auto-generated />
- * This file is auto-generated from ${AUTOGEN_NOTE}.
- * Do not edit this file directly. ${REGEN_HINT}
- */
-
-/**
- * Known data-bucket categories for the manifest-v1 storage format. Each value is one small,
- * independently-versioned, user-scoped category of encrypted data kept out of the main vault content
- * manifest so it syncs cheaply. Serialized as its string name on the wire. The canonical list lives in
- * the Rust codec's BUCKET_TABLES.
- */
-export const VaultDataBucketCategory = {
-${members}
-} as const;
-
-/**
- * Type representing all valid vault data bucket category values.
- */
-export type VaultDataBucketCategoryValue = typeof VaultDataBucketCategory[keyof typeof VaultDataBucketCategory];
-`;
-}
-
-/**
- * Generate the Swift string-constant struct (mirrors the FieldType.swift convention).
- */
-function generateSwift(categories) {
- const members = categories
- .map(category => ` /// ${describe(category)}
- public static let ${toCamelCase(category)} = "${category}"`)
- .join('\n\n');
-
- const all = categories.map(toCamelCase).join(', ');
-
- return `// <auto-generated />
-// This file is auto-generated from ${AUTOGEN_NOTE}.
-// Do not edit this file directly. ${REGEN_HINT}
-
-import Foundation
-
-/// Known data-bucket categories for the manifest-v1 storage format.
-/// The canonical list lives in the Rust codec's BUCKET_TABLES.
-public struct VaultDataBucketCategory {
-${members}
-
- /// All known data bucket categories.
- public static let all = [${all}]
-}
-`;
-}
-
-/**
- * Generate the Kotlin string-constant object (mirrors the FieldType.kt convention).
- */
-function generateKotlin(categories) {
- const members = categories
- .map(category => ` /**
- * ${describe(category)}
- */
- const val ${toScreamingSnakeCase(category)} = "${category}"`)
- .join('\n\n');
-
- const all = categories.map(toScreamingSnakeCase).join(', ');
-
- return `// <auto-generated />
-// This file is auto-generated from ${AUTOGEN_NOTE}.
-// Do not edit this file directly. ${REGEN_HINT}
-
-package net.aliasvault.app.vaultstore.models
-
-/**
- * Known data-bucket categories for the manifest-v1 storage format.
- * The canonical list lives in the Rust codec's BUCKET_TABLES.
- */
-object VaultDataBucketCategory {
-${members}
-
- /**
- * All known data bucket categories.
- */
- val all = listOf(${all})
-}
-`;
-}
-
-/**
- * Ensure the directory for a file path exists.
- */
-function ensureDir(filePath) {
- const dir = path.dirname(filePath);
- if (!fs.existsSync(dir)) {
- fs.mkdirSync(dir, { recursive: true });
- }
-}
-
-/**
- * Main execution.
- */
-function main() {
- if (!fs.existsSync(RUST_SOURCE)) {
- throw new Error(`Source file not found: ${RUST_SOURCE}`);
- }
-
- const rustSource = fs.readFileSync(RUST_SOURCE, 'utf8');
- const categories = parseBucketCategories(rustSource);
- console.log(`Parsed ${categories.length} bucket categorie(s): ${categories.join(', ')}`);
-
- const outputs = [
- [CS_OUTPUT, generateCSharp(categories)],
- [TS_OUTPUT, generateTypeScript(categories)],
- [SWIFT_OUTPUT, generateSwift(categories)],
- [KOTLIN_OUTPUT, generateKotlin(categories)],
- ];
-
- for (const [outputPath, content] of outputs) {
- ensureDir(outputPath);
- fs.writeFileSync(outputPath, content, 'utf8');
- console.log(`Generated: ${outputPath}`);
- }
-
- console.log('\nVaultDataBucketCategory generation complete!');
-}
-
-main();
diff --git a/core/models/scripts/generate-vault-table-registry.cjs b/core/models/scripts/generate-vault-table-registry.cjs
new file mode 100644
index 000000000..4bf343066
--- /dev/null
+++ b/core/models/scripts/generate-vault-table-registry.cjs
@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Generates the vault datamodel registry outputs from the TypeScript source of truth.
+ *
+ * Input: core/models/src/vault/VaultTableRegistry.ts (compiled to dist/vault/index.js)
+ * Outputs:
+ * - core/rust/src/vault_model/generated.rs (Rust registry data)
+ * - apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultDataBucketCategory.cs
+ * - apps/mobile-app/ios/VaultModels/VaultDataBucketCategory.swift
+ * - apps/mobile-app/android/.../vaultstore/models/VaultDataBucketCategory.kt
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { pathToFileURL } = require('url');
+const { emitRust, emitCSharpRegistry, emitBucketCategoryCSharp, emitBucketCategorySwift, emitBucketCategoryKotlin } = require('./lib/vault-table-registry-emit.cjs');
+
+const REPO_ROOT = path.join(__dirname, '../../..');
+const DIST_ENTRY = path.join(__dirname, '../dist/vault/index.js');
+const RUST_OUTPUT = path.join(REPO_ROOT, 'core/rust/src/vault_model/generated.rs');
+const CS_REGISTRY_OUTPUT = path.join(REPO_ROOT, 'apps/server/Databases/AliasClientDb/Models/VaultTableRegistry.cs');
+const BUCKET_CS_OUTPUT = path.join(REPO_ROOT, 'apps/server/Shared/AliasVault.Shared/Models/WebApi/V2/Vault/VaultDataBucketCategory.cs');
+const BUCKET_SWIFT_OUTPUT = path.join(REPO_ROOT, 'apps/mobile-app/ios/VaultModels/VaultDataBucketCategory.swift');
+const BUCKET_KOTLIN_OUTPUT = path.join(REPO_ROOT, 'apps/mobile-app/android/app/src/main/java/net/aliasvault/app/vaultstore/models/VaultDataBucketCategory.kt');
+
+function writeIfChanged(filePath, contents) {
+ const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
+ if (existing === contents) {
+ console.log(` ✓ up to date: ${path.relative(REPO_ROOT, filePath)}`);
+ return;
+ }
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
+ fs.writeFileSync(filePath, contents);
+ console.log(` ✎ wrote: ${path.relative(REPO_ROOT, filePath)}`);
+}
+
+async function main() {
+ // The dist bundle is ESM, so load it via dynamic import.
+ const registry = await import(pathToFileURL(DIST_ENTRY).href);
+
+ console.log('Generating vault table registry:');
+ console.log(` tables: ${registry.VAULT_TABLES.map((t) => t.Name).join(', ')}`);
+ console.log(` multi-value field keys: ${registry.MULTI_VALUE_FIELD_KEYS.join(', ')}`);
+
+ writeIfChanged(RUST_OUTPUT, emitRust(registry));
+ writeIfChanged(CS_REGISTRY_OUTPUT, emitCSharpRegistry(registry));
+ writeIfChanged(BUCKET_CS_OUTPUT, emitBucketCategoryCSharp(registry));
+ writeIfChanged(BUCKET_SWIFT_OUTPUT, emitBucketCategorySwift(registry));
+ writeIfChanged(BUCKET_KOTLIN_OUTPUT, emitBucketCategoryKotlin(registry));
+}
+
+main().catch((err) => {
+ console.error(err);
+ process.exit(1);
+});
diff --git a/core/models/scripts/lib/vault-table-registry-emit.cjs b/core/models/scripts/lib/vault-table-registry-emit.cjs
new file mode 100644
index 000000000..36b444132
--- /dev/null
+++ b/core/models/scripts/lib/vault-table-registry-emit.cjs
@@ -0,0 +1,366 @@
+/**
+ * Emitters for the vault table registry (core/models/src/vault/VaultTableRegistry.ts).
+ */
+
+'use strict';
+
+const TS_SOURCE_REL = 'core/models/src/vault/VaultTableRegistry.ts';
+const GENERATOR_REL = 'core/models/scripts/generate-vault-table-registry.cjs';
+
+/** Render a JS string array as a Rust `&["a", "b"]` slice literal. */
+function rustStrSlice(values) {
+ return `&[${values.map((v) => `"${v}"`).join(', ')}]`;
+}
+
+/** PascalCase/camelCase to SCREAMING_SNAKE_CASE (FieldDefinitionId to FIELD_DEFINITION_ID). */
+function toScreamingSnakeCase(name) {
+ return name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
+}
+
+/** Basic sanity checks on the registry module before emitting anything. */
+function validateRegistry(registry) {
+ const tables = registry.VAULT_TABLES;
+ if (!Array.isArray(tables) || tables.length === 0) {
+ throw new Error(`VAULT_TABLES not found or empty in ${TS_SOURCE_REL}. Run 'npm run build' first.`);
+ }
+ const names = tables.map((t) => t.Name);
+ if (new Set(names).size !== names.length) {
+ throw new Error('VAULT_TABLES contains duplicate table names.');
+ }
+ if (names[0] !== 'Items') {
+ throw new Error('VAULT_TABLES must list Items first: registry order is merge insert order.');
+ }
+ for (const table of tables) {
+ for (const key of [table.LegacyMergeKey, table.CanonicalMergeKey]) {
+ if (key && table.ManifestScoped && key[0] !== registry.VAULT_MANIFEST_ID_COLUMN) {
+ throw new Error(`${table.Name}: merge keys of a manifest-scoped table must start with ${registry.VAULT_MANIFEST_ID_COLUMN}.`);
+ }
+ }
+ }
+ if (!Array.isArray(registry.MULTI_VALUE_FIELD_KEYS) || registry.MULTI_VALUE_FIELD_KEYS.length === 0) {
+ throw new Error('MULTI_VALUE_FIELD_KEYS is empty; expected at least login.url from SystemFieldRegistry.');
+ }
+ const usedCategories = new Set(tables.filter((t) => t.BucketCategory).map((t) => t.BucketCategory));
+ for (const table of tables) {
+ if (table.BucketCategory && !registry.VAULT_BUCKET_CATEGORIES.includes(table.BucketCategory)) {
+ throw new Error(`${table.Name}: bucket category '${table.BucketCategory}' is not declared in VAULT_BUCKET_CATEGORIES.`);
+ }
+ }
+ for (const category of registry.VAULT_BUCKET_CATEGORIES) {
+ if (!usedCategories.has(category)) {
+ throw new Error(`VAULT_BUCKET_CATEGORIES declares '${category}' but no table uses it.`);
+ }
+ }
+ if (!Array.isArray(registry.VAULT_COLUMN_NAMES) || registry.VAULT_COLUMN_NAMES.length === 0) {
+ throw new Error('VAULT_COLUMN_NAMES not found or empty.');
+ }
+ const tableNames = new Set(names);
+ for (const table of tables) {
+ for (const ref of table.ReferencedBy || []) {
+ if (!tableNames.has(ref.Table)) {
+ throw new Error(`${table.Name}: ReferencedBy names unknown table '${ref.Table}'.`);
+ }
+ }
+ }
+ if (!registry.LogoKinds || !registry.LogoKinds.Favicon) {
+ throw new Error('LogoKinds not found; the emitter must receive the full vault module namespace.');
+ }
+ const declaredCategories = Object.values(registry.VaultDataBucketCategory || {}).sort();
+ const registryCategories = [...registry.VAULT_BUCKET_CATEGORIES].sort();
+ if (JSON.stringify(declaredCategories) !== JSON.stringify(registryCategories)) {
+ throw new Error(`VaultDataBucketCategory (${declaredCategories}) and VAULT_BUCKET_CATEGORIES (${registryCategories}) have drifted apart.`);
+ }
+}
+
+/** Render one VAULT_TABLES entry as a Rust TableConfig builder chain. */
+function emitRustTableEntry(table) {
+ const calls = [`TableConfig::new("${table.Name}")`];
+ if (table.ManifestScoped) {
+ calls.push('.manifest_scoped()');
+ }
+ if (table.ItemChild) {
+ calls.push('.item_child()');
+ }
+ if (table.PrimaryKey.length !== 1 || table.PrimaryKey[0] !== 'Id') {
+ calls.push(`.with_primary_key(${rustStrSlice(table.PrimaryKey)})`);
+ }
+ if (table.LegacyMergeKey) {
+ calls.push(`.with_composite_key(${rustStrSlice(table.LegacyMergeKey)})`);
+ }
+ if (table.CanonicalMergeKey) {
+ calls.push(`.with_canonical_key(${rustStrSlice(table.CanonicalMergeKey)})`);
+ }
+
+ const singleLine = ` ${calls.join('')},`;
+ if (singleLine.length <= 120) {
+ return singleLine;
+ }
+ const lines = [` ${calls[0]}`];
+ for (let i = 1; i < calls.length; i++) {
+ lines.push(` ${calls[i]}${i === calls.length - 1 ? ',' : ''}`);
+ }
+ return lines.join('\n');
+}
+
+/** Emit core/rust/src/vault_model/generated.rs from the registry module. */
+function emitRust(registry) {
+ validateRegistry(registry);
+ const tables = registry.VAULT_TABLES;
+ // Bucket tuples grouped by category declaration order: that order, not table order, decides the
+ // order buckets are emitted in (bucket_categories() dedups in tuple order).
+ const bucketTables = registry.VAULT_BUCKET_CATEGORIES.flatMap((category) =>
+ tables.filter((t) => t.BucketCategory === category).map((t) => `("${t.Name}", "${category}")`));
+ const blobColumns = tables.filter((t) => t.BlobColumn).map((t) => `("${t.Name}", "${t.BlobColumn.Column}", "${t.BlobColumn.Kind}")`);
+
+ return `//! Generated client vault datamodel registry data.
+//!
+//! @generated: do NOT edit this file directly. It is generated from
+//! ${TS_SOURCE_REL} by ${GENERATOR_REL}.
+//! Edit the TypeScript source and run 'core/models/build.sh' to regenerate.
+
+use super::TableConfig;
+
+/// All tables that need LWW merge, in registry order. Order is load-bearing: 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] = &[
+${tables.map(emitRustTableEntry).join('\n')}
+];
+
+/// List of syncable table names (for clients to know which tables to read).
+pub const SYNCABLE_TABLE_NAMES: &[&str] = &[
+${tables.map((t) => ` "${t.Name}",`).join('\n')}
+];
+
+/// The SQLite columns whose contents are extracted into content-addressed blobs rather than
+/// kept inline in the manifest. Tuple form \`(table_name, blob_column, kind_label)\`. The kind label
+/// is reported to the server on upload (used for metrics / retention).
+pub static BLOB_COLUMNS: &[(&str, &str, &str)] = &[
+${blobColumns.map((entry) => ` ${entry},`).join('\n')}
+];
+
+/// Tables never serialized into the server-stored manifest: internal SQLite, platform, or EF bookkeeping
+/// that is temporary and only used/required during runtime, and therefore should not become part of a persisted manifest.
+pub static SKIP_TABLES: &[&str] = &[
+${registry.VAULT_SKIP_TABLES.map((t) => ` "${t}",`).join('\n')}
+];
+
+/// Tables split out of the manifest into a data bucket, keyed by category, so each bucket syncs on its
+/// own server revision without rewriting the manifest. Tuple form \`(table_name, bucket_category)\`;
+/// \`category\` mirrors the server \`VaultDataBucketCategory\`. Several tables may share a category to sync together.
+pub static BUCKET_TABLES: &[(&str, &str)] = &[
+${bucketTables.map((entry) => ` ${entry},`).join('\n')}
+];
+
+/// Tables that belong exclusively to the user's own (personal) vault, never to a shared manifest.
+/// Deliberately independent of [\`BUCKET_TABLES\`]: a bucketed table is kept out of the manifest blob,
+/// which is a different question from which manifests may hold its rows at all.
+pub static PERSONAL_TABLES: &[&str] = &[${registry.VAULT_PERSONAL_TABLES.map((t) => `"${t}"`).join(', ')}];
+
+/// System field keys whose field holds multiple values, derived from SystemFieldRegistry
+/// (IsMultiValue). A value of such a field owns its row id (two devices each adding a value are
+/// adding two different things) and is not derived.
+pub static MULTI_VALUE_FIELD_KEYS: &[&str] = ${rustStrSlice(registry.MULTI_VALUE_FIELD_KEYS)};
+
+/// The per-manifest delivery-keypair table. Every manifest carries its own asymmetric keypair(s),
+/// stamped with that manifest's id (\`ManifestId\`).
+pub const ENCRYPTION_KEYS_TABLE: &str = "${registry.ENCRYPTION_KEYS_TABLE}";
+
+/// The scope column every stamped table carries: the id of the manifest that owns the row.
+pub const MANIFEST_ID_COL: &str = "${registry.VAULT_MANIFEST_ID_COLUMN}";
+
+/// Local bookkeeping table materialize writes into the vault DB: one row per manifest this
+/// vault is materialized from (\`Id\`, \`Name\`).
+pub const MANIFESTS_TABLE: &str = "${registry.MANIFESTS_TABLE}";
+
+/// Client-local SQLite table that carries the codec overflow inside the vault database itself (see
+/// \`CodecOverflow\`): materialize writes a single row \`{ Id: OVERFLOW_ROW_ID, Data: <json> }\`, and
+/// canonicalize / extract_bucket consume it to build the manifest.
+pub const OVERFLOW_TABLE: &str = "${registry.CODEC_OVERFLOW_TABLE}";
+
+/// Fixed sentinel primary key of the single \`OVERFLOW_TABLE\` row (deterministic on purpose:
+/// materialize output must not depend on a random source).
+pub const OVERFLOW_ROW_ID: &str = "${registry.CODEC_OVERFLOW_ROW_ID}";
+
+/// All zero GUID used for default values which indicate unstamped rows.
+pub const UNSTAMPED_SCOPE_SENTINEL: &str = "${registry.UNSTAMPED_SCOPE_SENTINEL}";
+
+/// Rows referenced from inside manifest content: \`(target_table, [(referencing_table, column)])\`.
+/// On a manifest split the referenced rows are reference-copied into the destination manifest.
+pub static REFERENCED_TABLES: &[(&str, &[(&str, &str)])] = &[
+${tables.filter((t) => t.ReferencedBy).map((t) => ` ("${t.Name}", &[${t.ReferencedBy.map((r) => `("${r.Table}", "${r.Column}")`).join(', ')}]),`).join('\n')}
+];
+
+/// Default trash retention in days: how long a trashed item survives before the pruner deletes it.
+pub const TRASH_RETENTION_DEFAULT_DAYS: u32 = ${registry.TRASH_RETENTION_DEFAULT_DAYS};
+
+/// Table, column, and logo-kind name vocabulary shared by the vault logic, so every module spells
+/// them identically. The full column set of each table is deliberately not modeled here: it lives
+/// in the SQL schema and is passed to the codec at runtime.
+pub mod names {
+${tables.map((t) => ` /// The \`${t.Name}\` table.\n pub const ${toScreamingSnakeCase(t.Name)}_TABLE: &str = "${t.Name}";`).join('\n')}
+
+${registry.VAULT_COLUMN_NAMES.map((c) => ` /// The \`${c}\` column.\n pub const ${toScreamingSnakeCase(c)}_COL: &str = "${c}";`).join('\n')}
+
+${Object.entries(registry.LogoKinds).map(([key, value]) => ` /// The \`${value}\` logo kind.\n pub const LOGO_KIND_${toScreamingSnakeCase(key)}: &str = "${value}";`).join('\n')}
+}
+`;
+}
+
+/**
+ * Emit the C# registry (AliasClientDb.Models.VaultTableRegistry): the table names, primary keys,
+ * manifest scoping and item-child flags, so a unit test can assert the EF model matches the
+ * registry. Merge keys are deliberately not emitted; they are Rust merge semantics.
+ */
+function emitCSharpRegistry(registry) {
+ validateRegistry(registry);
+ const entries = registry.VAULT_TABLES
+ .map((t) => ` new("${t.Name}", new[] { ${t.PrimaryKey.map((c) => `"${c}"`).join(', ')} }, ManifestScoped: ${t.ManifestScoped}, ItemChild: ${t.ItemChild}),`)
+ .join('\n');
+
+ return `// <auto-generated />
+// This file is auto-generated from ${TS_SOURCE_REL}
+// Do not edit this file directly. Run 'core/models/build.sh' (or
+// 'node ${GENERATOR_REL}') to regenerate.
+
+#nullable enable
+
+namespace AliasClientDb.Models;
+
+using System.Collections.Generic;
+
+/// <summary>
+/// The client vault datamodel registry: one entry per syncable vault table, generated from the
+/// TypeScript source of truth shared with the Rust codec. A unit test asserts the EF model
+/// matches this registry, so a datamodel change that skips one of the encodings fails loudly.
+/// </summary>
+public static class VaultTableRegistry
+{
+ /// <summary>
+ /// Gets all syncable client vault tables, in registry order.
+ /// </summary>
+ public static IReadOnlyList<VaultTableDefinition> Tables { get; } = new VaultTableDefinition[]
+ {
+${entries}
+ };
+}
+
+/// <summary>
+/// Metadata for one syncable client vault table.
+/// </summary>
+/// <param name="Name">Table name in the client SQLite database.</param>
+/// <param name="PrimaryKey">The columns that name a row within its manifest, excluding ManifestId.</param>
+/// <param name="ManifestScoped">True when the table's rows are namespaced per manifest.</param>
+/// <param name="ItemChild">True when the table's rows hang off an Item row.</param>
+public sealed record VaultTableDefinition(string Name, IReadOnlyList<string> PrimaryKey, bool ManifestScoped, bool ItemChild);
+`;
+}
+
+const BUCKET_AUTOGEN_NOTE = 'core/models/src/vault/VaultTableRegistry.ts (VAULT_BUCKET_CATEGORIES)';
+const BUCKET_REGEN_HINT = "Run 'core/models/build.sh' (or 'node core/models/scripts/generate-vault-table-registry.cjs') to regenerate.";
+const BUCKET_DEFAULT_DESCRIPTION = 'A manifest-v1 data bucket category.';
+
+/** Description for a bucket category, falling back to a generic one so a new bucket never breaks generation. */
+function describeBucketCategory(registry, category) {
+ return (registry.VaultDataBucketCategoryDescriptions || {})[category] || BUCKET_DEFAULT_DESCRIPTION;
+}
+
+/** Convert a PascalCase category to camelCase (Swift). */
+function toCamelCase(name) {
+ return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+/**
+ * Emit the C# VaultDataBucketCategory enum. Serialized as its string name (JsonStringEnumConverter)
+ * and stored as a string in the database, so the numeric backing is cosmetic; ordinals follow
+ * declaration order.
+ */
+function emitBucketCategoryCSharp(registry) {
+ validateRegistry(registry);
+ const members = registry.VAULT_BUCKET_CATEGORIES
+ .map((category, index) => ` /// <summary>${describeBucketCategory(registry, category)}</summary>
+ ${category} = ${index},`)
+ .join('\n\n');
+
+ return `// <auto-generated />
+// This file is auto-generated from ${BUCKET_AUTOGEN_NOTE}.
+// Do not edit this file directly. ${BUCKET_REGEN_HINT}
+
+namespace AliasVault.Shared.Models.WebApi.V2.Vault;
+
+using System.Text.Json.Serialization;
+
+/// <summary>
+/// Known data-bucket categories for the manifest-v1 storage format. Each value is one small, independently-versioned,
+/// user-scoped category of encrypted data kept out of the main vault content manifest so it syncs cheaply.
+/// Serialized as its string name on the wire (not the numeric value) and stored as a string in the database.
+/// Adding a new kind requires a server-side rollout first, because the server reasons about kinds for
+/// per-kind retention policies. The canonical list lives in the vault table registry (core/models).
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public enum VaultDataBucketCategory
+{
+${members}
+}
+`;
+}
+
+/** Emit the Swift string-constant struct (mirrors the FieldType.swift convention). */
+function emitBucketCategorySwift(registry) {
+ validateRegistry(registry);
+ const categories = registry.VAULT_BUCKET_CATEGORIES;
+ const members = categories
+ .map((category) => ` /// ${describeBucketCategory(registry, category)}
+ public static let ${toCamelCase(category)} = "${category}"`)
+ .join('\n\n');
+
+ return `// <auto-generated />
+// This file is auto-generated from ${BUCKET_AUTOGEN_NOTE}.
+// Do not edit this file directly. ${BUCKET_REGEN_HINT}
+
+import Foundation
+
+/// Known data-bucket categories for the manifest-v1 storage format.
+/// The canonical list lives in the vault table registry (core/models).
+public struct VaultDataBucketCategory {
+${members}
+
+ /// All known data bucket categories.
+ public static let all = [${categories.map(toCamelCase).join(', ')}]
+}
+`;
+}
+
+/** Emit the Kotlin string-constant object (mirrors the FieldType.kt convention). */
+function emitBucketCategoryKotlin(registry) {
+ validateRegistry(registry);
+ const categories = registry.VAULT_BUCKET_CATEGORIES;
+ const members = categories
+ .map((category) => ` /**
+ * ${describeBucketCategory(registry, category)}
+ */
+ const val ${toScreamingSnakeCase(category)} = "${category}"`)
+ .join('\n\n');
+
+ return `// <auto-generated />
+// This file is auto-generated from ${BUCKET_AUTOGEN_NOTE}.
+// Do not edit this file directly. ${BUCKET_REGEN_HINT}
+
+package net.aliasvault.app.vaultstore.models
+
+/**
+ * Known data-bucket categories for the manifest-v1 storage format.
+ * The canonical list lives in the vault table registry (core/models).
+ */
+object VaultDataBucketCategory {
+${members}
+
+ /**
+ * All known data bucket categories.
+ */
+ val all = listOf(${categories.map(toScreamingSnakeCase).join(', ')})
+}
+`;
+}
+
+module.exports = { emitRust, emitCSharpRegistry, emitBucketCategoryCSharp, emitBucketCategorySwift, emitBucketCategoryKotlin };
diff --git a/core/models/src/vault/VaultDataBucketCategory.ts b/core/models/src/vault/VaultDataBucketCategory.ts
index 1a5592c49..f69480ee9 100644
--- a/core/models/src/vault/VaultDataBucketCategory.ts
+++ b/core/models/src/vault/VaultDataBucketCategory.ts
@@ -1,14 +1,7 @@
-/**
- * <auto-generated />
- * This file is auto-generated from core/rust/src/vault_codec/types.rs (BUCKET_TABLES).
- * Do not edit this file directly. Run 'core/models/build.sh' (or 'node core/models/scripts/generate-bucket-categories.cjs') to regenerate.
- */
-
/**
* Known data-bucket categories for the manifest-v1 storage format. Each value is one small,
* independently-versioned, user-scoped category of encrypted data kept out of the main vault content
- * manifest so it syncs cheaply. Serialized as its string name on the wire. The canonical list lives in
- * the Rust codec's BUCKET_TABLES.
+ * manifest so it syncs cheaply. Serialized as its string name on the wire.
*/
export const VaultDataBucketCategory = {
/**
@@ -26,3 +19,11 @@ export const VaultDataBucketCategory = {
* Type representing all valid vault data bucket category values.
*/
export type VaultDataBucketCategoryValue = typeof VaultDataBucketCategory[keyof typeof VaultDataBucketCategory];
+
+/**
+ * Human-readable description per category, emitted into the generated platform variants' doc comments.
+ */
+export const VaultDataBucketCategoryDescriptions: Record<VaultDataBucketCategoryValue, string> = {
+ Settings: 'User client settings (sort order, autofill prefs, identity defaults, etc.).',
+ Stats: 'Per-item usage statistics (last used, use counts).',
+};
diff --git a/core/models/src/vault/VaultTableRegistry.ts b/core/models/src/vault/VaultTableRegistry.ts
new file mode 100644
index 000000000..70bd6b09c
--- /dev/null
+++ b/core/models/src/vault/VaultTableRegistry.ts
@@ -0,0 +1,241 @@
+import { SystemFieldRegistry } from './SystemFieldRegistry';
+
+/**
+ * The client vault datamodel registry: one entry per syncable client vault table, carrying the
+ * metadata every platform needs to agree on (primary keys, manifest scoping, merge match keys,
+ * bucket layout, blob extraction). This file is the single source of truth; the Rust codec's
+ * registry (core/rust/src/vault_model/generated.rs) is generated from it by
+ * core/models/scripts/generate-vault-table-registry.cjs.
+ */
+
+/**
+ * The scope column every stamped table carries: the id of the manifest that owns the row.
+ */
+export const VAULT_MANIFEST_ID_COLUMN = 'ManifestId';
+
+/**
+ * Metadata for one syncable client vault table.
+ */
+export type VaultTableDefinition = {
+ /** Table name in the client SQLite database. */
+ Name: string;
+ /** True when the table's rows are namespaced per manifest. */
+ ManifestScoped: boolean;
+ /**
+ * The columns that name a row within its manifest, excluding ManifestId. Defaults to ['Id'];
+ * tables keyed differently (Settings by Key, ItemTags by its natural key) override this.
+ */
+ PrimaryKey: string[];
+ /** True when the table's rows hang off an Item row (re-stamped with their item, cascaded on delete). */
+ ItemChild: boolean;
+ /**
+ * Match columns for the legacy statement merge. When absent, matching falls back to
+ * (ManifestId, PrimaryKey).
+ */
+ LegacyMergeKey?: string[];
+ /**
+ * Match columns for the canonical merge only, where both sides are first normalized to the
+ * manifest shape (see the Rust vault_codec::normalize module). Absent means the canonical merge
+ * uses the same rule as the statement merge.
+ */
+ CanonicalMergeKey?: string[];
+ /**
+ * The data-bucket category the table syncs in, when it is split out of the manifest into a
+ * bucket with its own server revision. Mirrors the server VaultDataBucketCategory.
+ */
+ BucketCategory?: string;
+ /**
+ * The column whose contents are extracted into content-addressed blobs rather than kept inline
+ * in the manifest. Kind is the label reported to the server on upload (metrics / retention).
+ */
+ BlobColumn?: { Column: string; Kind: string };
+ /**
+ * Rows in other tables that reference this table's rows from inside manifest content. On a
+ * manifest split the referenced rows are reference-copied into the destination manifest so each
+ * manifest stays self-contained.
+ */
+ ReferencedBy?: { Table: string; Column: string }[];
+};
+
+/**
+ * All syncable client vault tables, in registry order. Order is load-bearing: 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
+ * upsert and two devices never mint competing rows. Listed after Items so a merge inserts the
+ * item first.
+ */
+ { Name: 'ItemStats', ManifestScoped: true, PrimaryKey: ['Id'], ItemChild: true, BucketCategory: 'Stats' },
+ /*
+ * FieldValues legacy statement merge: a field value matches on the field it belongs to (FieldKey
+ * for system fields, FieldDefinitionId for custom ones; exactly one is set), so independently
+ * minted rows of the same field converge. Canonical merge: 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 (id part empty on both sides) while a multi-value row
+ * matches by its OWNED 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.
+ */
+ {
+ Name: 'FieldValues',
+ ManifestScoped: true,
+ PrimaryKey: ['Id'],
+ ItemChild: true,
+ LegacyMergeKey: ['ManifestId', 'ItemId', 'FieldKey', 'FieldDefinitionId'],
+ CanonicalMergeKey: ['ManifestId', 'ItemId', 'FieldKey', 'FieldDefinitionId', 'Id'],
+ },
+ { Name: 'Folders', ManifestScoped: true, PrimaryKey: ['Id'], ItemChild: false },
+ {
+ Name: 'Tags',
+ ManifestScoped: true,
+ PrimaryKey: ['Id'],
+ ItemChild: false,
+ ReferencedBy: [{ Table: 'ItemTags', Column: 'TagId' }],
+ },
+ /*
+ * ItemTags is a pure join table keyed by its natural key; it carries no surrogate id so two devices tagging the same item converge on one row.
+ */
+ { Name: 'ItemTags', ManifestScoped: true, PrimaryKey: ['ItemId', 'TagId'], ItemChild: true },
+ {
+ Name: 'Attachments',
+ ManifestScoped: true,
+ PrimaryKey: ['Id'],
+ ItemChild: true,
+ BlobColumn: { Column: 'Blob', Kind: 'attachment' },
+ },
+ { Name: 'TotpCodes', ManifestScoped: true, PrimaryKey: ['Id'], ItemChild: true },
+ { Name: 'Passkeys', ManifestScoped: true, PrimaryKey: ['Id'], ItemChild: true },
+ {
+ Name: 'FieldDefinitions',
+ ManifestScoped: true,
+ PrimaryKey: ['Id'],
+ ItemChild: false,
+ ReferencedBy: [{ Table: 'FieldValues', Column: 'FieldDefinitionId' }, { Table: 'FieldHistories', Column: 'FieldDefinitionId' }],
+ },
+ /*
+ * FieldHistories canonical merge: every history row derives its id from (item, field, ChangedAt),
+ * so after normalization the natural key IS the identity: concurrent changes union (distinct
+ * ChangedAt), same-millisecond snapshots converge. Legacy statement merge keeps plain
+ * (ManifestId, Id).
+ */
+ {
+ Name: 'FieldHistories',
+ ManifestScoped: true,
+ PrimaryKey: ['Id'],
+ ItemChild: true,
+ CanonicalMergeKey: ['ManifestId', 'ItemId', 'FieldKey', 'FieldDefinitionId', 'ChangedAt'],
+ },
+ {
+ Name: 'Logos',
+ ManifestScoped: true,
+ PrimaryKey: ['Id'],
+ ItemChild: false,
+ BlobColumn: { Column: 'FileData', Kind: 'favicon' },
+ },
+ { Name: 'EncryptionKeys', ManifestScoped: true, PrimaryKey: ['Id'], ItemChild: false },
+ {
+ Name: 'Settings',
+ ManifestScoped: true,
+ PrimaryKey: ['Key'],
+ ItemChild: false,
+ BucketCategory: 'Settings',
+ },
+];
+
+/**
+ * The column names the shared (Rust) vault logic references by name, emitted as named constants so
+ * every module spells them identically. The full column set of each table is deliberately not
+ * modeled here: it lives in the SQL schema and is passed to the codec at runtime.
+ */
+export const VAULT_COLUMN_NAMES: string[] = [
+ 'Id',
+ 'ItemId',
+ 'TagId',
+ 'FieldKey',
+ 'FieldDefinitionId',
+ 'ValueIndex',
+ 'ChangedAt',
+ 'IsMultiValue',
+ 'ParentFolderId',
+ 'FolderId',
+ 'LogoId',
+ 'Kind',
+ 'Source',
+ 'FileData',
+ 'Blob',
+ 'UpdatedAt',
+ 'DeletedAt',
+ 'PublicKey',
+ 'IsPrimary',
+ 'IsDeleted',
+];
+
+/**
+ * Data-bucket categories in declaration order. This order, not the table order, decides the order
+ * buckets are emitted in; every category must be used by at least one VAULT_TABLES entry.
+ */
+export const VAULT_BUCKET_CATEGORIES: string[] = ['Settings', 'Stats'];
+
+/**
+ * Tables never serialized into the server-stored manifest: internal SQLite, platform, or EF
+ * bookkeeping that only exists at runtime and must not become part of a persisted manifest.
+ */
+export const VAULT_SKIP_TABLES: string[] = [
+ '__EFMigrationsHistory',
+ '__EFMigrationsLock',
+ 'sqlite_sequence',
+ 'android_metadata',
+ 'Manifests',
+];
+
+/**
+ * Tables that belong exclusively to the user's own (personal) vault, never to a shared manifest.
+ * Empty today; kept as the declaration point for a future personal-only table.
+ */
+export const VAULT_PERSONAL_TABLES: string[] = [];
+
+/**
+ * System field keys whose field holds multiple values, derived from SystemFieldRegistry
+ * (IsMultiValue). A value of such a field owns its row id: two devices each adding a value are
+ * adding two different things, so their ids are never derived.
+ */
+export const MULTI_VALUE_FIELD_KEYS: string[] = Object.values(SystemFieldRegistry)
+ .filter((field) => field.IsMultiValue)
+ .map((field) => field.FieldKey.toLowerCase());
+
+/**
+ * The per-manifest delivery-keypair table. Every manifest carries its own asymmetric keypair(s),
+ * stamped with that manifest's id.
+ */
+export const ENCRYPTION_KEYS_TABLE = 'EncryptionKeys';
+
+/**
+ * Local bookkeeping table the codec materializes into the vault DB: one row per manifest this
+ * vault is materialized from (Id, Name).
+ */
+export const MANIFESTS_TABLE = 'Manifests';
+
+/**
+ * Client-local SQLite table that carries the codec overflow inside the vault database itself:
+ * unknown row columns and tables preserved for forward compatibility.
+ */
+export const CODEC_OVERFLOW_TABLE = 'CodecOverflows';
+
+/**
+ * Fixed sentinel primary key of the single CodecOverflows row (deterministic on purpose:
+ * materialize output must not depend on a random source).
+ */
+export const CODEC_OVERFLOW_ROW_ID = '00000000-0000-0000-0000-00000000c0de';
+
+/**
+ * All-zero GUID used for default values which indicate unstamped rows (a ManifestId naming no
+ * manifest).
+ */
+export const UNSTAMPED_SCOPE_SENTINEL = '00000000-0000-0000-0000-000000000000';
+
+/**
+ * Default trash retention in days: how long a trashed item survives before the pruner deletes it.
+ */
+export const TRASH_RETENTION_DEFAULT_DAYS = 30;
diff --git a/core/models/src/vault/index.ts b/core/models/src/vault/index.ts
index 15611807d..b72cd81c0 100644
--- a/core/models/src/vault/index.ts
+++ b/core/models/src/vault/index.ts
@@ -16,3 +16,4 @@ export * from './CredentialCompat';
export * from './ItemMethods';
export * from './SystemFieldRegistry';
export * from './FieldHistory';
+export * from './VaultTableRegistry';