@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/managers/HashManager/HashManager.d.ts

@@ -0,0 +1,60 @@
+import type { HashAlgorithm } from "../../common/models/setting.type.js";
+import { HashManagerCore, type HashManagerCoreOptions } from "./HashManagerCore.js";
+/**
+ * Class for managing hash managers and performing hash calculations.
+ * Selects an appropriate manager according to the available hash algorithm.
+ */
+export declare class HashManager extends HashManagerCore {
+    /**
+     * Instance of the hash manager currently in use.
+     */
+    manager: HashManagerCore;
+    /**
+     * Checks whether the specified hash algorithm is available.
+     *
+     * @param hashAlg The hash algorithm to check
+     * @returns True if available
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+    /**
+     * Selects and initialises an available hash manager.
+     *
+     * @returns True if initialisation is successful
+     * @throws Throws an error if no available manager exists
+     */
+    setManager(): Promise<boolean>;
+    /**
+     * Constructs a new HashManager.
+     *
+     * @param options Initialisation options
+     */
+    constructor(options: HashManagerCoreOptions);
+    /**
+     * Initialises the hash manager.
+     *
+     * @returns True if initialisation is successful
+     * @throws Throws an error if initialisation fails
+     */
+    processInitialise(): Promise<boolean>;
+    /**
+     * Computes the hash value for the specified string.
+     *
+     * @param piece The string to be hashed
+     * @returns The hash value (returned as a Promise)
+     */
+    computeHash(piece: string): Promise<string>;
+    /**
+     * Computes the hash value without encryption.
+     *
+     * @param piece The string to be hashed
+     * @returns The hash value (returned as a Promise)
+     */
+    computeHashWithoutEncryption(piece: string): Promise<string>;
+    /**
+     * Computes the hash value with encryption.
+     *
+     * @param piece The string to be hashed
+     * @returns The hash value (returned as a Promise)
+     */
+    computeHashWithEncryption(piece: string): Promise<string>;
+}

package/dist/managers/HashManager/HashManager.js

@@ -0,0 +1,97 @@
+import { FallbackWasmHashManager, XXHash32RawHashManager, XXHash64HashManager } from "./XXHashHashManager.js";
+import { FallbackPureJSHashManager, PureJSHashManager, SHA1HashManager } from "./PureJSHashManager.js";
+import { HashManagerCore } from "./HashManagerCore.js";
+import { LOG_LEVEL_VERBOSE, Logger } from "../../common/logger.js";
+const HashManagers = [
+  XXHash64HashManager,
+  XXHash32RawHashManager,
+  SHA1HashManager,
+  PureJSHashManager,
+  // Please retain these fallback managers, as they are essential for compatibility.
+  FallbackWasmHashManager,
+  FallbackPureJSHashManager
+];
+class HashManager extends HashManagerCore {
+  /**
+   * Instance of the hash manager currently in use.
+   */
+  manager = void 0;
+  /**
+   * Checks whether the specified hash algorithm is available.
+   *
+   * @param hashAlg The hash algorithm to check
+   * @returns True if available
+   */
+  static isAvailableFor(hashAlg) {
+    return HashManagers.some((manager) => manager.isAvailableFor(hashAlg));
+  }
+  /**
+   * Selects and initialises an available hash manager.
+   *
+   * @returns True if initialisation is successful
+   * @throws Throws an error if no available manager exists
+   */
+  async setManager() {
+    const settings = this.options.settingService.currentSettings();
+    for (const Manager of HashManagers) {
+      if (Manager.isAvailableFor(settings.hashAlg)) {
+        this.manager = new Manager(this.options);
+        return await this.manager.initialise();
+      }
+    }
+    throw new Error(`HashManager for ${settings.hashAlg} is not available`);
+  }
+  /**
+   * Constructs a new HashManager.
+   *
+   * @param options Initialisation options
+   */
+  constructor(options) {
+    super(options);
+  }
+  /**
+   * Initialises the hash manager.
+   *
+   * @returns True if initialisation is successful
+   * @throws Throws an error if initialisation fails
+   */
+  async processInitialise() {
+    const settings = this.options.settingService.currentSettings();
+    if (await this.setManager()) {
+      Logger(`HashManager for ${settings.hashAlg} has been initialised`, LOG_LEVEL_VERBOSE);
+      return true;
+    }
+    Logger(`HashManager for ${settings.hashAlg} failed to initialise`);
+    throw new Error(`HashManager for ${settings.hashAlg} failed to initialise`);
+  }
+  /**
+   * Computes the hash value for the specified string.
+   *
+   * @param piece The string to be hashed
+   * @returns The hash value (returned as a Promise)
+   */
+  async computeHash(piece) {
+    return await this.manager.computeHash(piece);
+  }
+  /**
+   * Computes the hash value without encryption.
+   *
+   * @param piece The string to be hashed
+   * @returns The hash value (returned as a Promise)
+   */
+  computeHashWithoutEncryption(piece) {
+    return this.manager.computeHashWithoutEncryption(piece);
+  }
+  /**
+   * Computes the hash value with encryption.
+   *
+   * @param piece The string to be hashed
+   * @returns The hash value (returned as a Promise)
+   */
+  computeHashWithEncryption(piece) {
+    return this.manager.computeHashWithEncryption(piece);
+  }
+}
+export {
+  HashManager
+};

