Skip to content

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.ts
index 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.mts
index 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.ts
index 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.js
index 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.mjs
index 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.tsx
index 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 migration
const 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.mts
index 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.ts
index 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.js
index 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.mjs
index 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.cs
index 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.cs
index 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.mts
index 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.ts
index 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.js
index 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.mjs
index 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.ts
new file mode 100644
index 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.ts
index 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 file
diff --git a/shared/vault-sql/src/utils/VersionCompatibility.ts b/shared/vault-sql/src/utils/VersionCompatibility.ts
new file mode 100644
index 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;
+}