node-opcua-server-configuration 2.163.0 → 2.164.2

package/source/clientTools/push_certificate_management_client.ts

@@ -1,27 +1,26 @@
 /**
  * @module node-opcua-server-configuration.client
  */
-import { ByteString } from "node-opcua-basic-types";
-import { NodeId, resolveNodeId } from "node-opcua-nodeid";
-import { CallMethodRequestLike, IBasicSessionAsync } from "node-opcua-pseudo-session";
-import { StatusCode, StatusCodes } from "node-opcua-status-code";
-import { DataType, VariantArrayType, VariantLike } from "node-opcua-variant";
+import type { ByteString } from "node-opcua-basic-types";
+import { BinaryStream } from "node-opcua-binary-stream";
+import type { Certificate } from "node-opcua-crypto/web";
+import { AttributeIds, coerceQualifiedName, type QualifiedNameLike } from "node-opcua-data-model";
 import { ClientFile, OpenFileMode } from "node-opcua-file-transfer";
-import { AttributeIds, QualifiedNameLike, coerceQualifiedName } from "node-opcua-data-model";
+import { NodeId, resolveNodeId } from "node-opcua-nodeid";
+import type { CallMethodRequestLike, IBasicSessionAsync } from "node-opcua-pseudo-session";
 import { makeBrowsePath } from "node-opcua-service-translate-browse-path";
-import { Certificate } from "node-opcua-crypto/web";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
 import { TrustListDataType } from "node-opcua-types";
-import { BinaryStream } from "node-opcua-binary-stream";
+import { DataType, VariantArrayType, type VariantLike } from "node-opcua-variant";
 
-import {
+import type {
     CreateSigningRequestResult,
     GetRejectedListResult,
     PushCertificateManager,
     UpdateCertificateResult
-} from "../push_certificate_manager";
-
-import { ITrustList } from "../trust_list";
-import { TrustListMasks } from "../server/trust_list_server";
+} from "../push_certificate_manager.js";
+import type { TrustListMasks } from "../server/trust_list_server.js";
+import type { ITrustList } from "../trust_list.js";
 
 const serverConfigurationNodeId = resolveNodeId("ServerConfiguration");
 const createSigningRequestMethod = resolveNodeId("ServerConfiguration_CreateSigningRequest");