package/dist/managers/HashManager/HashManagerCore.d.ts

@@ -0,0 +1,114 @@
+import type { ISettingService } from "../../services/base/IService.js";
+import type { HashAlgorithm } from "../../common/models/setting.type.js";
+/**
+ * Prefix for encrypted hashes.
+ *
+ * This constant is prepended to hash strings when encryption is enabled.
+ */
+export declare const HashEncryptedPrefix = "+";
+/**
+ * Options for initialising {@link HashManagerCore}.
+ */
+export type HashManagerCoreOptions = {
+    /**
+     * Remote database settings used for hash management.
+     */
+    settingService: ISettingService;
+};
+/**
+ * Abstract base class for hash management.
+ *
+ * Provides core logic for handling passphrase hashing, encryption toggling,
+ * and initialisation routines. Subclasses should implement encryption-specific
+ * hash computation methods.
+ */
+export declare abstract class HashManagerCore {
+    protected settingService: ISettingService;
+    /**
+     * Indicates whether encryption is enabled for hash computation.
+     */
+    useEncryption: boolean;
+    /**
+     * Hashed passphrase as a string, used for hash operations.
+     */
+    hashedPassphrase: string;
+    /**
+     * Hashed passphrase as a 32-bit number, used for hash operations.
+     */
+    hashedPassphrase32: number;
+    /**
+     * Options used for initialisation and configuration.
+     */
+    options: HashManagerCoreOptions;
+    /**
+     * Constructs a new {@link HashManagerCore} instance.
+     *
+     * @param options - Configuration options for hash management.
+     */
+    constructor(options: HashManagerCoreOptions);
+    /**
+     * Applies the given options to the hash manager.
+     *
+     * Updates encryption settings and computes passphrase hashes.
+     *
+     * @param options - Optional configuration to apply.
+     */
+    applyOptions(options?: HashManagerCoreOptions): void;
+    /**
+     * Performs initialisation logic specific to the hash manager implementation.
+     *
+     * Subclasses must implement this method.
+     *
+     * @returns Promise resolving to true if initialisation succeeds.
+     */
+    abstract processInitialise(): Promise<boolean>;
+    /**
+     * Task representing the initialisation process.
+     */
+    initialiseTask?: Promise<boolean>;
+    /**
+     * Ensures the hash manager is initialised.
+     *
+     * Returns a promise that resolves when initialisation is complete.
+     *
+     * @returns Promise resolving to true if initialisation succeeds.
+     */
+    initialise(): Promise<boolean>;
+    /**
+     * Computes a hash for the given string.
+     *
+     * If encryption is enabled, the hash is computed with encryption and prefixed.
+     * Otherwise, a plain hash is computed.
+     *
+     * @param piece - The input string to hash.
+     * @returns Promise resolving to the computed hash string.
+     */
+    computeHash(piece: string): Promise<string>;
+    /**
+     * Computes a hash for the given string without encryption.
+     *
+     * Subclasses must implement this method.
+     *
+     * @param piece - The input string to hash.
+     * @returns Promise resolving to the computed hash string.
+     */
+    abstract computeHashWithoutEncryption(piece: string): Promise<string>;
+    /**
+     * Computes a hash for the given string with encryption.
+     *
+     * Subclasses must implement this method.
+     *
+     * @param piece - The input string to hash.
+     * @returns Promise resolving to the computed encrypted hash string.
+     */
+    abstract computeHashWithEncryption(piece: string): Promise<string>;
+    /**
+     * Determines whether the hash manager is available for the specified algorithm.
+     *
+     * Subclasses should override this method to indicate supported algorithms.
+     *
+     * @param hashAlg - The hash algorithm to check.
+     * @returns True if available, false otherwise.
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+}

package/dist/managers/HashManager/HashManagerCore.js

@@ -0,0 +1,99 @@
+import { fallbackMixedHashEach, mixedHash } from "octagonal-wheels/hash/purejs";
+import { SALT_OF_ID, SEED_MURMURHASH } from "../../common/models/shared.const.behabiour.js";
+const HashEncryptedPrefix = "+";
+class HashManagerCore {
+  settingService;
+  /**
+   * Indicates whether encryption is enabled for hash computation.
+   */
+  useEncryption = false;
+  /**
+   * Hashed passphrase as a string, used for hash operations.
+   */
+  hashedPassphrase = "";
+  /**
+   * Hashed passphrase as a 32-bit number, used for hash operations.
+   */
+  hashedPassphrase32 = 0;
+  /**
+   * Options used for initialisation and configuration.
+   */
+  options;
+  /**
+   * Constructs a new {@link HashManagerCore} instance.
+   *
+   * @param options - Configuration options for hash management.
+   */
+  constructor(options) {
+    this.options = options;
+    this.settingService = options.settingService;
+    this.applyOptions(options);
+  }
+  /**
+   * Applies the given options to the hash manager.
+   *
+   * Updates encryption settings and computes passphrase hashes.
+   *
+   * @param options - Optional configuration to apply.
+   */
+  applyOptions(options) {
+    if (options) {
+      this.options = options;
+    }
+    const settings = this.options.settingService.currentSettings();
+    this.useEncryption = settings.encrypt ?? false;
+    const passphrase = settings.passphrase || "";
+    const usingLetters = ~~(passphrase.length / 4 * 3);
+    const passphraseForHash = SALT_OF_ID + passphrase.substring(0, usingLetters);
+    this.hashedPassphrase = fallbackMixedHashEach(passphraseForHash);
+    this.hashedPassphrase32 = mixedHash(passphraseForHash, SEED_MURMURHASH)[0];
+  }
+  /**
+   * Task representing the initialisation process.
+   */
+  initialiseTask;
+  /**
+   * Ensures the hash manager is initialised.
+   *
+   * Returns a promise that resolves when initialisation is complete.
+   *
+   * @returns Promise resolving to true if initialisation succeeds.
+   */
+  initialise() {
+    if (this.initialiseTask) {
+      return this.initialiseTask;
+    }
+    this.initialiseTask = this.processInitialise();
+    return this.initialiseTask;
+  }
+  /**
+   * Computes a hash for the given string.
+   *
+   * If encryption is enabled, the hash is computed with encryption and prefixed.
+   * Otherwise, a plain hash is computed.
+   *
+   * @param piece - The input string to hash.
+   * @returns Promise resolving to the computed hash string.
+   */
+  async computeHash(piece) {
+    if (this.useEncryption) {
+      return HashEncryptedPrefix + await this.computeHashWithEncryption(piece);
+    }
+    return await this.computeHashWithoutEncryption(piece);
+  }
+  /**
+   * Determines whether the hash manager is available for the specified algorithm.
+   *
+   * Subclasses should override this method to indicate supported algorithms.
+   *
+   * @param hashAlg - The hash algorithm to check.
+   * @returns True if available, false otherwise.
+   */
+  static isAvailableFor(hashAlg) {
+    return false;
+  }
+}
+export {
+  HashEncryptedPrefix,
+  HashManagerCore
+};

