Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
Add semantic versioning checks to vault SQL migrations to allow backwards compatible changes (#1313)
Leendert de Borstc1e8a9b44ec3
diff --git a/apps/browser-extension/src/utils/SqliteClient.ts b/apps/browser-extension/src/utils/SqliteClient.tsindex cc8a93bb5..73aa483a0 100644--- a/apps/browser-extension/src/utils/SqliteClient.ts+++ b/apps/browser-extension/src/utils/SqliteClient.ts@@ -4,7 +4,7 @@ import * as dateFormatter from '@/utils/dateFormatter';import type { Credential, EncryptionKey, PasswordSettings, TotpCode, Passkey } from '@/utils/dist/shared/models/vault';import type { Attachment } from '@/utils/dist/shared/models/vault';import type { VaultVersion } from '@/utils/dist/shared/vault-sql';-import { VaultSqlGenerator } from '@/utils/dist/shared/vault-sql';+import { VaultSqlGenerator, checkVersionCompatibility, extractVersionFromMigrationId } from '@/utils/dist/shared/vault-sql';import { VaultVersionIncompatibleError } from '@/utils/types/errors/VaultVersionIncompatibleError';import { t } from '@/i18n/StandaloneI18n';@@ -585,7 +585,7 @@ export class SqliteClient {/*** Get the current database version from the migrations history.* Returns the semantic version (e.g., "1.4.1") from the latest migration.- * Returns null if no migrations are found.+ * Uses semantic versioning to allow backwards-compatible minor/patch versions.*/public async getDatabaseVersion(): Promise<VaultVersion> {if (!this.db) {@@ -604,27 +604,43 @@ export class SqliteClient {throw new Error('No migrations found in the database.');}- // Extract version using regex - matches patterns like "20240917191243_1.4.1-RenameAttachmentsPlural"+ // Extract version from migration ID (e.g., "20240917191243_1.4.1-RenameAttachmentsPlural" -> "1.4.1")const migrationId = results[0].MigrationId;- const versionRegex = /_(\d+\.\d+\.\d+)-/;- const versionMatch = versionRegex.exec(migrationId);+ const databaseVersion = extractVersionFromMigrationId(migrationId);- let currentVersion = null;- if (versionMatch?.[1]) {- currentVersion = versionMatch[1];+ if (!databaseVersion) {+ throw new Error('Could not extract version from migration ID');}- // Get all available vault versions to get the revision number of the current version.- const vaultSqlGenerator = new VaultSqlGenerator();- const allVersions = vaultSqlGenerator.getAllVersions();- const currentVersionRevision = allVersions.find(v => v.version === currentVersion);+ // Check version compatibility using semantic versioning+ const compatibilityResult = checkVersionCompatibility(databaseVersion);- if (!currentVersionRevision) {+ if (!compatibilityResult.isCompatible) {const errorMessage = await t('common.errors.browserExtensionOutdated');throw new VaultVersionIncompatibleError(errorMessage);}- return currentVersionRevision;+ // If the version is known, return the full version info+ if (compatibilityResult.isKnownVersion && compatibilityResult.clientVersion) {+ return compatibilityResult.clientVersion;+ }++ /*+ * Version is unknown but compatible (same major version).+ * Create a VaultVersion object with the actual database version but use the latest client's revision number.+ * This allows older clients to work with newer backwards-compatible database versions.+ */+ const vaultSqlGenerator = new VaultSqlGenerator();+ const latestClientVersion = vaultSqlGenerator.getLatestVersion();++ // Return a version object with the actual database version string but the latest known revision+ return {+ revision: latestClientVersion.revision,+ version: databaseVersion, // Use the actual database version (e.g., "1.7.0")+ description: `Unknown version ${databaseVersion} (backwards compatible)`,+ releaseVersion: latestClientVersion.releaseVersion,+ compatibleUpToVersion: latestClientVersion.compatibleUpToVersion+ };} catch (error) {console.error('Error getting database version:', error);throw error;diff --git a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.mts b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.mtsindex f8cbb4705..bb4891590 100644--- a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.mts+++ b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.mts@@ -135,4 +135,64 @@ declare const MIGRATION_SCRIPTS: Record<number, string>;*/declare const CreateVaultSqlGenerator: () => VaultSqlGenerator;-export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo };+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++/**+ * Result of version compatibility check+ */+type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;+ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;+ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;+ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;+ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;+ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+};+/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+declare function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult;+/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+declare function extractVersionFromMigrationId(migrationId: string): string | null;++export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo, type VersionCompatibilityResult, checkVersionCompatibility, extractVersionFromMigrationId };diff --git a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.ts b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.tsindex f8cbb4705..bb4891590 100644--- a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.ts+++ b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.d.ts@@ -135,4 +135,64 @@ declare const MIGRATION_SCRIPTS: Record<number, string>;*/declare const CreateVaultSqlGenerator: () => VaultSqlGenerator;-export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo };+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++/**+ * Result of version compatibility check+ */+type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;+ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;+ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;+ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;+ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;+ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+};+/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+declare function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult;+/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+declare function extractVersionFromMigrationId(migrationId: string): string | null;++export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo, type VersionCompatibilityResult, checkVersionCompatibility, extractVersionFromMigrationId };diff --git a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.js b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.jsindex 920d984cc..d70e2ee3b 100644--- a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.js+++ b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.js@@ -27,7 +27,9 @@ __export(index_exports, {CreateVaultSqlGenerator: () => CreateVaultSqlGenerator,MIGRATION_SCRIPTS: () => MIGRATION_SCRIPTS,VAULT_VERSIONS: () => VAULT_VERSIONS,- VaultSqlGenerator: () => VaultSqlGenerator+ VaultSqlGenerator: () => VaultSqlGenerator,+ checkVersionCompatibility: () => checkVersionCompatibility,+ extractVersionFromMigrationId: () => extractVersionFromMigrationId});module.exports = __toCommonJS(index_exports);@@ -1583,11 +1585,77 @@ var VaultSqlGenerator = class {var CreateVaultSqlGenerator = () => {return new VaultSqlGenerator();};++// src/utils/VersionCompatibility.ts+function parseSemanticVersion(version) {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);+ if (!match) {+ return null;+ }+ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}+function checkVersionCompatibility(databaseVersion) {+ const dbVersion = parseSemanticVersion(databaseVersion);+ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const knownVersion = VAULT_VERSIONS.find((v) => v.version === databaseVersion);+ if (knownVersion) {+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);+ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference && (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);+ const isCompatible = !isMajorVersionDifference;+ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}+function extractVersionFromMigrationId(migrationId) {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);+ return versionMatch?.[1] ?? null;+}// Annotate the CommonJS export names for ESM import in node:0 && (module.exports = {COMPLETE_SCHEMA_SQL,CreateVaultSqlGenerator,MIGRATION_SCRIPTS,VAULT_VERSIONS,- VaultSqlGenerator+ VaultSqlGenerator,+ checkVersionCompatibility,+ extractVersionFromMigrationId});diff --git a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.mjs b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.mjsindex 9bb83929b..8418edbf1 100644--- a/apps/browser-extension/src/utils/dist/shared/vault-sql/index.mjs+++ b/apps/browser-extension/src/utils/dist/shared/vault-sql/index.mjs@@ -1554,10 +1554,76 @@ var VaultSqlGenerator = class {var CreateVaultSqlGenerator = () => {return new VaultSqlGenerator();};++// src/utils/VersionCompatibility.ts+function parseSemanticVersion(version) {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);+ if (!match) {+ return null;+ }+ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}+function checkVersionCompatibility(databaseVersion) {+ const dbVersion = parseSemanticVersion(databaseVersion);+ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const knownVersion = VAULT_VERSIONS.find((v) => v.version === databaseVersion);+ if (knownVersion) {+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);+ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference && (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);+ const isCompatible = !isMajorVersionDifference;+ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}+function extractVersionFromMigrationId(migrationId) {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);+ return versionMatch?.[1] ?? null;+}export {COMPLETE_SCHEMA_SQL,CreateVaultSqlGenerator,MIGRATION_SCRIPTS,VAULT_VERSIONS,- VaultSqlGenerator+ VaultSqlGenerator,+ checkVersionCompatibility,+ extractVersionFromMigrationId};diff --git a/apps/mobile-app/utils/SqliteClient.tsx b/apps/mobile-app/utils/SqliteClient.tsxindex 975b7e725..74c0c093c 100644--- a/apps/mobile-app/utils/SqliteClient.tsx+++ b/apps/mobile-app/utils/SqliteClient.tsx@@ -2,7 +2,7 @@ import { Buffer } from 'buffer';import type { EncryptionKeyDerivationParams, VaultMetadata } from '@/utils/dist/shared/models/metadata';import type { Attachment, Credential, EncryptionKey, PasswordSettings, TotpCode, Passkey } from '@/utils/dist/shared/models/vault';-import { VaultSqlGenerator, VaultVersion } from '@/utils/dist/shared/vault-sql';+import { VaultSqlGenerator, VaultVersion, checkVersionCompatibility, extractVersionFromMigrationId } from '@/utils/dist/shared/vault-sql';import { VaultVersionIncompatibleError } from '@/utils/types/errors/VaultVersionIncompatibleError';import NativeVaultManager from '@/specs/NativeVaultManager';@@ -657,11 +657,9 @@ class SqliteClient {/*** Get the current database version from the migrations history.* Returns the internal version information that matches the current database version.- * Returns null if no matching version is found.+ * Uses semantic versioning to allow backwards-compatible minor/patch versions.*/public async getDatabaseVersion(): Promise<VaultVersion> {- let currentVersion = '';-// Query the migrations history table for the latest migrationconst results = await this.executeQuery<{ MigrationId: string }>(`SELECT MigrationId@@ -673,25 +671,42 @@ class SqliteClient {throw new Error('No migrations found');}- // Extract version using regex - matches patterns like "20240917191243_1.4.1-RenameAttachmentsPlural"+ // Extract version from migration ID (e.g., "20240917191243_1.4.1-RenameAttachmentsPlural" -> "1.4.1")const migrationId = results[0].MigrationId;- const versionRegex = /_(\d+\.\d+\.\d+)-/;- const versionMatch = versionRegex.exec(migrationId);+ const databaseVersion = extractVersionFromMigrationId(migrationId);- if (versionMatch?.[1]) {- currentVersion = versionMatch[1];+ if (!databaseVersion) {+ throw new Error('Could not extract version from migration ID');}- // Get all available vault versions to get the revision number of the current version.- const vaultSqlGenerator = new VaultSqlGenerator();- const allVersions = vaultSqlGenerator.getAllVersions();- const currentVersionRevision = allVersions.find(v => v.version === currentVersion);+ // Check version compatibility using semantic versioning+ const compatibilityResult = checkVersionCompatibility(databaseVersion);- if (!currentVersionRevision) {+ if (!compatibilityResult.isCompatible) {throw new VaultVersionIncompatibleError('vault.errors.appOutdated');}- return currentVersionRevision;+ // If the version is known, return the full version info+ if (compatibilityResult.isKnownVersion && compatibilityResult.clientVersion) {+ return compatibilityResult.clientVersion;+ }++ /*+ * Version is unknown but compatible (same major version).+ * Create a VaultVersion object with the actual database version but use the latest client's revision number.+ * This allows older clients to work with newer backwards-compatible database versions.+ */+ const vaultSqlGenerator = new VaultSqlGenerator();+ const latestClientVersion = vaultSqlGenerator.getLatestVersion();++ // Return a version object with the actual database version string but the latest known revision+ return {+ revision: latestClientVersion.revision,+ version: databaseVersion, // Use the actual database version (e.g., "1.7.0")+ description: `Unknown version ${databaseVersion} (backwards compatible)`,+ releaseVersion: latestClientVersion.releaseVersion,+ compatibleUpToVersion: latestClientVersion.compatibleUpToVersion+ };}/**diff --git a/apps/mobile-app/utils/dist/shared/vault-sql/index.d.mts b/apps/mobile-app/utils/dist/shared/vault-sql/index.d.mtsindex f8cbb4705..bb4891590 100644--- a/apps/mobile-app/utils/dist/shared/vault-sql/index.d.mts+++ b/apps/mobile-app/utils/dist/shared/vault-sql/index.d.mts@@ -135,4 +135,64 @@ declare const MIGRATION_SCRIPTS: Record<number, string>;*/declare const CreateVaultSqlGenerator: () => VaultSqlGenerator;-export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo };+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++/**+ * Result of version compatibility check+ */+type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;+ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;+ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;+ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;+ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;+ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+};+/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+declare function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult;+/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+declare function extractVersionFromMigrationId(migrationId: string): string | null;++export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo, type VersionCompatibilityResult, checkVersionCompatibility, extractVersionFromMigrationId };diff --git a/apps/mobile-app/utils/dist/shared/vault-sql/index.d.ts b/apps/mobile-app/utils/dist/shared/vault-sql/index.d.tsindex f8cbb4705..bb4891590 100644--- a/apps/mobile-app/utils/dist/shared/vault-sql/index.d.ts+++ b/apps/mobile-app/utils/dist/shared/vault-sql/index.d.ts@@ -135,4 +135,64 @@ declare const MIGRATION_SCRIPTS: Record<number, string>;*/declare const CreateVaultSqlGenerator: () => VaultSqlGenerator;-export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo };+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++/**+ * Result of version compatibility check+ */+type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;+ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;+ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;+ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;+ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;+ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+};+/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+declare function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult;+/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+declare function extractVersionFromMigrationId(migrationId: string): string | null;++export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo, type VersionCompatibilityResult, checkVersionCompatibility, extractVersionFromMigrationId };diff --git a/apps/mobile-app/utils/dist/shared/vault-sql/index.js b/apps/mobile-app/utils/dist/shared/vault-sql/index.jsindex 920d984cc..d70e2ee3b 100644--- a/apps/mobile-app/utils/dist/shared/vault-sql/index.js+++ b/apps/mobile-app/utils/dist/shared/vault-sql/index.js@@ -27,7 +27,9 @@ __export(index_exports, {CreateVaultSqlGenerator: () => CreateVaultSqlGenerator,MIGRATION_SCRIPTS: () => MIGRATION_SCRIPTS,VAULT_VERSIONS: () => VAULT_VERSIONS,- VaultSqlGenerator: () => VaultSqlGenerator+ VaultSqlGenerator: () => VaultSqlGenerator,+ checkVersionCompatibility: () => checkVersionCompatibility,+ extractVersionFromMigrationId: () => extractVersionFromMigrationId});module.exports = __toCommonJS(index_exports);@@ -1583,11 +1585,77 @@ var VaultSqlGenerator = class {var CreateVaultSqlGenerator = () => {return new VaultSqlGenerator();};++// src/utils/VersionCompatibility.ts+function parseSemanticVersion(version) {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);+ if (!match) {+ return null;+ }+ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}+function checkVersionCompatibility(databaseVersion) {+ const dbVersion = parseSemanticVersion(databaseVersion);+ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const knownVersion = VAULT_VERSIONS.find((v) => v.version === databaseVersion);+ if (knownVersion) {+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);+ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference && (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);+ const isCompatible = !isMajorVersionDifference;+ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}+function extractVersionFromMigrationId(migrationId) {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);+ return versionMatch?.[1] ?? null;+}// Annotate the CommonJS export names for ESM import in node:0 && (module.exports = {COMPLETE_SCHEMA_SQL,CreateVaultSqlGenerator,MIGRATION_SCRIPTS,VAULT_VERSIONS,- VaultSqlGenerator+ VaultSqlGenerator,+ checkVersionCompatibility,+ extractVersionFromMigrationId});diff --git a/apps/mobile-app/utils/dist/shared/vault-sql/index.mjs b/apps/mobile-app/utils/dist/shared/vault-sql/index.mjsindex 9bb83929b..8418edbf1 100644--- a/apps/mobile-app/utils/dist/shared/vault-sql/index.mjs+++ b/apps/mobile-app/utils/dist/shared/vault-sql/index.mjs@@ -1554,10 +1554,76 @@ var VaultSqlGenerator = class {var CreateVaultSqlGenerator = () => {return new VaultSqlGenerator();};++// src/utils/VersionCompatibility.ts+function parseSemanticVersion(version) {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);+ if (!match) {+ return null;+ }+ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}+function checkVersionCompatibility(databaseVersion) {+ const dbVersion = parseSemanticVersion(databaseVersion);+ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const knownVersion = VAULT_VERSIONS.find((v) => v.version === databaseVersion);+ if (knownVersion) {+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);+ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference && (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);+ const isCompatible = !isMajorVersionDifference;+ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}+function extractVersionFromMigrationId(migrationId) {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);+ return versionMatch?.[1] ?? null;+}export {COMPLETE_SCHEMA_SQL,CreateVaultSqlGenerator,MIGRATION_SCRIPTS,VAULT_VERSIONS,- VaultSqlGenerator+ VaultSqlGenerator,+ checkVersionCompatibility,+ extractVersionFromMigrationId};diff --git a/apps/server/AliasVault.Client/Services/Database/DbService.cs b/apps/server/AliasVault.Client/Services/Database/DbService.csindex 3db9b7ce9..8c142ac14 100644--- a/apps/server/AliasVault.Client/Services/Database/DbService.cs+++ b/apps/server/AliasVault.Client/Services/Database/DbService.cs@@ -381,6 +381,7 @@ public sealed class DbService : IDisposable/// <summary>/// Get the current version (applied migration) of the database that is loaded in memory.+ /// Uses semantic versioning to allow backwards-compatible minor/patch versions./// </summary>/// <returns>Version as string.</returns>public async Task<SqlVaultVersion> GetCurrentDatabaseVersionAsync()@@ -403,17 +404,47 @@ public sealed class DbService : IDisposable}}+ // Check version compatibility using semantic versioning+ var isCompatible = await _jsInteropService.IsVersionCompatibleAsync(currentVersion);++ if (!isCompatible)+ {+ // Version is incompatible (different major version)+ return new SqlVaultVersion+ {+ Revision = 0,+ Version = _UNKNOWN_VERSION,+ Description = _UNKNOWN_VERSION,+ ReleaseVersion = _UNKNOWN_VERSION,+ CompatibleUpToVersion = _UNKNOWN_VERSION,+ };+ }+// Get all available vault versions to get the revision number of the current version.var allVersions = await _jsInteropService.GetAllVaultVersionsAsync();var currentVersionRevision = allVersions.FirstOrDefault(v => v.Version == currentVersion);- return currentVersionRevision ?? new SqlVaultVersion+ // If the version is known, return it+ if (currentVersionRevision is not null){- Revision = 0,- Version = _UNKNOWN_VERSION,- Description = _UNKNOWN_VERSION,- ReleaseVersion = _UNKNOWN_VERSION,- CompatibleUpToVersion = _UNKNOWN_VERSION,+ return currentVersionRevision;+ }++ /*+ * Version is unknown but compatible (same major version).+ * Create a version object with the actual database version but use the latest client's revision number.+ * This allows older clients to work with newer backwards-compatible database versions.+ */+ var latestClientVersion = await _jsInteropService.GetLatestVaultVersionAsync();++ // Return a version object with the actual database version string but the latest known revision+ return new SqlVaultVersion+ {+ Revision = latestClientVersion.Revision,+ Version = currentVersion, // Use the actual database version (e.g., "1.7.0")+ Description = $"Unknown version {currentVersion} (backwards compatible)",+ ReleaseVersion = latestClientVersion.ReleaseVersion,+ CompatibleUpToVersion = latestClientVersion.CompatibleUpToVersion,};}diff --git a/apps/server/AliasVault.Client/Services/JsInterop/JsInteropService.cs b/apps/server/AliasVault.Client/Services/JsInterop/JsInteropService.csindex 4fc60280b..e2266c3fc 100644--- a/apps/server/AliasVault.Client/Services/JsInterop/JsInteropService.cs+++ b/apps/server/AliasVault.Client/Services/JsInterop/JsInteropService.cs@@ -541,6 +541,31 @@ public sealed class JsInteropService(IJSRuntime jsRuntime)};}+ /// <summary>+ /// Checks if a database version is compatible with the current client using semantic versioning.+ /// Returns true if the version is compatible (known version or same major version).+ /// Returns false if the version is incompatible (different major version).+ /// </summary>+ /// <param name="databaseVersion">The database version to check (e.g., "1.6.0").</param>+ /// <returns>True if compatible, false otherwise.</returns>+ public async Task<bool> IsVersionCompatibleAsync(string databaseVersion)+ {+ try+ {+ if (_vaultSqlInteropModule == null)+ {+ await InitializeAsync();+ }++ var result = await _vaultSqlInteropModule!.InvokeAsync<JsonElement>("checkVersionCompatibility", databaseVersion);+ return result.GetProperty("isCompatible").GetBoolean();+ }+ catch (JSException)+ {+ return false;+ }+ }+/// <summary>/// Gets SQL commands to upgrade vault from current to target migration./// </summary>diff --git a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.mts b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.mtsindex f8cbb4705..bb4891590 100644--- a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.mts+++ b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.mts@@ -135,4 +135,64 @@ declare const MIGRATION_SCRIPTS: Record<number, string>;*/declare const CreateVaultSqlGenerator: () => VaultSqlGenerator;-export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo };+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++/**+ * Result of version compatibility check+ */+type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;+ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;+ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;+ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;+ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;+ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+};+/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+declare function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult;+/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+declare function extractVersionFromMigrationId(migrationId: string): string | null;++export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo, type VersionCompatibilityResult, checkVersionCompatibility, extractVersionFromMigrationId };diff --git a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.ts b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.tsindex f8cbb4705..bb4891590 100644--- a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.ts+++ b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.d.ts@@ -135,4 +135,64 @@ declare const MIGRATION_SCRIPTS: Record<number, string>;*/declare const CreateVaultSqlGenerator: () => VaultSqlGenerator;-export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo };+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++/**+ * Result of version compatibility check+ */+type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;+ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;+ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;+ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;+ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;+ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+};+/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+declare function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult;+/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+declare function extractVersionFromMigrationId(migrationId: string): string | null;++export { COMPLETE_SCHEMA_SQL, CreateVaultSqlGenerator, MIGRATION_SCRIPTS, type SqlGenerationResult, VAULT_VERSIONS, VaultSqlGenerator, type VaultVersion, type VaultVersionInfo, type VersionCompatibilityResult, checkVersionCompatibility, extractVersionFromMigrationId };diff --git a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.js b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.jsindex 920d984cc..d70e2ee3b 100644--- a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.js+++ b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.js@@ -27,7 +27,9 @@ __export(index_exports, {CreateVaultSqlGenerator: () => CreateVaultSqlGenerator,MIGRATION_SCRIPTS: () => MIGRATION_SCRIPTS,VAULT_VERSIONS: () => VAULT_VERSIONS,- VaultSqlGenerator: () => VaultSqlGenerator+ VaultSqlGenerator: () => VaultSqlGenerator,+ checkVersionCompatibility: () => checkVersionCompatibility,+ extractVersionFromMigrationId: () => extractVersionFromMigrationId});module.exports = __toCommonJS(index_exports);@@ -1583,11 +1585,77 @@ var VaultSqlGenerator = class {var CreateVaultSqlGenerator = () => {return new VaultSqlGenerator();};++// src/utils/VersionCompatibility.ts+function parseSemanticVersion(version) {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);+ if (!match) {+ return null;+ }+ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}+function checkVersionCompatibility(databaseVersion) {+ const dbVersion = parseSemanticVersion(databaseVersion);+ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const knownVersion = VAULT_VERSIONS.find((v) => v.version === databaseVersion);+ if (knownVersion) {+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);+ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference && (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);+ const isCompatible = !isMajorVersionDifference;+ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}+function extractVersionFromMigrationId(migrationId) {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);+ return versionMatch?.[1] ?? null;+}// Annotate the CommonJS export names for ESM import in node:0 && (module.exports = {COMPLETE_SCHEMA_SQL,CreateVaultSqlGenerator,MIGRATION_SCRIPTS,VAULT_VERSIONS,- VaultSqlGenerator+ VaultSqlGenerator,+ checkVersionCompatibility,+ extractVersionFromMigrationId});diff --git a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.mjs b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.mjsindex 9bb83929b..8418edbf1 100644--- a/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.mjs+++ b/apps/server/AliasVault.Client/wwwroot/js/dist/shared/vault-sql/index.mjs@@ -1554,10 +1554,76 @@ var VaultSqlGenerator = class {var CreateVaultSqlGenerator = () => {return new VaultSqlGenerator();};++// src/utils/VersionCompatibility.ts+function parseSemanticVersion(version) {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);+ if (!match) {+ return null;+ }+ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}+function checkVersionCompatibility(databaseVersion) {+ const dbVersion = parseSemanticVersion(databaseVersion);+ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const knownVersion = VAULT_VERSIONS.find((v) => v.version === databaseVersion);+ if (knownVersion) {+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);+ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference && (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);+ const isCompatible = !isMajorVersionDifference;+ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}+function extractVersionFromMigrationId(migrationId) {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);+ return versionMatch?.[1] ?? null;+}export {COMPLETE_SCHEMA_SQL,CreateVaultSqlGenerator,MIGRATION_SCRIPTS,VAULT_VERSIONS,- VaultSqlGenerator+ VaultSqlGenerator,+ checkVersionCompatibility,+ extractVersionFromMigrationId};diff --git a/shared/vault-sql/src/__tests__/VersionCompatibility.test.ts b/shared/vault-sql/src/__tests__/VersionCompatibility.test.tsnew file mode 100644index 000000000..aee1f95d0--- /dev/null+++ b/shared/vault-sql/src/__tests__/VersionCompatibility.test.ts@@ -0,0 +1,140 @@+import { describe, it, expect } from 'vitest';+import { checkVersionCompatibility, extractVersionFromMigrationId } from '../utils/VersionCompatibility';++describe('VersionCompatibility', () => {+ describe('extractVersionFromMigrationId', () => {+ it('should extract version from valid migration ID', () => {+ const result = extractVersionFromMigrationId('20240917191243_1.4.1-RenameAttachmentsPlural');+ expect(result).toBe('1.4.1');+ });++ it('should extract version from different migration ID format', () => {+ const result = extractVersionFromMigrationId('20250310131554_1.5.0-AddTotpCodes');+ expect(result).toBe('1.5.0');+ });++ it('should return null for invalid migration ID', () => {+ const result = extractVersionFromMigrationId('InvalidMigrationId');+ expect(result).toBeNull();+ });++ it('should return null for migration ID without version', () => {+ const result = extractVersionFromMigrationId('20240917191243-NoVersion');+ expect(result).toBeNull();+ });+ });++ describe('checkVersionCompatibility', () => {+ describe('Known versions', () => {+ it('should be compatible with known version 1.0.0', () => {+ const result = checkVersionCompatibility('1.0.0');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(true);+ expect(result.isMajorVersionDifference).toBe(false);+ expect(result.clientVersion).toBeDefined();+ });++ it('should be compatible with known version 1.5.0', () => {+ const result = checkVersionCompatibility('1.5.0');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(true);+ expect(result.isMajorVersionDifference).toBe(false);+ });++ it('should be compatible with known version 1.6.0', () => {+ const result = checkVersionCompatibility('1.6.0');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(true);+ });+ });++ describe('Unknown versions - Same major version (backwards compatible)', () => {+ it('should be compatible with unknown patch version (1.6.1)', () => {+ const result = checkVersionCompatibility('1.6.1');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(false);+ expect(result.isMinorVersionDifference).toBe(true);+ });++ it('should be compatible with unknown patch version (1.6.2)', () => {+ const result = checkVersionCompatibility('1.6.2');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(false);+ expect(result.isMinorVersionDifference).toBe(true);+ });++ it('should be compatible with unknown minor version (1.49.0)', () => {+ const result = checkVersionCompatibility('1.49.0');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(false);+ expect(result.isMinorVersionDifference).toBe(true);+ });++ it('should be compatible with unknown minor+patch version (1.49.5)', () => {+ const result = checkVersionCompatibility('1.49.5');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(false);+ expect(result.isMinorVersionDifference).toBe(true);+ });+ });++ describe('Unknown versions - Different major version (incompatible)', () => {+ it('should be incompatible with major version 26.0.0', () => {+ const result = checkVersionCompatibility('26.0.0');+ expect(result.isCompatible).toBe(false);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(true);+ expect(result.isMinorVersionDifference).toBe(false);+ });++ it('should be incompatible with major version 31.1.5', () => {+ const result = checkVersionCompatibility('31.1.5');+ expect(result.isCompatible).toBe(false);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(true);+ });++ it('should be incompatible with major version 0.5.0', () => {+ const result = checkVersionCompatibility('0.5.0');+ expect(result.isCompatible).toBe(false);+ expect(result.isKnownVersion).toBe(false);+ expect(result.isMajorVersionDifference).toBe(true);+ });+ });++ describe('Invalid versions', () => {+ it('should be incompatible with invalid version format', () => {+ const result = checkVersionCompatibility('invalid');+ expect(result.isCompatible).toBe(false);+ });++ it('should be incompatible with incomplete version', () => {+ const result = checkVersionCompatibility('1.5');+ expect(result.isCompatible).toBe(false);+ });++ it('should be incompatible with empty version', () => {+ const result = checkVersionCompatibility('');+ expect(result.isCompatible).toBe(false);+ });+ });++ describe('Edge cases', () => {+ it('should handle version with extra characters', () => {+ const result = checkVersionCompatibility('1.5.0-beta');+ expect(result.isCompatible).toBe(false);+ });++ it('should handle version with leading zeros (treats as 1.5.0)', () => {+ // Note: parseInt handles leading zeros, so "01.05.00" becomes 1.5.0+ const result = checkVersionCompatibility('01.05.00');+ expect(result.isCompatible).toBe(true);+ expect(result.isKnownVersion).toBe(false);+ });+ });+ });+});diff --git a/shared/vault-sql/src/index.ts b/shared/vault-sql/src/index.tsindex c55686b80..765e905fd 100644--- a/shared/vault-sql/src/index.ts+++ b/shared/vault-sql/src/index.ts@@ -2,4 +2,5 @@ export * from './types/VaultVersion';export * from './sql/VaultSqlGenerator';export * from './sql/VaultVersions';export * from './sql/SqlConstants';-export * from './factories/VaultSqlGeneratorFactory';\ No newline at end of file+export * from './factories/VaultSqlGeneratorFactory';+export * from './utils/VersionCompatibility';\ No newline at end of filediff --git a/shared/vault-sql/src/utils/VersionCompatibility.ts b/shared/vault-sql/src/utils/VersionCompatibility.tsnew file mode 100644index 000000000..999aa9488--- /dev/null+++ b/shared/vault-sql/src/utils/VersionCompatibility.ts@@ -0,0 +1,154 @@+/**+ * Utility for checking vault version compatibility using semantic versioning+ */++import { VAULT_VERSIONS } from '../sql/VaultVersions';+import type { VaultVersion } from '../types/VaultVersion';++/**+ * Result of version compatibility check+ */+export type VersionCompatibilityResult = {+ /**+ * Whether the database version is compatible with the current client+ */+ isCompatible: boolean;++ /**+ * The database version string (e.g., "1.6.1")+ */+ databaseVersion: string;++ /**+ * The current client's version info (if found)+ */+ clientVersion?: VaultVersion;++ /**+ * Whether the database version is known to the client+ */+ isKnownVersion: boolean;++ /**+ * Whether this is a major version difference+ */+ isMajorVersionDifference: boolean;++ /**+ * Whether this is a minor/patch version difference+ */+ isMinorVersionDifference: boolean;+}++/**+ * Parse a semantic version string into its components+ */+function parseSemanticVersion(version: string): { major: number; minor: number; patch: number } | null {+ const versionRegex = /^(\d+)\.(\d+)\.(\d+)$/;+ const match = versionRegex.exec(version);++ if (!match) {+ return null;+ }++ return {+ major: parseInt(match[1], 10),+ minor: parseInt(match[2], 10),+ patch: parseInt(match[3], 10)+ };+}++/**+ * Check if a database version is compatible with the current client using semantic versioning rules.+ *+ * Compatibility rules:+ * 1. If the database version is known to the client (exists in VAULT_VERSIONS), it's compatible+ * 2. If the database version is unknown:+ * - Same major version (e.g., 1.6.1 vs 1.6.2 or 1.7.0): Compatible (backwards compatible minor/patch changes)+ * - Different major version (e.g., 1.6.1 vs 2.0.0): Incompatible (breaking changes)+ *+ * This allows newer database versions with backwards-compatible changes to work with older clients,+ * while still preventing incompatibilities from major version changes.+ *+ * @param databaseVersion - The version string from the database migration (e.g., "1.6.1")+ * @returns VersionCompatibilityResult with compatibility information+ */+export function checkVersionCompatibility(databaseVersion: string): VersionCompatibilityResult {+ // Parse the database version+ const dbVersion = parseSemanticVersion(databaseVersion);++ if (!dbVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }++ // Check if this version is known to the client+ const knownVersion = VAULT_VERSIONS.find(v => v.version === databaseVersion);++ if (knownVersion) {+ // Known version - always compatible+ return {+ isCompatible: true,+ databaseVersion,+ clientVersion: knownVersion,+ isKnownVersion: true,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }++ /*+ * Unknown version - check semantic versioning compatibility+ * Find the latest version known to this client+ */+ const latestClientVersion = VAULT_VERSIONS[VAULT_VERSIONS.length - 1];+ const clientVersion = parseSemanticVersion(latestClientVersion.version);++ if (!clientVersion) {+ return {+ isCompatible: false,+ databaseVersion,+ isKnownVersion: false,+ isMajorVersionDifference: false,+ isMinorVersionDifference: false+ };+ }++ /* Check if major versions match */+ const isMajorVersionDifference = dbVersion.major !== clientVersion.major;+ const isMinorVersionDifference = !isMajorVersionDifference &&+ (dbVersion.minor !== clientVersion.minor || dbVersion.patch !== clientVersion.patch);++ /* Compatible if same major version (backwards compatible minor/patch changes) */+ const isCompatible = !isMajorVersionDifference;++ return {+ isCompatible,+ databaseVersion,+ clientVersion: latestClientVersion,+ isKnownVersion: false,+ isMajorVersionDifference,+ isMinorVersionDifference+ };+}++/**+ * Extract version from a migration ID.+ *+ * Migration IDs follow the pattern: "YYYYMMDDHHMMSS_X.Y.Z-Description"+ * For example: "20240917191243_1.4.1-RenameAttachmentsPlural"+ *+ * @param migrationId - The migration ID from __EFMigrationsHistory+ * @returns The version string (e.g., "1.4.1") or null if not found+ */+export function extractVersionFromMigrationId(migrationId: string): string | null {+ const versionRegex = /_(\d+\.\d+\.\d+)-/;+ const versionMatch = versionRegex.exec(migrationId);++ return versionMatch?.[1] ?? null;+}