@@ -34,7 +33,6 @@ const defaultApplicationGroup = resolveNodeId("ServerConfiguration_CertificateGr
 const defaultHttpsGroup = resolveNodeId("ServerConfiguration_CertificateGroups_DefaultHttpsGroup");
 const defaultUserTokenGroup = resolveNodeId("ServerConfiguration_CertificateGroups_DefaultUserTokenGroup");
 
-
 function findCertificateGroupNodeId(certificateGroup: NodeId | string): NodeId {
     if (certificateGroup instanceof NodeId) {
         return certificateGroup;
@@ -64,7 +62,10 @@ export class TrustListClient extends ClientFile implements ITrustList {
     private removeCertificateNodeId?: NodeId;
     private openWithMasksNodeId?: NodeId;
 
-    constructor(session: IBasicSessionAsync, public nodeId: NodeId) {
+    constructor(
+        session: IBasicSessionAsync,
+        public nodeId: NodeId
+    ) {
         super(session, nodeId);
     }
     /**
@@ -78,12 +79,12 @@ export class TrustListClient extends ClientFile implements ITrustList {
             makeBrowsePath(this.nodeId, "/OpenWithMasks") // OpenWithMasks Mandatory
         ]);
 
-        this.closeAndUpdateNodeId = browseResults[0].targets![0].targetId;
-        this.addCertificateNodeId = browseResults[1].targets![0].targetId;
-        this.removeCertificateNodeId = browseResults[2].targets![0].targetId;
-        this.openWithMasksNodeId = browseResults[3].targets![0].targetId;
+        this.closeAndUpdateNodeId = browseResults[0].targets?.[0].targetId;
+        this.addCertificateNodeId = browseResults[1].targets?.[0].targetId;
+        this.removeCertificateNodeId = browseResults[2].targets?.[0].targetId;
+        this.openWithMasksNodeId = browseResults[3].targets?.[0].targetId;
 
-        // istanbul ignore next
+        // c8 ignore next
         if (!this.openWithMasksNodeId || this.openWithMasksNodeId.isEmpty()) {
             throw new Error("Cannot find mandatory method OpenWithMask on object");
         }
@@ -95,12 +96,12 @@ export class TrustListClient extends ClientFile implements ITrustList {
     }
 
     async openWithMasks(trustListMask: TrustListMasks): Promise<number> {
-        // istanbul ignore next
+        // c8 ignore next
         if (this.fileHandle) {
             throw new Error("File has already be opened");
         }
         await this.ensureInitialized();
-        // istanbul ignore next
+        // c8 ignore next
         if (!this.openWithMasksNodeId) {
             throw new Error("OpenWithMasks doesn't exist");
         }
@@ -114,11 +115,11 @@ export class TrustListClient extends ClientFile implements ITrustList {
         if (callMethodResult.statusCode.isNotGood()) {
             throw new Error(callMethodResult.statusCode.name);
         }
-        this.fileHandle = callMethodResult.outputArguments![0].value as number;
+        this.fileHandle = callMethodResult.outputArguments?.[0].value as number;
         return this.fileHandle;
     }
 
-    async closeAndUpdate(applyChangesRequired: boolean): Promise<boolean> {
+    async closeAndUpdate(): Promise<boolean> {
         if (!this.fileHandle) {
             throw new Error("File has node been opened yet");
         }
@@ -126,10 +127,7 @@ export class TrustListClient extends ClientFile implements ITrustList {
         if (!this.closeAndUpdateNodeId) {
             throw new Error("CloseAndUpdateMethod doesn't exist");
         }
-        const inputArguments = [
-            { dataType: DataType.UInt32, value: this.fileHandle },
-            { dataType: DataType.Boolean, value: !!applyChangesRequired }
-        ];
+        const inputArguments = [{ dataType: DataType.UInt32, value: this.fileHandle }];
         const methodToCall: CallMethodRequestLike = {
             inputArguments,
             methodId: this.closeAndUpdateNodeId,
@@ -139,7 +137,8 @@ export class TrustListClient extends ClientFile implements ITrustList {
         if (callMethodResult.statusCode.isNotGood()) {
             throw new Error(callMethodResult.statusCode.name);
         }
-        return callMethodResult.outputArguments![0].value as boolean;
+        this.fileHandle = 0;
+        return callMethodResult.outputArguments?.[0].value as boolean;
     }
 
     async addCertificate(certificate: Certificate, isTrustedCertificate: boolean): Promise<StatusCode> {
@@ -200,21 +199,25 @@ export class TrustListClient extends ClientFile implements ITrustList {
     }
 
     async writeTrustedCertificateList(trustedList: TrustListDataType): Promise<boolean> {
-        await this.open(OpenFileMode.Write);
+        await this.open(OpenFileMode.WriteEraseExisting);
         const s = trustedList.binaryStoreSize();
         const stream = new BinaryStream(s);
         trustedList.encode(stream);
-        return await this.closeAndUpdate(true);
+        await this.write(stream.buffer);
+        return await this.closeAndUpdate();
     }
 }
 export class CertificateGroup {
-    constructor(public session: IBasicSessionAsync, public nodeId: NodeId) {}
+    constructor(
+        public session: IBasicSessionAsync,
+        public nodeId: NodeId
+    ) {}
     async getCertificateTypes(): Promise<NodeId[]> {
         const browsePathResult = await this.session.translateBrowsePath(makeBrowsePath(this.nodeId, "/CertificateTypes"));
         if (browsePathResult.statusCode.isNotGood()) {
             throw new Error(browsePathResult.statusCode.name);
         }
-        const certificateTypesNodeId = browsePathResult.targets![0].targetId;
+        const certificateTypesNodeId = browsePathResult.targets?.[0].targetId;
         const dataValue = await this.session.read({ nodeId: certificateTypesNodeId, attributeId: AttributeIds.Value });
         if (dataValue.statusCode.isNotGood()) {
             throw new Error(browsePathResult.statusCode.name);
@@ -226,7 +229,10 @@ export class CertificateGroup {
         if (browsePathResult.statusCode.isNotGood()) {
             throw new Error(browsePathResult.statusCode.name);
         }
-        const trustListNodeId = browsePathResult.targets![0].targetId;
+        const trustListNodeId = browsePathResult.targets?.[0].targetId;
+        if (!trustListNodeId) {
+            throw new Error("TrustList node not found");
+        }
         return new TrustListClient(this.session, trustListNodeId);
     }
 }
@@ -302,7 +308,7 @@ export class ClientPushCertificateManagement implements PushCertificateManager {
 
         if (callMethodResult.statusCode.isGood()) {
             return {
-                certificateSigningRequest: callMethodResult.outputArguments![0].value,
+                certificateSigningRequest: callMethodResult.outputArguments?.[0].value,
                 statusCode: callMethodResult.statusCode
             };
         } else {
@@ -330,11 +336,11 @@ export class ClientPushCertificateManagement implements PushCertificateManager {
         };
         const callMethodResult = await this.session.call(methodToCall);
         if (callMethodResult.statusCode.isGood()) {
-            if (callMethodResult.outputArguments![0].dataType !== DataType.ByteString) {
+            if (callMethodResult.outputArguments?.[0].dataType !== DataType.ByteString) {
                 return { statusCode: StatusCodes.BadInvalidArgument };
             }
             return {
-                certificates: callMethodResult.outputArguments![0].value,
+                certificates: callMethodResult.outputArguments?.[0].value,
                 statusCode: callMethodResult.statusCode
             };
         } else {
@@ -422,22 +428,21 @@ export class ClientPushCertificateManagement implements PushCertificateManager {
         };
         const callMethodResult = await this.session.call(methodToCall);
         if (callMethodResult.statusCode.isGood()) {
-            if (!callMethodResult.outputArguments || callMethodResult.outputArguments!.length !== 1) {
+            if (!callMethodResult.outputArguments || callMethodResult.outputArguments.length !== 1) {
                 return {
                     statusCode: StatusCodes.BadInternalError,
-                    applyChangesRequired: false,
+                    applyChangesRequired: false
                 };
                 // throw Error("Internal Error, expecting 1 output result");
             }
             return {
-                applyChangesRequired: !!callMethodResult.outputArguments![0].value,
+                applyChangesRequired: !!callMethodResult.outputArguments?.[0].value,
                 statusCode: callMethodResult.statusCode
             };
         } else {
-            return { 
+            return {
                 statusCode: callMethodResult.statusCode,
                 applyChangesRequired: false
-
             };
         }
     }
@@ -471,7 +476,7 @@ export class ClientPushCertificateManagement implements PushCertificateManager {
         };
         const callMethodResult = await this.session.call(methodToCall);
 
-        if (callMethodResult.outputArguments && callMethodResult.outputArguments.length) {
+        if (callMethodResult.outputArguments?.length) {
             throw new Error("Invalid  output arguments");
         }
         return callMethodResult.statusCode;
@@ -507,7 +512,7 @@ export class ClientPushCertificateManagement implements PushCertificateManager {
         if (browseName.toString() === "DefaultUserTokenGroup") {
             return new CertificateGroup(this.session, defaultUserTokenGroup);
         }
-        // istanbul ignore next
+        // c8 ignore next
         throw new Error("Not Implemented yet");
     }
     public async getApplicationGroup(): Promise<CertificateGroup> {

package/source/index.ts

@@ -2,11 +2,13 @@
  * @module node-opcua-server-configuration
  */
 // export * from "./trust_list_impl";
-export * from "./push_certificate_manager";
-export * from "./clientTools/push_certificate_management_client";
-export * from "./standard_certificate_types";
 
-export * from "./server/install_push_certitifate_management";
-export * from "./server/push_certificate_manager_server_impl";
-export * from "./server/push_certificate_manager_helpers";
-export * from "./server/promote_trust_list";
+export * from "./clientTools/certificate_types.js";
+export * from "./clientTools/push_certificate_management_client.js";
+export * from "./push_certificate_manager.js";
+export * from "./server/install_push_certitifate_management.js";
+export * from "./server/promote_trust_list.js";
+export * from "./server/push_certificate_manager/subject_to_string.js";
+export * from "./server/push_certificate_manager_helpers.js";
+export * from "./server/push_certificate_manager_server_impl.js";
+export * from "./standard_certificate_types.js";

package/source/push_certificate_manager.ts

@@ -1,9 +1,9 @@
 /**
  * @module node-opcua-server-configuration
  */
-import { ByteString, UAString } from "node-opcua-basic-types";
-import { NodeId } from "node-opcua-nodeid";
-import { StatusCode } from "node-opcua-status-code";
+import type { ByteString, UAString } from "node-opcua-basic-types";
+import type { NodeId } from "node-opcua-nodeid";
+import type { StatusCode } from "node-opcua-status-code";
 
 export interface CreateSigningRequestResult {
     statusCode: StatusCode;
@@ -21,7 +21,6 @@ export interface UpdateCertificateResult {
 }
 
 export interface PushCertificateManager {
-
     /**
      * The SupportedPrivateKeyFormats specifies the private key formats supported by the Server.
      * Possible values include “PEM” (see RFC 5958) or “PFX” (see PKCS #12). The array is empty
@@ -65,12 +64,12 @@ export interface PushCertificateManager {
      *
      */
     updateCertificate(
-      certificateGroupId: NodeId | string,
-      certificateTypeId: NodeId | string,
-      certificate: ByteString,
-      issuerCertificates: ByteString[],
-      privateKeyFormat: UAString,
-      privateKey: ByteString
+        certificateGroupId: NodeId | string,
+        certificateTypeId: NodeId | string,
+        certificate: ByteString,
+        issuerCertificates: ByteString[],
+        privateKeyFormat?: UAString,
+        privateKey?: ByteString
     ): Promise<UpdateCertificateResult>;
 
     /**
@@ -136,11 +135,11 @@ export interface PushCertificateManager {
      * Bad_UserAccessDenied          The current user does not have the rights required.
      */
     createSigningRequest(
-      certificateGroupId: NodeId | string,
-      certificateTypeId: NodeId | string,
-      subjectName: string | null,
-      regeneratePrivateKey?: boolean,
-      nonce?: ByteString
+        certificateGroupId: NodeId | string,
+        certificateTypeId: NodeId | string,
+        subjectName: string | null,
+        regeneratePrivateKey?: boolean,
+        nonce?: ByteString
     ): Promise<CreateSigningRequestResult>;
 
     /**
@@ -159,6 +158,5 @@ export interface PushCertificateManager {
      *  Bad_UserAccessDenied  The current user does not have the rights required
      */
 
-    getRejectedList(): Promise</*certificates*/GetRejectedListResult>;
-
+    getRejectedList(): Promise</*certificates*/ GetRejectedListResult>;
 }

package/source/server/certificate_validation.ts

@@ -0,0 +1,103 @@
+/**
+ * @module node-opcua-server-configuration-server
+ */
+import type { ByteString } from "node-opcua-basic-types";
+import type { OPCUACertificateManager } from "node-opcua-certificate-manager";
+import { type CertificateInternals, exploreCertificate, verifyCertificateChain } from "node-opcua-crypto/web";
+import { make_errorLog, make_warningLog } from "node-opcua-debug";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+
+const warningLog = make_warningLog("ServerConfiguration");
+const errorLog = make_errorLog("ServerConfiguration");
+
+/**
+ * Validates the certificate and its issuer chain, including parsing, date validity,
+ * chain verification, and trust verification.
+ * @returns Object with statusCode. If Good, also contains the concatenated certificateChain.
+ */
+export async function validateCertificateAndChain(
+    certificateManager: OPCUACertificateManager,
+    isApplicationGroup: boolean,
+    certificate: Buffer,
+    issuerCertificates: ByteString[] | null | undefined
+): Promise<{ statusCode: StatusCode; certificateChain?: Buffer }> {
+    let certInfo: CertificateInternals;
+    try {
+        certInfo = exploreCertificate(certificate);
+    } catch (err) {
+        errorLog("Cannot parse certificate:", (err as Error).message);
+        return { statusCode: StatusCodes.BadCertificateInvalid };
+    }
+
+    const issuerCertBuffers = (issuerCertificates || []).filter((cert): cert is Buffer => {
+        return Buffer.isBuffer(cert) && cert.length > 0;
+    });
+
+    if ((issuerCertificates || []).length !== issuerCertBuffers.length) {
+        warningLog("issuerCertificates contains invalid entries");
+        return { statusCode: StatusCodes.BadCertificateInvalid };
+    }
+
+    for (const issuerCert of issuerCertBuffers) {
+        try {
+            const issuerInfo = exploreCertificate(issuerCert);
+            const nowIssuer = new Date();
+            if (issuerInfo.tbsCertificate.validity.notBefore.getTime() > nowIssuer.getTime()) {
+                warningLog("Issuer certificate is not yet valid");
+                return { statusCode: StatusCodes.BadSecurityChecksFailed };
+            }
+            if (issuerInfo.tbsCertificate.validity.notAfter.getTime() < nowIssuer.getTime()) {
+                warningLog("Issuer certificate is out of date");
+                return { statusCode: StatusCodes.BadSecurityChecksFailed };
+            }
+        } catch (err) {
+            errorLog("Cannot parse issuer certificate:", (err as Error).message);
+            return { statusCode: StatusCodes.BadCertificateInvalid };
+        }
+    }
+
+    if (issuerCertBuffers.length > 0) {
+        const chainCheck = await verifyCertificateChain([certificate, ...issuerCertBuffers]);
+        if (chainCheck.status !== "Good") {
+            warningLog("Issuer chain validation failed:", chainCheck.status, chainCheck.reason);
+            return { statusCode: StatusCodes.BadSecurityChecksFailed };
+        }
+    }
+
+    const certificateChain = Buffer.concat([certificate, ...issuerCertBuffers]);
+
+    // Trust validation is only relevant for client certificates, not the server's own certificate
+    if (!isApplicationGroup) {
+        if (certificateManager.verifyCertificate) {
+            const status = await certificateManager.verifyCertificate(certificateChain, {
+                acceptCertificateWithValidIssuerChain: true
+            });
+            if (status !== "Good") {
+                warningLog("Certificate trust validation failed:", status);
+                return { statusCode: StatusCodes.BadSecurityChecksFailed };
+            }
+        }
+    }
+
+    const now = new Date();
+    if (certInfo.tbsCertificate.validity.notBefore.getTime() > now.getTime()) {
+        warningLog(
+            "Certificate is not yet valid : not before ",
+            certInfo.tbsCertificate.validity.notBefore.toISOString(),
+            "now = ",
+            now.toISOString()
+        );
+        return { statusCode: StatusCodes.BadSecurityChecksFailed };
+    }
+    if (certInfo.tbsCertificate.validity.notAfter.getTime() < now.getTime()) {
+        warningLog(
+            "Certificate is already out of date : not after ",
+            certInfo.tbsCertificate.validity.notAfter.toISOString(),
+            "now = ",
+            now.toISOString()
+        );
+        return { statusCode: StatusCodes.BadSecurityChecksFailed };
+    }
+
+    return { statusCode: StatusCodes.Good, certificateChain };
+}

package/source/server/file_transaction_manager.ts

@@ -0,0 +1,253 @@
+/**
+ * @module node-opcua-server-configuration-server
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { make_debugLog, make_errorLog, make_warningLog } from "node-opcua-debug";
+
+const debugLog = make_debugLog("ServerConfiguration");
+const errorLog = make_errorLog("ServerConfiguration");
+const warningLog = make_warningLog("ServerConfiguration");
+
+type Functor = () => Promise<void>;
+
+async function _copyFile(source: string, dest: string): Promise<void> {
+    try {
+        debugLog("copying file \n source ", source, "\n =>\n dest ", dest);
+        const sourceExist = fs.existsSync(source);
+        if (sourceExist) {
+            await fs.promises.copyFile(source, dest);
+        }
+    } catch (err) {
+        errorLog(err);
+    }
+}
+
+async function _deleteFile(file: string): Promise<void> {
+    try {
+        const exists = fs.existsSync(file);
+        if (exists) {
+            debugLog("deleting file ", file);
+            await fs.promises.unlink(file);
+        }
+    } catch (err) {
+        errorLog(err);
+    }
+}
+
+async function _moveFile(source: string, dest: string): Promise<void> {
+    debugLog("moving file file \n source ", source, "\n =>\n dest ", dest);
+    try {
+        await _copyFile(source, dest);
+        await _deleteFile(source);
+    } catch (err) {
+        errorLog(err);
+    }
+}
+
+async function _moveFileWithBackup(source: string, dest: string, backupPath: string): Promise<void> {
+    // let make a copy of the destination file
+    debugLog("moveFileWithBackup file \n source ", source, "\n =>\n dest ", dest);
+    await _copyFile(dest, backupPath);
+    await _moveFile(source, dest);
+}
+
+export class FileTransactionManager {
+    readonly #pendingFileOps: Functor[] = [];
+    readonly #cleanupTasks: Functor[] = [];
+    readonly #backupFiles: Map<string, string> = new Map();
+    #tmpdir?: string;
+
+    /**
+     * Gets or initializes the underlying temporary directory for the transaction.
+     */
+    public async getTmpDir(): Promise<string> {
+        if (!this.#tmpdir) {
+            const tempBase = path.join(os.tmpdir(), "node-opcua-tx-");
+            this.#tmpdir = await fs.promises.mkdtemp(tempBase);
+        }
+        return this.#tmpdir;
+    }
+
+    /**
+     * Stages a file for writing during the transaction.
+     * Writes the content to a temporary location and registers
+     * a move operation to atomically place it at destinationPath upon applyFileOps().
+     */
+    public async stageFile(destinationPath: string, content: Buffer | string, encoding?: BufferEncoding): Promise<void> {
+        // ensure tmpdir exists
+        const tmpDir = await this.getTmpDir();
+
+        const uniqueFileName = `${crypto.randomBytes(16).toString("hex")}.tmp`;
+        const tempFilePath = path.join(tmpDir, uniqueFileName);
+
+        if (encoding) {
+            await fs.promises.writeFile(tempFilePath, content as string, encoding);
+        } else {
+            await fs.promises.writeFile(tempFilePath, content);
+        }
+
+        this.addFileOp(() => this.#moveFileWithBackupTracked(tempFilePath, destinationPath));
+    }
+
+    public addFileOp(functor: Functor): void {
+        this.#pendingFileOps.push(functor);
+    }
+
+    public addCleanupTask(functor: Functor): void {
+        this.#cleanupTasks.push(functor);
+    }
+
+    public get pendingTasksCount(): number {
+        return this.#pendingFileOps.length;
+    }
+
+    /**
+     * Abort the current transaction by clearing pending file operations
+     * and deleting the temporary staging folder.
+     */
+    public async abortTransaction(): Promise<void> {
+        this.#pendingFileOps.length = 0;
+        await this.#executeCleanupTasks();
+        await this.#cleanupTempFolder();
+    }
+
+    /**
+     * Move file with backup and track the backup for potential rollback.
+     * This method creates a backup of the destination file and tracks it
+     * so it can be restored if the transaction fails.
+     */
+    async #moveFileWithBackupTracked(source: string, dest: string): Promise<void> {
+        const tmpDir = await this.getTmpDir();
+        const uniqueFileName = `${crypto.randomBytes(16).toString("hex")}_backup.tmp`;
+        const backupPath = path.join(tmpDir, uniqueFileName);
+
+        // Track the backup before creating it
+        this.#backupFiles.set(dest, backupPath);
+
+        // Perform the actual move with backup
+        await _moveFileWithBackup(source, dest, backupPath);
+    }
+
+    /**
+     * Commit the transaction by executing all pending file operations.
+     */
+    public async applyFileOps(): Promise<void> {
+        debugLog("start applyFileOps");
+        const fileOperation = this.#pendingFileOps.splice(0);
+
+        try {
+            while (fileOperation.length) {
+                const op = fileOperation.shift();
+                await op?.();
+            }
+            debugLog("end applyFileOps");
+
+            // Transaction successful - clean up backup files
+            await this.#cleanupBackupFiles();
+            await this.#executeCleanupTasks();
+            await this.#cleanupTempFolder();
+        } catch (err) {
+            errorLog("Error during applyFileOps:", (err as Error).message);
+            errorLog("Rolling back transaction to restore previous certificate state");
+
+            // Rollback: restore all backup files to their original locations
+            try {
+                await this.#rollbackTransaction();
+                debugLog("Transaction rollback successful");
+            } catch (rollbackErr) {
+                errorLog("Critical: Rollback failed:", (rollbackErr as Error).message);
+                errorLog("Certificate state may be inconsistent - manual intervention required");
+            }
+
+            // Clear backup tracking after rollback
+            this.#backupFiles.clear();
+            await this.#executeCleanupTasks();
+            await this.#cleanupTempFolder();
+
+            throw err;
+        }
+    }
+
+    /**
+     * Rollback the transaction by restoring all backup files.
+     * This restores files from their *_old backups to recover the previous state.
+     */
+    async #rollbackTransaction(): Promise<void> {
+        debugLog("Rolling back transaction, restoring", this.#backupFiles.size, "backup files");
+
+        const rollbackPromises: Promise<void>[] = [];
+
+        for (const [dest, backupPath] of this.#backupFiles.entries()) {
+            rollbackPromises.push(
+                (async () => {
+                    try {
+                        // Check if backup exists before trying to restore
+                        if (fs.existsSync(backupPath)) {
+                            debugLog("Restoring backup:", backupPath, "to", dest);
+                            await _copyFile(backupPath, dest);
+                            // Delete backup immediately after restoration
+                            await _deleteFile(backupPath);
+                        }
+                    } catch (err) {
+                        errorLog("Error restoring backup file", backupPath, "to", dest, ":", (err as Error).message);
+                    }
+                })()
+            );
+        }
+
+        await Promise.all(rollbackPromises);
+        debugLog("Transaction rollback completed");
+    }
+
+    /**
+     * Clean up backup files after successful transaction.
+     * Removes all *_old backup files that were created during the transaction.
+     */
+    async #cleanupBackupFiles(): Promise<void> {
+        debugLog("Cleaning up", this.#backupFiles.size, "backup files");
+
+        const cleanupPromises: Promise<void>[] = [];
+
+        for (const backupPath of this.#backupFiles.values()) {
+            cleanupPromises.push(
+                _deleteFile(backupPath).catch((err) => {
+                    warningLog("Failed to delete backup file", backupPath, ":", err);
+                })
+            );
+        }
+
+        await Promise.all(cleanupPromises);
+        this.#backupFiles.clear();
+    }
+
+    /**
+     * Clean up the temporary transaction folder.
+     */
+    async #cleanupTempFolder(): Promise<void> {
+        if (this.#tmpdir) {
+            try {
+                await fs.promises.rm(this.#tmpdir, { recursive: true, force: true });
+            } catch (err) {
+                warningLog("Failed to delete temporary transaction folder", this.#tmpdir, ":", err);
+            } finally {
+                this.#tmpdir = undefined;
+            }
+        }
+    }
+
+    async #executeCleanupTasks(): Promise<void> {
+        debugLog("Executing cleanup tasks");
+        const tasks = this.#cleanupTasks.splice(0);
+        for (const task of tasks) {
+            try {
+                await task();
+            } catch (err) {
+                errorLog("Error during cleanup task:", (err as Error).message);
+            }
+        }
+    }
+}