package/dist/managers/HashManager/PureJSHashManager.d.ts

@@ -0,0 +1,77 @@
+import { HashManagerCore } from "./HashManagerCore.js";
+import type { HashAlgorithm } from "../../common/models/setting.type.js";
+/**
+ * Provides hash management using the "mixed-purejs" algorithm.
+ *
+ * This manager utilises a pure JavaScript implementation for hashing.
+ * It is available only when the hash algorithm is set to "mixed-purejs".
+ */
+export declare class PureJSHashManager extends HashManagerCore {
+    /**
+     * Determines whether this manager is available for the specified algorithm.
+     * @param hashAlg The hash algorithm to check.
+     * @returns True if the algorithm is "mixed-purejs".
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+    /**
+     * Initialises the hash manager.
+     * @returns Always resolves to true.
+     */
+    processInitialise(): Promise<boolean>;
+    /**
+     * Computes a hash for the given input, including encryption.
+     * @param input The input string to hash.
+     * @returns The computed hash as a promise.
+     */
+    computeHashWithEncryption(input: string): Promise<string>;
+    /**
+     * Computes a hash for the given input, without encryption.
+     * @param input The input string to hash.
+     * @returns The computed hash as a promise.
+     */
+    computeHashWithoutEncryption(input: string): Promise<string>;
+}
+/**
+ * Provides hash management using the "sha1" algorithm.
+ *
+ * This manager utilises a pure JavaScript SHA-1 implementation.
+ * It is available only when the hash algorithm is set to "sha1".
+ */
+export declare class SHA1HashManager extends HashManagerCore {
+    /**
+     * Determines whether this manager is available for the specified algorithm.
+     * @param hashAlg The hash algorithm to check.
+     * @returns True if the algorithm is "sha1".
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+    /**
+     * Initialises the hash manager.
+     * @returns Always resolves to true.
+     */
+    processInitialise(): Promise<boolean>;
+    /**
+     * Computes a SHA-1 hash for the given input, including encryption.
+     * @param input The input string to hash.
+     * @returns The computed SHA-1 hash as a promise.
+     */
+    computeHashWithEncryption(input: string): Promise<string>;
+    /**
+     * Computes a SHA-1 hash for the given input, without encryption.
+     * @param input The input string to hash.
+     * @returns The computed SHA-1 hash as a promise.
+     */
+    computeHashWithoutEncryption(input: string): Promise<string>;
+}
+/**
+ * Fallback hash manager using the pure JavaScript implementation.
+ *
+ * This manager is always available and acts as a fallback when no specific algorithm matches.
+ */
+export declare class FallbackPureJSHashManager extends PureJSHashManager {
+    /**
+     * Always returns true, indicating this manager is available for any algorithm.
+     * @param _hashAlg The hash algorithm (ignored).
+     * @returns True.
+     */
+    static isAvailableFor(_hashAlg: HashAlgorithm): boolean;
+}

