@vrtmrz/livesync-commonlib 0.1.36 → 0.1.38

package/dist/common/settingConstants.js

@@ -71,7 +71,7 @@ const SettingInformation = {
   },
   configPassphrase: {
     name: "Passphrase of sensitive configuration items",
-    desc: "This passphrase will not be copied to another device. It will be set to `Default` until you configure it again."
+    desc: "SettingService.ConfigurationPassphraseDeviceLocalDescription"
   },
   configPassphraseStore: {
     name: "Encrypting sensitive configuration items"

package/dist/services/base/CommonlibMessages.d.ts

@@ -5,6 +5,13 @@
  * these messages so that symbolic keys are never exposed to users.
  */
 export declare const commonlibEnglishMessages: {
+    readonly "SettingService.ConfigurationPassphraseDeviceLocalDescription": "This passphrase stays on this device. When another device needs to decrypt protected settings without a saved key, enter the same passphrase at start-up.";
+    readonly "SettingService.ConfigurationPassphraseTitle": "Configuration passphrase";
+    readonly "SettingService.ConfigurationPassphraseRetryTitle": "Configuration could not be decrypted. Enter the configuration passphrase again.";
+    readonly "SettingService.ConfigurationPassphraseCancelled": "Configuration passphrase entry was cancelled or unavailable. Start-up was stopped; saved settings were retained.";
+    readonly "SettingService.ConfigurationEncryptionSaveFailed": "Configuration encryption could not be saved. Verify the saved settings and device key before retrying.";
+    readonly "SettingService.ConfigurationPassphraseRollbackFailed": "The configuration passphrase could not be restored after a write failure. Verify the saved settings and device key before retrying.";
+    readonly "SettingService.ConfigurationCouldNotBeDecrypted": "Existing configuration could not be decrypted. The configuration key was not changed.";
     readonly "(BETA) Always overwrite with a newer file": "(BETA) Always overwrite with a newer file";
     readonly "(Beta) Use ignore files": "(Beta) Use ignore files";
     readonly "(Days passed, 0 to disable automatic-deletion)": "(Days passed, 0 to disable automatic-deletion)";

package/dist/services/base/CommonlibMessages.js

@@ -1,4 +1,11 @@
 const commonlibEnglishMessages = {
+  "SettingService.ConfigurationPassphraseDeviceLocalDescription": "This passphrase stays on this device. When another device needs to decrypt protected settings without a saved key, enter the same passphrase at start-up.",
+  "SettingService.ConfigurationPassphraseTitle": "Configuration passphrase",
+  "SettingService.ConfigurationPassphraseRetryTitle": "Configuration could not be decrypted. Enter the configuration passphrase again.",
+  "SettingService.ConfigurationPassphraseCancelled": "Configuration passphrase entry was cancelled or unavailable. Start-up was stopped; saved settings were retained.",
+  "SettingService.ConfigurationEncryptionSaveFailed": "Configuration encryption could not be saved. Verify the saved settings and device key before retrying.",
+  "SettingService.ConfigurationPassphraseRollbackFailed": "The configuration passphrase could not be restored after a write failure. Verify the saved settings and device key before retrying.",
+  "SettingService.ConfigurationCouldNotBeDecrypted": "Existing configuration could not be decrypted. The configuration key was not changed.",
   "(BETA) Always overwrite with a newer file": "(BETA) Always overwrite with a newer file",
   "(Beta) Use ignore files": "(Beta) Use ignore files",
   "(Days passed, 0 to disable automatic-deletion)": "(Days passed, 0 to disable automatic-deletion)",

package/dist/services/base/IService.d.ts

@@ -1,6 +1,6 @@
 import type { FetchHttpHandler } from "@smithy/fetch-http-handler";
 import { type LOG_LEVEL } from "octagonal-wheels/common/logger";
-import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, RemotePreferredTweakResult, SettingsMigrationState, TweakAssessment, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
+import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, ConfigPassphraseStore, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, RemotePreferredTweakResult, SettingsMigrationState, TweakAssessment, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
 import type { LiveSyncLocalDB } from "../../pouchdb/LiveSyncLocalDB.js";
 import type { ReplicatorInstance } from "../../replication/ReplicatorInstance.js";
 import type { SimpleStore } from "octagonal-wheels/databases/SimpleStoreBase";
@@ -323,6 +323,8 @@ export interface ISettingService {
     deleteDeviceLocalConfig(key: string): void;
     onBeforeSaveSettingData(nextSettings: ObsidianLiveSyncSettings, previousSettings: ObsidianLiveSyncSettings): Promise<(Partial<ObsidianLiveSyncSettings> | void)[]>;
     saveSettingData(): Promise<void>;
+    /** Save a new configuration wrapper and its device-local key, retaining the protected values. */
+    changeConfigurationEncryption(store: ConfigPassphraseStore, passphrase?: string): Promise<void>;
     currentSettings(): ObsidianLiveSyncSettings;
     updateSettings(updateFn: (current: ObsidianLiveSyncSettings) => ObsidianLiveSyncSettings, saveImmediately?: boolean): Promise<void>;
     applyExternalSettings(partial: Partial<ObsidianLiveSyncSettings>, saveImmediately?: boolean): Promise<void>;

package/dist/services/base/SettingService.d.ts

@@ -1,4 +1,4 @@
-import { type ObsidianLiveSyncSettings, type SettingsMigrationState } from "../../common/types.js";
+import { type ConfigPassphraseStore, type ObsidianLiveSyncSettings, type SettingsMigrationState } from "../../common/types.js";
 import type { IAPIService, ISettingService } from "./IService.js";
 import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 import { createInstanceLogFunction } from "../lib/logUtils.js";
@@ -22,6 +22,7 @@ export declare abstract class SettingService<T extends ServiceContext = ServiceC
     protected abstract loadData(): Promise<ObsidianLiveSyncSettings | undefined>;
     private _lastPersistedSettings?;
     private _settingsMigrationState?;
+    private saveQueue;
     getSettingsMigrationState(): SettingsMigrationState | undefined;
     _log: ReturnType<typeof createInstanceLogFunction>;
     constructor(context: T, dependencies: SettingServiceDependencies);
@@ -63,6 +64,14 @@ export declare abstract class SettingService<T extends ServiceContext = ServiceC
      * Save the current settings to storage.
      */
     saveSettingData(): Promise<void>;
+    private serialiseSave;
+    /** Change the configuration wrapper without changing the protected plaintext values. */
+    changeConfigurationEncryption(store: ConfigPassphraseStore, passphrase?: string): Promise<void>;
+    private restoreConfigurationPassphrase;
+    private prepareConfigurationKeyChange;
+    private prepareSettingSave;
+    private writePreparedSettings;
+    private commitPreparedSettings;
     private encryptRemoteConfigurationUris;
     private hasManagedP2PProfileURI;
     private decryptRemoteConfigurationUris;
@@ -104,13 +113,15 @@ export declare abstract class SettingService<T extends ServiceContext = ServiceC
     applyExternalSettings(partial: Partial<ObsidianLiveSyncSettings>, saveImmediately?: boolean): Promise<void>;
     applyPartial(partial: Partial<ObsidianLiveSyncSettings>, saveImmediately?: boolean): Promise<void>;
     getPassphrase(settings: ObsidianLiveSyncSettings): Promise<string | false>;
-    private usedPassphrase;
+    private usedPassphrase?;
+    private getSavingPassphrase;
+    private rememberPassphrase;
     /**
      * Clear any used passphrase from memory.
      */
     clearUsedPassphrase(): void;
     decryptConfigurationItem(encrypted: string, passphrase: string): Promise<string | false>;
-    encryptConfigurationItem(src: string, settings: ObsidianLiveSyncSettings): Promise<string>;
+    encryptConfigurationItem(src: string, settings: ObsidianLiveSyncSettings, passphrase?: string): Promise<string>;
     private encryptPlainConfigurationItem;
     private encryptConfigurationItemWith;
     /**
@@ -118,6 +129,11 @@ export declare abstract class SettingService<T extends ServiceContext = ServiceC
      * @param settings The settings to decrypt.
      */
     decryptSettings(settings: ObsidianLiveSyncSettings): Promise<ObsidianLiveSyncSettings>;
+    private decryptSettingsWithPassphrase;
+    private hasProtectedConfiguration;
+    private validateStoredIdConfiguration;
+    private isPlainConfigurationUri;
+    private loadConfiguration;
     loadSettings(): Promise<void>;
     private tryDecodeJson;
     private cloneSettings;

package/dist/services/base/SettingService.js

@@ -13,7 +13,12 @@ import { ServiceBase } from "./ServiceBase.js";
 import { createInstanceLogFunction } from "../lib/logUtils.js";
 import { isCloudantURI } from "../../pouchdb/utils_couchdb.js";
 import { decryptString, encryptString } from "../../encryption/stringEncryption.js";
-import { encryptWithEphemeralSalt } from "octagonal-wheels/encryption/hkdf";
+import { encryptWithEphemeralSalt, HKDF_SALTED_ENCRYPTED_PREFIX } from "octagonal-wheels/encryption/hkdf";
+import {
+  ENCRYPT_V1_PREFIX_PROBABLY,
+  ENCRYPT_V2_PREFIX,
+  ENCRYPT_V3_PREFIX
+} from "octagonal-wheels/encryption/encryption";
 import {
   activateP2PRemoteConfiguration,
   activateRemoteConfiguration,
@@ -31,6 +36,8 @@ import {
   restoreConnectionSettings,
   selectConnectionSettings
 } from "../../common/models/setting.policy.js";
+class ConfigurationPassphraseError extends Error {
+}
 class SettingService extends ServiceBase {
   deviceAndVaultName = "";
   APIService;
@@ -44,6 +51,7 @@ class SettingService extends ServiceBase {
   }
   _lastPersistedSettings;
   _settingsMigrationState;
+  saveQueue = Promise.resolve();
   getSettingsMigrationState() {
     return this._settingsMigrationState;
   }
@@ -152,31 +160,131 @@ class SettingService extends ServiceBase {
   /**
    * Save the current settings to storage.
    */
-  async saveSettingData() {
-    this.saveDeviceAndVaultName();
+  saveSettingData() {
+    return this.serialiseSave(async () => {
+      const prepared = await this.prepareSettingSave(this.cloneSettings(this.settings));
+      await this.writePreparedSettings(prepared);
+      this.commitPreparedSettings(prepared);
+    });
+  }
+  serialiseSave(operation) {
+    const result = this.saveQueue.then(operation);
+    this.saveQueue = result.catch(() => void 0);
+    return result;
+  }
+  /** Change the configuration wrapper without changing the protected plaintext values. */
+  changeConfigurationEncryption(store, passphrase) {
+    const result = this.serialiseSave(async () => {
+      if (store !== "" && store !== "LOCALSTORAGE" && store !== "ASK_AT_LAUNCH") {
+        throw new Error("The configuration passphrase storage mode is unsupported.");
+      }
+      const oldLocalKey = this.getDeviceLocalConfig("ls-setting-passphrase");
+      const settings = this.cloneSettings(this.settings);
+      let targetKey;
+      if (store === "LOCALSTORAGE") {
+        targetKey = passphrase ?? oldLocalKey ?? false;
+      } else if (store === "") {
+        targetKey = "*";
+      } else {
+        targetKey = await this.getSavingPassphrase({ ...settings, configPassphraseStore: store });
+      }
+      if (!targetKey) {
+        throw new Error("A configuration passphrase is required. Settings were not saved.");
+      }
+      await this.prepareConfigurationKeyChange(settings, targetKey);
+      settings.configPassphraseStore = store;
+      const prepared = await this.prepareSettingSave(settings, targetKey);
+      const changesLocalKey = store === "LOCALSTORAGE" && targetKey !== oldLocalKey;
+      try {
+        if (changesLocalKey) this.setDeviceLocalConfig("ls-setting-passphrase", targetKey);
+        await this.writePreparedSettings(prepared);
+      } catch (error) {
+        if (changesLocalKey) this.restoreConfigurationPassphrase(oldLocalKey, error);
+        throw error;
+      }
+      this.settings.configPassphraseStore = store;
+      this.commitPreparedSettings(prepared);
+    });
+    return result.catch((error) => {
+      this._log(this.context.translate("SettingService.ConfigurationEncryptionSaveFailed"), LOG_LEVEL_URGENT);
+      throw error;
+    });
+  }
+  restoreConfigurationPassphrase(previous, cause) {
+    try {
+      if (previous) this.setDeviceLocalConfig("ls-setting-passphrase", previous);
+      else this.deleteDeviceLocalConfig("ls-setting-passphrase");
+    } catch {
+      const message = this.context.translate("SettingService.ConfigurationPassphraseRollbackFailed");
+      this._log(message, LOG_LEVEL_URGENT);
+      throw new Error(message, { cause });
+    }
+  }
+  async prepareConfigurationKeyChange(settings, targetKey) {
+    for (const config of Object.values(settings.remoteConfigurations)) {
+      if (config.isEncrypted && this.isPlainConfigurationUri(config.uri)) config.isEncrypted = false;
+    }
+    const hasCiphertext = this.hasProtectedConfiguration(settings);
+    if (!hasCiphertext) return;
+    const oldKey = await this.getSavingPassphrase(settings);
+    const failure = () => new Error(this.context.translate("SettingService.ConfigurationCouldNotBeDecrypted"));
+    if (!oldKey) throw failure();
+    if (settings.encryptedCouchDBConnection) {
+      const connection = this.tryDecodeJson(
+        await this.decryptConfigurationItem(settings.encryptedCouchDBConnection, oldKey)
+      );
+      if (!restoreConnectionSettings(this.cloneSettings(settings), connection)) throw failure();
+      settings.encryptedCouchDBConnection = "";
+    }
+    if (settings.encryptedPassphrase) {
+      const plaintext = await this.decryptConfigurationItem(settings.encryptedPassphrase, oldKey);
+      if (plaintext === false) throw failure();
+      settings.encryptedPassphrase = requireConfigurationCiphertext(
+        await this.encryptPlainConfigurationItem(plaintext, settings, targetKey)
+      );
+    }
+    if (settings.idDerivationVersion === 1 && settings.encryptedIdDerivationKey) {
+      const idKey = await this.decryptConfigurationItem(settings.encryptedIdDerivationKey, oldKey);
+      if (idKey === false) throw failure();
+      configuredIdKey({ ...settings, idDerivationKey: idKey });
+    }
+    for (const config of Object.values(settings.remoteConfigurations)) {
+      if (!config.isEncrypted) continue;
+      const plaintext = await this.decryptConfigurationItem(config.uri, oldKey);
+      if (plaintext === false) {
+        try {
+          ConnectionStringParser.parse(config.uri);
+        } catch {
+          throw failure();
+        }
+      } else {
+        config.uri = plaintext;
+      }
+      config.isEncrypted = false;
+    }
+  }
+  async prepareSettingSave(settings, selectedPassphrase) {
     const previousSettings = this._lastPersistedSettings ?? this.cloneSettings(this.settings);
-    const settings = this.cloneSettings(this.settings);
     const hookResults = await this.onBeforeSaveSettingData(settings, previousSettings);
+    const savedPatch = {};
     for (const patch of hookResults) {
       if (patch instanceof Error || !patch) continue;
       Object.assign(settings, patch);
-      Object.assign(this.settings, patch);
+      Object.assign(savedPatch, patch);
     }
+    const runtime = this.cloneSettings(settings);
     const idKey = configuredIdKey(settings);
+    const configurationPassphrase = selectedPassphrase ?? await this.getSavingPassphrase(settings);
     if (settings.idDerivationVersion === 1) {
       if (idKey === false) {
         throw new Error("The configured ID derivation key is unavailable.");
       }
-      let passphrase = this.usedPassphrase;
-      if (passphrase === "") {
-        passphrase = await this.getPassphrase(settings);
-      }
-      if (passphrase === false || passphrase === "") {
+      if (!configurationPassphrase) {
         const message = "Failed to retrieve a passphrase for the ID derivation key. Settings were not saved.";
         this._log(message, LOG_LEVEL_URGENT);
         throw new Error(message);
       }
-      const encryptedIdKey = await encryptString(idKey, passphrase + SALT_OF_PASSPHRASE);
+      const encryptedIdKey = await encryptString(idKey, configurationPassphrase + SALT_OF_PASSPHRASE);
       if (encryptedIdKey === "") {
         const message = "Failed to encrypt the ID derivation key. Settings were not saved.";
         this._log(message, LOG_LEVEL_URGENT);
@@ -184,18 +292,14 @@ class SettingService extends ServiceBase {
       }
       settings.encryptedIdDerivationKey = encryptedIdKey;
       settings.idDerivationKey = "";
-      this.usedPassphrase = passphrase;
     } else {
       settings.encryptedIdDerivationKey = "";
     }
     settings.deviceAndVaultName = "";
     if (settings.P2P_DevicePeerName && settings.P2P_DevicePeerName.trim() !== "") {
-      this._log("Saving device peer name to small config");
-      this.setSmallConfig(SETTING_KEY_P2P_DEVICE_NAME, settings.P2P_DevicePeerName.trim());
       settings.P2P_DevicePeerName = "";
     }
     omitUnpersistedSettings(settings);
-    const configurationPassphrase = this.usedPassphrase || await this.getPassphrase(settings);
     if (!configurationPassphrase) {
       if (Object.values(settings.remoteConfigurations).some((config) => this.hasManagedP2PProfileURI(config.uri))) {
         const message = "Failed to retrieve a passphrase for managed P2P source data. Settings were not saved.";
@@ -213,7 +317,11 @@ class SettingService extends ServiceBase {
     } else {
       if (hasConnectionSettings(settings)) {
         settings.encryptedCouchDBConnection = requireConfigurationCiphertext(
-          await this.encryptConfigurationItem(JSON.stringify(selectConnectionSettings(settings)), settings)
+          await this.encryptConfigurationItem(
+            JSON.stringify(selectConnectionSettings(settings)),
+            settings,
+            configurationPassphrase
+          )
         );
         clearConnectionSettings(settings);
       } else if (settings.encryptedCouchDBConnection) {
@@ -226,18 +334,32 @@ class SettingService extends ServiceBase {
       }
       if (settings.encrypt && settings.passphrase != "") {
         settings.encryptedPassphrase = requireConfigurationCiphertext(
-          await this.encryptPlainConfigurationItem(settings.passphrase, settings)
+          await this.encryptPlainConfigurationItem(settings.passphrase, settings, configurationPassphrase)
         );
         settings.passphrase = "";
       }
-      await this.encryptRemoteConfigurationUris(settings);
+      await this.encryptRemoteConfigurationUris(settings, configurationPassphrase);
     }
     const persisted = prepareSettingsForPersistence(settings);
-    await this.saveData(persisted);
-    this._lastPersistedSettings = this.cloneSettings(this.settings);
-    void this.onSettingSaved(settings);
+    return { persisted, runtime, patch: savedPatch, passphrase: configurationPassphrase };
   }
-  async encryptRemoteConfigurationUris(settings) {
+  async writePreparedSettings(prepared) {
+    this.saveDeviceAndVaultName();
+    if (prepared.runtime.P2P_DevicePeerName?.trim()) {
+      this.setSmallConfig(SETTING_KEY_P2P_DEVICE_NAME, prepared.runtime.P2P_DevicePeerName.trim());
+    }
+    await this.saveData(prepared.persisted);
+  }
+  commitPreparedSettings(prepared) {
+    Object.assign(this.settings, prepared.patch);
+    this.settings.encryptedCouchDBConnection = prepared.persisted.encryptedCouchDBConnection;
+    this.settings.encryptedPassphrase = prepared.persisted.encryptedPassphrase;
+    this.settings.encryptedIdDerivationKey = prepared.persisted.encryptedIdDerivationKey;
+    this._lastPersistedSettings = prepared.runtime;
+    if (prepared.passphrase) this.rememberPassphrase(prepared.runtime, prepared.passphrase);
+    void this.onSettingSaved(prepared.persisted);
+  }
+  async encryptRemoteConfigurationUris(settings, passphrase) {
     const configs = settings.remoteConfigurations || {};
     for (const [id, config] of Object.entries(configs)) {
       if (config.isEncrypted || config.uri.trim() === "") {
@@ -246,7 +368,7 @@ class SettingService extends ServiceBase {
       const managedP2PProfile = this.hasManagedP2PProfileURI(config.uri);
       let encryptedURI;
       try {
-        encryptedURI = await this.encryptConfigurationItem(config.uri, settings);
+        encryptedURI = await this.encryptConfigurationItem(config.uri, settings, passphrase);
       } catch (error) {
         if (managedP2PProfile) {
           const message = `Failed to encrypt managed P2P remote configuration '${id}'. Settings were not saved.`;
@@ -288,6 +410,7 @@ class SettingService extends ServiceBase {
     return (new URLSearchParams(query).get("managedType") ?? "").trim().length > 0;
   }
   async decryptRemoteConfigurationUris(settings, passphrase) {
+    let verified = false;
     const configs = settings.remoteConfigurations || {};
     for (const [id, config] of Object.entries(configs)) {
       if (!config.isEncrypted) {
@@ -319,7 +442,9 @@ class SettingService extends ServiceBase {
         uri: decryptedURI,
         isEncrypted: false
       };
+      verified = true;
     }
+    return verified;
   }
   /**
    * Event triggered before realising the settings.
@@ -404,24 +529,37 @@ class SettingService extends ServiceBase {
     const methods = {
       "": () => Promise.resolve("*"),
       LOCALSTORAGE: () => Promise.resolve(this.getDeviceLocalConfig("ls-setting-passphrase") ?? false),
-      ASK_AT_LAUNCH: () => this.APIService.confirm.askString("Passphrase", "passphrase", "")
+      ASK_AT_LAUNCH: () => this.APIService.confirm.askString(
+        this.context.translate("SettingService.ConfigurationPassphraseTitle"),
+        "passphrase",
+        "",
+        true
+      )
     };
     const method = settings.configPassphraseStore;
     const methodFunc = method in methods ? methods[method] : methods[""];
     return methodFunc();
   }
-  usedPassphrase = "";
+  usedPassphrase;
+  getSavingPassphrase(settings) {
+    if (settings.configPassphraseStore === "ASK_AT_LAUNCH" && this.usedPassphrase?.store === "ASK_AT_LAUNCH") {
+      return Promise.resolve(this.usedPassphrase.value);
+    }
+    return this.getPassphrase(settings);
+  }
+  rememberPassphrase(settings, passphrase) {
+    this.usedPassphrase = { store: settings.configPassphraseStore, value: passphrase };
+  }
   /**
    * Clear any used passphrase from memory.
    */
   clearUsedPassphrase() {
-    this.usedPassphrase = "";
+    this.usedPassphrase = void 0;
   }
   async decryptConfigurationItem(encrypted, passphrase) {
     try {
       const dec = await decryptString(encrypted, passphrase + SALT_OF_PASSPHRASE);
       if (dec) {
-        this.usedPassphrase = passphrase;
         return dec;
       }
     } catch (ex) {
@@ -430,18 +568,15 @@ class SettingService extends ServiceBase {
     }
     return false;
   }
-  async encryptConfigurationItem(src, settings) {
-    return this.encryptConfigurationItemWith(src, settings, encryptString);
+  async encryptConfigurationItem(src, settings, passphrase) {
+    return this.encryptConfigurationItemWith(src, settings, encryptString, passphrase);
   }
-  async encryptPlainConfigurationItem(src, settings) {
-    return this.encryptConfigurationItemWith(src, settings, encryptWithEphemeralSalt);
+  async encryptPlainConfigurationItem(src, settings, passphrase) {
+    return this.encryptConfigurationItemWith(src, settings, encryptWithEphemeralSalt, passphrase);
   }
-  async encryptConfigurationItemWith(src, settings, encrypt) {
-    if (this.usedPassphrase != "") {
-      return await encrypt(src, this.usedPassphrase + SALT_OF_PASSPHRASE);
-    }
-    const passphrase = await this.getPassphrase(settings);
-    if (passphrase === false) {
+  async encryptConfigurationItemWith(src, settings, encrypt, selectedPassphrase) {
+    const passphrase = selectedPassphrase ?? await this.getSavingPassphrase(settings);
+    if (!passphrase) {
       this._log(
         "Failed to obtain passphrase when saving data.json! Please verify the configuration.",
         LOG_LEVEL_URGENT
@@ -450,7 +585,7 @@ class SettingService extends ServiceBase {
     }
     const dec = await encrypt(src, passphrase + SALT_OF_PASSPHRASE);
     if (dec) {
-      this.usedPassphrase = passphrase;
+      if (selectedPassphrase === void 0) this.rememberPassphrase(settings, passphrase);
       return dec;
     }
     return "";
@@ -460,19 +595,24 @@ class SettingService extends ServiceBase {
    * @param settings The settings to decrypt.
    */
   async decryptSettings(settings) {
-    if (settings.idDerivationVersion !== 1) {
-      configuredIdKey(settings);
-    } else if (!settings.encryptedIdDerivationKey) {
-      throw new Error("The configured ID derivation key is missing or unavailable.");
-    }
+    this.validateStoredIdConfiguration(settings);
     const passphrase = await this.getPassphrase(settings);
+    const result = await this.decryptSettingsWithPassphrase(settings, passphrase);
+    if (result.verified && passphrase) this.rememberPassphrase(settings, passphrase);
+    return result.settings;
+  }
+  async decryptSettingsWithPassphrase(settings, passphrase) {
+    let verified = false;
+    this.validateStoredIdConfiguration(settings);
     if (settings.idDerivationVersion === 1) {
       if (passphrase === false || passphrase === "") {
-        throw new Error("The configured ID derivation key cannot be decrypted without a passphrase.");
+        throw new ConfigurationPassphraseError(
+          "The configured ID derivation key cannot be decrypted without a passphrase."
+        );
       }
       const decryptedIdKey = await this.decryptConfigurationItem(settings.encryptedIdDerivationKey, passphrase);
       if (decryptedIdKey === false) {
-        throw new Error("The configured ID derivation key could not be decrypted.");
+        throw new ConfigurationPassphraseError("The configured ID derivation key could not be decrypted.");
       }
       try {
         configuredIdKey({ ...settings, idDerivationKey: decryptedIdKey });
@@ -480,6 +620,7 @@ class SettingService extends ServiceBase {
         throw new Error("The configured ID derivation key is invalid.");
       }
       settings.idDerivationKey = decryptedIdKey;
+      verified = true;
     }
     if (passphrase === false) {
       this._log("No passphrase found for data.json! Verify configuration before syncing.", LOG_LEVEL_URGENT);
@@ -503,6 +644,8 @@ class SettingService extends ServiceBase {
             LOG_LEVEL_URGENT
           );
           clearConnectionSettings(settings);
+        } else {
+          verified = true;
         }
       }
       if (settings.encrypt && settings.encryptedPassphrase) {
@@ -510,6 +653,7 @@ class SettingService extends ServiceBase {
         const decrypted = await this.decryptConfigurationItem(encrypted, passphrase);
         if (decrypted) {
           settings.passphrase = decrypted;
+          verified = true;
         } else {
           this._log(
             "Failed to decrypt passphrase from data.json! Ensure configuration is correct before syncing with remote.",
@@ -518,9 +662,80 @@ class SettingService extends ServiceBase {
           settings.passphrase = "";
         }
       }
-      await this.decryptRemoteConfigurationUris(settings, passphrase);
+      verified = await this.decryptRemoteConfigurationUris(settings, passphrase) || verified;
+    }
+    return { settings, verified };
+  }
+  hasProtectedConfiguration(settings) {
+    return !!(settings.encryptedCouchDBConnection || settings.encrypt && settings.encryptedPassphrase || settings.encryptedIdDerivationKey || Object.values(settings.remoteConfigurations || {}).some(
+      (config) => config.isEncrypted && !this.isPlainConfigurationUri(config.uri)
+    ));
+  }
+  validateStoredIdConfiguration(settings) {
+    if (settings.idDerivationVersion !== 1) {
+      configuredIdKey(settings);
+    } else if (!settings.encryptedIdDerivationKey) {
+      throw new Error("The configured ID derivation key is missing or unavailable.");
+    }
+  }
+  isPlainConfigurationUri(uri) {
+    try {
+      ConnectionStringParser.parse(uri);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async loadConfiguration(settings) {
+    if (settings.configPassphraseStore !== "LOCALSTORAGE" || !this.hasProtectedConfiguration(settings)) {
+      return this.decryptSettings(settings);
+    }
+    if (settings.idDerivationVersion === 1) {
+      const ciphertext = settings.encryptedIdDerivationKey;
+      if (![HKDF_SALTED_ENCRYPTED_PREFIX, ENCRYPT_V1_PREFIX_PROBABLY, ENCRYPT_V2_PREFIX, ENCRYPT_V3_PREFIX].some(
+        (prefix) => ciphertext?.startsWith(prefix)
+      )) {
+        throw new Error("The configured ID derivation key is missing or unavailable.");
+      }
+    } else {
+      configuredIdKey(settings);
+    }
+    const previous = this.getDeviceLocalConfig("ls-setting-passphrase");
+    let candidate = previous || false;
+    let retry = false;
+    while (true) {
+      if (candidate) {
+        try {
+          const result = await this.decryptSettingsWithPassphrase(this.cloneSettings(settings), candidate);
+          if (result.verified) {
+            if (candidate !== previous) {
+              try {
+                this.setDeviceLocalConfig("ls-setting-passphrase", candidate);
+              } catch (error) {
+                this.restoreConfigurationPassphrase(previous, error);
+                throw error;
+              }
+            }
+            this.rememberPassphrase(settings, candidate);
+            return result.settings;
+          }
+        } catch (error) {
+          if (!(error instanceof ConfigurationPassphraseError)) throw error;
+        }
+        retry = true;
+      }
+      candidate = await this.APIService.confirm.askString(
+        this.context.translate(
+          retry ? "SettingService.ConfigurationPassphraseRetryTitle" : "SettingService.ConfigurationPassphraseTitle"
+        ),
+        "passphrase",
+        "",
+        true
+      );
+      if (!candidate) {
+        throw new Error(this.context.translate("SettingService.ConfigurationPassphraseCancelled"));
+      }
     }
-    return settings;
   }
   async loadSettings() {
     const prepared = prepareSettingsForLoad(await this.loadData());
@@ -536,7 +751,7 @@ class SettingService extends ServiceBase {
         settings.isConfigured = false;
       }
     }
-    this.settings = await this.decryptSettings(settings);
+    this.settings = await this.loadConfiguration(settings);
     this.onDisplayLanguageChanged?.(this.settings.displayLanguage);
     await this.adjustSettings(this.settings);
     const migratedLegacyRemoteConfigurations = !hadRemoteConfigurations && Object.keys(this.settings.remoteConfigurations ?? {}).length > 0;

package/docs/proven-in-use.md

@@ -8,6 +8,8 @@ The code paths below identify the maintained Self-hosted LiveSync composition po
 
 ## Obsidian plug-in
 
+Unreleased configuration-encryption tests cover changing the wrapper key without changing connection, E2EE, profile, or independent ID values. They also cover custom-key input before loading, failed writes, concurrent saves, cancellation, and unreadable-payload retention. Commonlib owns these service results. LiveSync owns the Apply controls, setting-tab registration, and database startup order; actual Apply and restart behaviour requires its focused real-Obsidian scenario.
+
 The CouchDB connection fix bypasses browser HTTP caching so encrypted replication can continue after a remote Rebuild preserves document IDs and revisions. Commonlib's regression tests cover Metadata and Chunks encrypted with a replacement Security Seed while an earlier response remains cached. Self-hosted LiveSync's `couchdb-http-cache` scenario additionally populates the real browser HTTP cache before rebuilding, confirms that the Seed and ciphertext change while the revision remains unchanged, and requires subsequent replication to succeed without clearing that cache. The released LiveSync 1.0.34 fails this scenario; a local checked Commonlib artefact passes in the maintained LiveSync 1.0.34 composition on Linux Obsidian 1.12.7. This establishes the tested build's behaviour, with the reporter's Windows and Obsidian 1.13.7 environment still unverified.
 
 Unreleased settings tests verify that Object Storage-only credentials, JWT values, and authentication headers reach the host persistence handler only after connection encryption, and that unavailable or failed required encryption preserves the previous persisted settings. The focused `/settings` entry also supplies conditional whole-profile Markdown preparation and import preservation. A clean packed consumer checks the exhaustive property policy and prepared output types with an ES2018 compile fixture. Commonlib owns these result and type contracts; Self-hosted LiveSync owns Markdown file writes, its settings interface, and restoration through a real Obsidian restart.

package/docs/settings-lifecycle.md

@@ -74,6 +74,10 @@ The standard Commonlib `SettingService` performs this preparation automatically.
 
 ## Preparing settings for persistence and Markdown
 
+The existing `SettingService` provides `changeConfigurationEncryption(store, passphrase?)` for hosts which edit the configuration encryption mode or device-local custom key. Await it before marking those edits as saved. It prepares one wrapper key for connection credentials, the E2EE passphrase, remote profile URIs, and the independent ID key, and serialises the change with ordinary settings saves. It rejects empty keys and unreadable existing protected items. A failed write attempts to restore the previous device key and does not send a success event. The device key and settings document use separate host writes, so this is not a guarantee of rollback after process termination or an uncertain persistence error.
+
+When `loadSettings()` cannot validate a custom configuration key, it requests a masked key through the host's existing `confirm.askString` capability. It validates each candidate on a fresh copy and stores only a validated key before continuing initialisation. Cancellation or unavailable input stops that load without changing the saved settings. The ID-key rejection contract remains in `decryptSettings()`; loading never replaces a missing or invalid ID key with another key. ASK mode retains one successful in-memory key for ordinary saves in that launch. Hosts own the visible prompt, cancellation on disposal, and the policy which prevents database and replication work before loading completes.
+
 `SettingService` prepares a separate settings object before calling the host's persistence handler. Object Storage credentials, CouchDB credentials, JWT values, and authentication headers share the existing `encryptedCouchDBConnection` payload. Encryption runs when any protected connection property is present, including when every CouchDB property is empty. The same policy supplies the properties encrypted, cleared before saving, and restored on loading. Older plaintext settings and encrypted payloads without newer properties remain readable.
 
 An unavailable configuration passphrase or an empty connection-encryption result stops the save before the host's persistence handler receives the object. Remote profile URI encryption also stops on failure when a configuration passphrase is explicitly selected. The previous persisted settings remain intact. Removing all connection values clears an older encrypted payload only after it can be decrypted, preserving recovery after a failed decryption. Profile names, IDs, and selections remain ordinary settings; profile URIs are encrypted separately.
@@ -116,3 +120,5 @@ The settings schema version is independent of the package version and of any rem
 The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, legacy file-name case normalisation, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. Credential tests cover Object Storage-only persistence, JWT and header restoration, legacy settings, removed credentials, encryption failures, conditional whole-profile Markdown export, and preservation of local values on import. Tweak-assessment tests cover effective defaults, unadvertised values, directional change sets, reconstruction impact, raw representation differences, immutable snapshots, and document-ID case behaviour. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports. Its ES2018 compile fixture checks missing policies and attempts to bypass prepared output types.
 
 Hosts remain responsible for testing when setup is classified as new, how local review acknowledgement is stored, how replication is gated, and how their settings interface presents the result.
+
+`SettingService.configurationEncryption.unit.spec.ts` covers key changes with ID versions 0 and 1, stale-cache avoidance, per-launch ASK reuse, concurrent saves, preparation and persistence errors, rollback reporting, custom-key input and cancellation, and retention of unreadable items. These are Commonlib-owned service contracts; Apply controls and real application restarts require downstream verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -1010,7 +1010,7 @@
     "idb": "^8.0.3",
     "markdown-it": "^14.2.0",
     "minimatch": "^10.2.5",
-    "octagonal-wheels": "^0.1.53",
+    "octagonal-wheels": "^0.1.55",
     "pouchdb-adapter-http": "^9.0.0",
     "pouchdb-adapter-idb": "^9.0.0",
     "pouchdb-adapter-indexeddb": "^9.0.0",