package/dist/managers/HashManager/PureJSHashManager.js

@@ -0,0 +1,84 @@
+import { HashManagerCore } from "./HashManagerCore.js";
+import { fallbackMixedHashEach, sha1 } from "octagonal-wheels/hash/purejs";
+import { HashAlgorithms } from "../../common/models/setting.const.js";
+class PureJSHashManager extends HashManagerCore {
+  /**
+   * Determines whether this manager is available for the specified algorithm.
+   * @param hashAlg The hash algorithm to check.
+   * @returns True if the algorithm is "mixed-purejs".
+   */
+  static isAvailableFor(hashAlg) {
+    return hashAlg === HashAlgorithms.MIXED_PUREJS;
+  }
+  /**
+   * Initialises the hash manager.
+   * @returns Always resolves to true.
+   */
+  processInitialise() {
+    return Promise.resolve(true);
+  }
+  /**
+   * Computes a hash for the given input, including encryption.
+   * @param input The input string to hash.
+   * @returns The computed hash as a promise.
+   */
+  computeHashWithEncryption(input) {
+    return Promise.resolve(fallbackMixedHashEach(`${input}${this.hashedPassphrase}${input.length}`));
+  }
+  /**
+   * Computes a hash for the given input, without encryption.
+   * @param input The input string to hash.
+   * @returns The computed hash as a promise.
+   */
+  computeHashWithoutEncryption(input) {
+    return Promise.resolve(fallbackMixedHashEach(`${input}-${input.length}`));
+  }
+}
+class SHA1HashManager extends HashManagerCore {
+  /**
+   * Determines whether this manager is available for the specified algorithm.
+   * @param hashAlg The hash algorithm to check.
+   * @returns True if the algorithm is "sha1".
+   */
+  static isAvailableFor(hashAlg) {
+    return hashAlg === HashAlgorithms.SHA1;
+  }
+  /**
+   * Initialises the hash manager.
+   * @returns Always resolves to true.
+   */
+  processInitialise() {
+    return Promise.resolve(true);
+  }
+  /**
+   * Computes a SHA-1 hash for the given input, including encryption.
+   * @param input The input string to hash.
+   * @returns The computed SHA-1 hash as a promise.
+   */
+  computeHashWithEncryption(input) {
+    return sha1(`${input}-${this.hashedPassphrase}-${input.length}`);
+  }
+  /**
+   * Computes a SHA-1 hash for the given input, without encryption.
+   * @param input The input string to hash.
+   * @returns The computed SHA-1 hash as a promise.
+   */
+  computeHashWithoutEncryption(input) {
+    return sha1(`${input}-${input.length}`);
+  }
+}
+class FallbackPureJSHashManager extends PureJSHashManager {
+  /**
+   * Always returns true, indicating this manager is available for any algorithm.
+   * @param _hashAlg The hash algorithm (ignored).
+   * @returns True.
+   */
+  static isAvailableFor(_hashAlg) {
+    return true;
+  }
+}
+export {
+  FallbackPureJSHashManager,
+  PureJSHashManager,
+  SHA1HashManager
+};

package/dist/managers/HashManager/XXHashHashManager.d.ts

@@ -0,0 +1,96 @@
+import { HashManagerCore, type HashManagerCoreOptions } from "./HashManagerCore.js";
+import type { XXHashAPI } from "xxhash-wasm-102";
+import type { HashAlgorithm } from "../../common/models/setting.type.js";
+/**
+ * Abstract base class for hash managers using XXHash algorithms.
+ * Provides initialisation and common properties for XXHash-based managers.
+ */
+export declare abstract class XXHashHashManager extends HashManagerCore {
+    /**
+     * Instance of XXHash API used for hashing operations.
+     */
+    xxhash: XXHashAPI;
+    /**
+     * Constructs a new XXHashHashManager.
+     * @param options - Options for the hash manager core.
+     */
+    constructor(options: HashManagerCoreOptions);
+    /**
+     * Initialises the XXHash API instance.
+     * @returns A promise resolving to true when initialisation is complete.
+     */
+    processInitialise(): Promise<boolean>;
+}
+/**
+ * Hash manager for the legacy hash algorithm (empty string).
+ * Utilises XXHash32 raw hashing.
+ */
+export declare class XXHash32RawHashManager extends XXHashHashManager {
+    /**
+     * Determines whether this manager is available for the specified algorithm.
+     * @param hashAlg - The hash algorithm to check.
+     * @returns True if available, false otherwise.
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+    /**
+     * Computes a hash for the given piece using encryption.
+     * @param piece - The input string to hash.
+     * @returns A promise resolving to the hash string.
+     */
+    computeHashWithEncryption(piece: string): Promise<string>;
+    /**
+     * Computes a hash for the given piece without encryption.
+     * @param piece - The input string to hash.
+     * @returns A promise resolving to the hash string.
+     */
+    computeHashWithoutEncryption(piece: string): Promise<string>;
+}
+/**
+ * Hash manager for the XXHash64 algorithm ("xxhash64").
+ */
+export declare class XXHash64HashManager extends XXHashHashManager {
+    /**
+     * Determines whether this manager is available for the specified algorithm.
+     * @param hashAlg - The hash algorithm to check.
+     * @returns True if available, false otherwise.
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+    /**
+     * Computes a hash for the given piece using encryption.
+     * @param piece - The input string to hash.
+     * @returns A promise resolving to the hash string.
+     */
+    computeHashWithEncryption(piece: string): Promise<string>;
+    /**
+     * Computes a hash for the given piece without encryption.
+     * @param piece - The input string to hash.
+     * @returns A promise resolving to the hash string.
+     */
+    computeHashWithoutEncryption(piece: string): Promise<string>;
+}
+/**
+ * Fallback hash manager utilising XXHash32.
+ * Used when no specific algorithm is matched.
+ * Please be careful with this manager, as it is different from XXHash32RawHashManager.
+ */
+export declare class FallbackWasmHashManager extends XXHashHashManager {
+    /**
+     * Determines whether this manager is available for the specified algorithm.
+     * Always returns true as a fallback.
+     * @param hashAlg - The hash algorithm to check.
+     * @returns True.
+     */
+    static isAvailableFor(hashAlg: HashAlgorithm): boolean;
+    /**
+     * Computes a hash for the given piece using encryption.
+     * @param piece - The input string to hash.
+     * @returns A promise resolving to the hash string.
+     */
+    computeHashWithEncryption(piece: string): Promise<string>;
+    /**
+     * Computes a hash for the given piece without encryption.
+     * @param piece - The input string to hash.
+     * @returns A promise resolving to the hash string.
+     */
+    computeHashWithoutEncryption(piece: string): Promise<string>;
+}