@cetapod/react-native-smb 1.0.0

package/cpp/shared/io/SmbFileIO.hpp

@@ -0,0 +1,45 @@
+// SMB file I/O helpers — sync and async pipelined variants.
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <cstddef>
+#include <ctime>
+#include <functional>
+#include <string>
+#include <vector>
+
+#include "../ReactNativeSmb.hpp"
+#include "../core/CancellationToken.hpp"
+
+namespace react_native_smb {
+
+// Sync helpers run on the I/O thread.
+
+// Read remote SMB file to local path. Returns total bytes read.
+int64_t smbReadFile(
+    void* ctx, const std::string& remotePath, const std::string& localPath, std::function<void(double, double)> progressHandler = [](double, double) {}, const CancellationToken& cancel = {});
+
+// Upload local file to remote SMB path. Returns total bytes written.
+int64_t smbWriteFile(
+    void* ctx, const std::string& localPath, const std::string& remotePath, std::function<void(double, double)> progressHandler = [](double, double) {}, const CancellationToken& cancel = {});
+
+// Copy SMB file to another SMB location. Returns total bytes copied.
+// totalBytesCopied: shared counter for cumulative progress across multiple files.
+int64_t smbCopyFile(void* ctx, const std::string& fromPath, const std::string& toPath, std::shared_ptr<int64_t> totalBytesCopied, int64_t totalSize,
+                    std::function<void(double, double)> progressHandler = {}, const CancellationToken& cancel = {});
+
+// Async pipelined helpers (drive poll loop on caller thread; call under connectionMutex_).
+
+// Async pipelined download. Returns total bytes read.
+int64_t smbReadFileAsync(void* ctx, const std::string& remotePath, const std::string& localPath, std::function<void(double, double)> progressHandler = {}, const CancellationToken& cancel = {});
+
+// Async pipelined upload. Returns total bytes written.
+int64_t smbWriteFileAsync(void* ctx, const std::string& localPath, const std::string& remotePath, std::function<void(double, double)> progressHandler = {}, const CancellationToken& cancel = {});
+
+// Async pipelined SMB->SMB copy on the same context.
+// totalBytesCopied: shared counter for cumulative progress. Returns bytes copied.
+int64_t smbCopyFileAsync(void* ctx, const std::string& fromPath, const std::string& toPath, std::shared_ptr<int64_t> totalBytesCopied, int64_t totalSize,
+                         std::function<void(double, double)> progressHandler = {}, const CancellationToken& cancel = {});
+
+}  // namespace react_native_smb

package/cpp/shared/io/SmbPathUtil.hpp

@@ -0,0 +1,75 @@
+#pragma once
+
+#include <smb2/libsmb2.h>
+#include <smb2/smb2.h>
+
+#include <cstdint>
+#include <string>
+
+#include "../ReactNativeSmb.hpp"  // SmbFileInfo
+
+namespace react_native_smb {
+
+// Path and stat helpers shared by operators.
+namespace path_util {
+
+// Strip a single leading '/'; map "." / "/" / "" to empty (libsmb2 root form).
+inline std::string normalized(const std::string& path) {
+    std::string p = path;
+    if (p == "." || p == "/" || p.empty()) {
+        p = "";
+    } else if (p[0] == '/') {
+        p = p.substr(1);
+    }
+    return p;
+}
+
+// Join base + child with exactly one separator.
+inline std::string buildUrl(const std::string& baseUrl, const std::string& path) {
+    if (path.empty() || path == "/") return baseUrl;
+    if (baseUrl.empty()) return path;
+    std::string result = baseUrl;
+    if (result.back() != '/' && path.front() != '/') result += "/";
+    result += path;
+    return result;
+}
+
+inline std::string extractFileName(const std::string& path) {
+    size_t lastSlash = path.find_last_of("/\\");
+    return (lastSlash != std::string::npos) ? path.substr(lastSlash + 1) : path;
+}
+
+inline std::string parentOf(const std::string& path) {
+    size_t lastSlash = path.find_last_of("/\\");
+    std::string parent = (lastSlash != std::string::npos && lastSlash > 0) ? path.substr(0, lastSlash) : "/";
+    if (parent.empty()) parent = "/";
+    return parent;
+}
+
+// Strip a "file://" prefix from a local URI.
+inline std::string convertUriToPath(const std::string& path) {
+    const std::string fileProtocol = "file://";
+    if (path.find(fileProtocol) == 0) return path.substr(fileProtocol.length());
+    return path;
+}
+
+// Build an SmbFileInfo from a stat struct (childCount unknown = -1).
+inline SmbFileInfo makeFileInfo(const struct smb2_stat_64& stat, const std::string& name, const std::string& path) {
+    bool isDirectory = (stat.smb2_type & SMB2_TYPE_DIRECTORY) != 0;
+    int64_t size = isDirectory ? 0 : static_cast<int64_t>(stat.smb2_size);
+    return SmbFileInfo{
+        name,
+        path,
+        size,
+        isDirectory,
+        static_cast<int64_t>(stat.smb2_mtime),
+        static_cast<int64_t>(stat.smb2_atime),
+        static_cast<int64_t>(stat.smb2_btime),
+        static_cast<int64_t>(stat.smb2_ctime),
+        -1,
+        {},
+    };
+}
+
+}  // namespace path_util
+}  // namespace react_native_smb

package/cpp/shared/io/SmbSecurity.cpp

@@ -0,0 +1,308 @@
+#include "SmbSecurity.hpp"
+
+#include <iomanip>
+#include <sstream>
+
+namespace react_native_smb {
+
+std::string SmbSecurity::convertSidToString(struct smb2_sid* sid) {
+    if (!sid) {
+        return "";
+    }
+
+    std::stringstream ss;
+    ss << "S-1";
+
+    // Convert identifier authority
+    uint64_t ia = 0;
+    for (int i = 0; i < SID_ID_AUTH_LEN; i++) {
+        ia <<= 8;
+        ia |= sid->id_auth[i];
+    }
+
+    if (ia <= 0xffffffff) {
+        ss << "-" << ia;
+    } else {
+        ss << "-0x" << std::hex << ia;
+    }
+
+    // Convert sub-authorities
+    for (int i = 0; i < sid->sub_auth_count; i++) {
+        ss << "-" << sid->sub_auth[i];
+    }
+
+    return ss.str();
+}
+
+std::vector<std::string> SmbSecurity::convertControlFlags(const std::uint16_t& control, bool longForm) {
+    std::vector<std::string> flags;
+
+    if (control == 0) {
+        flags.push_back("None");
+        return flags;
+    }
+
+    if (control & SMB2_SD_CONTROL_SR) flags.push_back(longForm ? "SELF_RELATIVE" : "SR");
+    if (control & SMB2_SD_CONTROL_RM) flags.push_back(longForm ? "RM_CONTROL_VALID" : "RM");
+    if (control & SMB2_SD_CONTROL_PS) flags.push_back(longForm ? "SACL_PROTECTED" : "PS");
+    if (control & SMB2_SD_CONTROL_PD) flags.push_back(longForm ? "DACL_PROTECTED" : "PD");
+    if (control & SMB2_SD_CONTROL_SI) flags.push_back(longForm ? "SACL_AUTO_INHERITED" : "SI");
+    if (control & SMB2_SD_CONTROL_DI) flags.push_back(longForm ? "DACL_AUTO_INHERITED" : "DI");
+    if (control & SMB2_SD_CONTROL_SC) flags.push_back(longForm ? "SACL_COMPUTED_INHERITANCE_REQUIRED" : "SC");
+    if (control & SMB2_SD_CONTROL_DC) flags.push_back(longForm ? "DACL_COMPUTED_INHERITANCE_REQUIRED" : "DC");
+    if (control & SMB2_SD_CONTROL_DT) flags.push_back(longForm ? "DACL_TRUSTED" : "DT");
+    if (control & SMB2_SD_CONTROL_SS) flags.push_back(longForm ? "SERVER_SECURITY" : "SS");
+    if (control & SMB2_SD_CONTROL_SD) flags.push_back(longForm ? "SACL_DEFAULTED" : "SD");
+    if (control & SMB2_SD_CONTROL_SP) flags.push_back(longForm ? "SACL_PRESENT" : "SP");
+    if (control & SMB2_SD_CONTROL_DD) flags.push_back(longForm ? "DACL_DEFAULTED" : "DD");
+    if (control & SMB2_SD_CONTROL_DP) flags.push_back(longForm ? "DACL_PRESENT" : "DP");
+    if (control & SMB2_SD_CONTROL_GD) flags.push_back(longForm ? "GROUP_DEFAULTED" : "GD");
+    if (control & SMB2_SD_CONTROL_OD) flags.push_back(longForm ? "OWNER_DEFAULTED" : "OD");
+
+    if (flags.empty()) {
+        std::stringstream ss;
+        ss << "0x" << std::hex << control;
+        flags.push_back(ss.str());
+    }
+
+    return flags;
+}
+
+std::vector<std::string> SmbSecurity::convertAccessMask(const uint32_t& mask) {
+    std::vector<std::string> permissions;
+
+    if (mask == 0) {
+        permissions.push_back("None");
+        return permissions;
+    }
+
+    // Generic access rights (highest priority)
+    if (mask & SMB2_GENERIC_ALL) permissions.push_back("GENERIC_ALL");
+    if (mask & SMB2_GENERIC_EXECUTE) permissions.push_back("GENERIC_EXECUTE");
+    if (mask & SMB2_GENERIC_WRITE) permissions.push_back("GENERIC_WRITE");
+    if (mask & SMB2_GENERIC_READ) permissions.push_back("GENERIC_READ");
+
+    // Standard access rights
+    if (mask & SMB2_MAXIMUM_ALLOWED) permissions.push_back("MAXIMUM_ALLOWED");
+    if (mask & SMB2_ACCESS_SYSTEM_SECURITY) permissions.push_back("ACCESS_SYSTEM_SECURITY");
+    if (mask & SMB2_SYNCHRONIZE) permissions.push_back("SYNCHRONIZE");
+    if (mask & SMB2_WRITE_OWNER) permissions.push_back("WRITE_OWNER");
+    if (mask & SMB2_WRITE_DACL) permissions.push_back("WRITE_DACL");
+    if (mask & SMB2_READ_CONTROL) permissions.push_back("READ_CONTROL");
+    if (mask & SMB2_DELETE) permissions.push_back("DELETE");
+
+    // File/directory specific access rights
+    if (mask & SMB2_FILE_WRITE_ATTRIBUTES) permissions.push_back("WRITE_ATTRIBUTES");
+    if (mask & SMB2_FILE_READ_ATTRIBUTES) permissions.push_back("READ_ATTRIBUTES");
+    if (mask & SMB2_FILE_DELETE_CHILD) permissions.push_back("DELETE_CHILD");
+    if (mask & SMB2_FILE_EXECUTE) permissions.push_back("EXECUTE");
+    if (mask & SMB2_FILE_WRITE_EA) permissions.push_back("WRITE_EA");
+    if (mask & SMB2_FILE_READ_EA) permissions.push_back("READ_EA");
+
+    // File specific rights
+    if (mask & SMB2_FILE_APPEND_DATA) permissions.push_back("APPEND_DATA");
+    if (mask & SMB2_FILE_WRITE_DATA) permissions.push_back("WRITE_DATA");
+    if (mask & SMB2_FILE_READ_DATA) permissions.push_back("READ_DATA");
+
+    if (permissions.empty()) {
+        std::stringstream ss;
+        ss << "0x" << std::hex << mask;
+        permissions.push_back(ss.str());
+    }
+
+    return permissions;
+}
+
+std::vector<std::string> SmbSecurity::convertAccessMask(const uint32_t& mask, bool isDirectory) {
+    std::vector<std::string> permissions;
+
+    if (mask == 0) {
+        permissions.push_back("None");
+        return permissions;
+    }
+
+    // Generic access rights (highest priority)
+    if (mask & SMB2_GENERIC_ALL) permissions.push_back("GENERIC_ALL");
+    if (mask & SMB2_GENERIC_EXECUTE) permissions.push_back("GENERIC_EXECUTE");
+    if (mask & SMB2_GENERIC_WRITE) permissions.push_back("GENERIC_WRITE");
+    if (mask & SMB2_GENERIC_READ) permissions.push_back("GENERIC_READ");
+
+    // Standard access rights
+    if (mask & SMB2_MAXIMUM_ALLOWED) permissions.push_back("MAXIMUM_ALLOWED");
+    if (mask & SMB2_ACCESS_SYSTEM_SECURITY) permissions.push_back("ACCESS_SYSTEM_SECURITY");
+    if (mask & SMB2_SYNCHRONIZE) permissions.push_back("SYNCHRONIZE");
+    if (mask & SMB2_WRITE_OWNER) permissions.push_back("WRITE_OWNER");
+    if (mask & SMB2_WRITE_DACL) permissions.push_back("WRITE_DACL");
+    if (mask & SMB2_READ_CONTROL) permissions.push_back("READ_CONTROL");
+    if (mask & SMB2_DELETE) permissions.push_back("DELETE");
+
+    // File/directory specific access rights
+    if (mask & SMB2_FILE_WRITE_ATTRIBUTES) permissions.push_back("WRITE_ATTRIBUTES");
+    if (mask & SMB2_FILE_READ_ATTRIBUTES) permissions.push_back("READ_ATTRIBUTES");
+    if (mask & SMB2_FILE_DELETE_CHILD) permissions.push_back("DELETE_CHILD");
+    if (mask & SMB2_FILE_WRITE_EA) permissions.push_back("WRITE_EA");
+    if (mask & SMB2_FILE_READ_EA) permissions.push_back("READ_EA");
+
+    // Context-specific rights
+    if (isDirectory) {
+        if (mask & SMB2_FILE_LIST_DIRECTORY) permissions.push_back("LIST_DIRECTORY");
+        if (mask & SMB2_FILE_ADD_FILE) permissions.push_back("ADD_FILE");
+        if (mask & SMB2_FILE_ADD_SUBDIRECTORY) permissions.push_back("ADD_SUBDIRECTORY");
+        if (mask & SMB2_FILE_TRAVERSE) permissions.push_back("TRAVERSE");
+    } else {
+        if (mask & SMB2_FILE_READ_DATA) permissions.push_back("READ_DATA");
+        if (mask & SMB2_FILE_WRITE_DATA) permissions.push_back("WRITE_DATA");
+        if (mask & SMB2_FILE_APPEND_DATA) permissions.push_back("APPEND_DATA");
+        if (mask & SMB2_FILE_EXECUTE) permissions.push_back("EXECUTE");
+    }
+
+    if (permissions.empty()) {
+        std::stringstream ss;
+        ss << "0x" << std::hex << mask;
+        permissions.push_back(ss.str());
+    }
+
+    return permissions;
+}
+
+std::string SmbSecurity::convertAceType(const uint8_t& aceType) {
+    switch (aceType) {
+        case SMB2_ACCESS_ALLOWED_ACE_TYPE:
+            return "ACCESS_ALLOWED";
+        case SMB2_ACCESS_DENIED_ACE_TYPE:
+            return "ACCESS_DENIED";
+        case SMB2_SYSTEM_AUDIT_ACE_TYPE:
+            return "SYSTEM_AUDIT";
+        case SMB2_ACCESS_ALLOWED_OBJECT_ACE_TYPE:
+            return "ACCESS_ALLOWED_OBJECT";
+        case SMB2_ACCESS_DENIED_OBJECT_ACE_TYPE:
+            return "ACCESS_DENIED_OBJECT";
+        case SMB2_SYSTEM_AUDIT_OBJECT_ACE_TYPE:
+            return "SYSTEM_AUDIT_OBJECT";
+        case SMB2_ACCESS_ALLOWED_CALLBACK_ACE_TYPE:
+            return "ACCESS_ALLOWED_CALLBACK";
+        case SMB2_ACCESS_DENIED_CALLBACK_ACE_TYPE:
+            return "ACCESS_DENIED_CALLBACK";
+        case SMB2_SYSTEM_MANDATORY_LABEL_ACE_TYPE:
+            return "SYSTEM_MANDATORY_LABEL";
+        case SMB2_SYSTEM_RESOURCE_ATTRIBUTE_ACE_TYPE:
+            return "SYSTEM_RESOURCE_ATTRIBUTE";
+        case SMB2_SYSTEM_SCOPED_POLICY_ID_ACE_TYPE:
+            return "SYSTEM_SCOPED_POLICY_ID";
+        default:
+            std::stringstream ss;
+            ss << "UNKNOWN_TYPE_0x" << std::hex << static_cast<int>(aceType);
+            return ss.str();
+    }
+}
+
+std::vector<std::string> SmbSecurity::convertAceFlags(const uint8_t& aceFlags) {
+    std::vector<std::string> flags;
+
+    if (aceFlags == 0) {
+        flags.push_back("None");
+        return flags;
+    }
+
+    if (aceFlags & SMB2_OBJECT_INHERIT_ACE) flags.push_back("OBJECT_INHERIT");
+    if (aceFlags & SMB2_CONTAINER_INHERIT_ACE) flags.push_back("CONTAINER_INHERIT");
+    if (aceFlags & SMB2_NO_PROPAGATE_INHERIT_ACE) flags.push_back("NO_PROPAGATE_INHERIT");
+    if (aceFlags & SMB2_INHERIT_ONLY_ACE) flags.push_back("INHERIT_ONLY");
+    if (aceFlags & SMB2_INHERITED_ACE) flags.push_back("INHERITED");
+    if (aceFlags & SMB2_SUCCESSFUL_ACCESS_ACE_FLAG) flags.push_back("SUCCESSFUL_ACCESS");
+    if (aceFlags & SMB2_FAILED_ACCESS_ACE_FLAG) flags.push_back("FAILED_ACCESS");
+
+    if (flags.empty()) {
+        std::stringstream ss;
+        ss << "0x" << std::hex << static_cast<int>(aceFlags);
+        flags.push_back(ss.str());
+    }
+
+    return flags;
+}
+
+SmbAcl SmbSecurity::convertAclToSmbAcl(struct smb2_acl* acl) {
+    SmbAcl result;
+    if (!acl) {
+        return result;
+    }
+
+    result.revision = acl->revision;
+    result.aceCount = acl->ace_count;
+
+    struct smb2_ace* ace = acl->aces;
+    int aceIndex = 0;
+
+    while (ace && aceIndex < acl->ace_count) {
+        try {
+            result.aces.push_back(convertAceToSmbAce(ace));
+            ace = ace->next;
+            aceIndex++;
+        } catch (const std::exception& e) {
+            break;
+        }
+    }
+
+    result.aceCount = static_cast<uint16_t>(result.aces.size());
+
+    return result;
+}
+
+SmbAce SmbSecurity::convertAceToSmbAce(struct smb2_ace* ace) {
+    SmbAce result;
+    if (!ace) {
+        return result;
+    }
+
+    result.aceType = convertAceType(ace->ace_type);
+    result.aceFlags = convertAceFlags(ace->ace_flags);
+    result.mask = convertAccessMask(ace->mask);
+    result.sid = SmbSecurity::convertSidToString(ace->sid);
+
+    return result;
+}
+
+SmbSecurityDescriptor SmbSecurity::processSecurityDescriptor(struct smb2_security_descriptor* sd) {
+    SmbSecurityDescriptor result{0, {}, "", "", SmbAcl{0, 0, {}}};
+
+    if (!sd) {
+        return result;
+    }
+
+    // Set revision
+    result.revision = sd->revision;
+
+    if (sd->control) {
+        result.control = convertControlFlags(sd->control, true);
+    } else {
+        result.control = {"None"};
+    }
+
+    // Convert Owner, Group, and DACL
+    if (sd->owner) {
+        result.ownerSid = convertSidToString(sd->owner);
+    } else {
+        result.ownerSid = "";
+    }
+
+    if (sd->group) {
+        result.groupSid = convertSidToString(sd->group);
+    } else {
+        result.groupSid = "";
+    }
+
+    if (sd->dacl) {
+        result.dacl = convertAclToSmbAcl(sd->dacl);
+    } else {
+        result.dacl = SmbAcl{0, 0, {}};
+    }
+
+    return result;
+}
+
+void SmbSecurity::freeAcl(struct smb2_acl* acl) {
+    if (acl) {
+        free(acl);
+    }
+}
+}  // namespace react_native_smb

package/cpp/shared/io/SmbSecurity.hpp

@@ -0,0 +1,32 @@
+#pragma once
+
+#include "../ReactNativeSmb.hpp"
+#include <cstdint>
+#include <cstddef>
+#include <ctime>
+#include <smb2/smb2.h>
+#include <smb2/libsmb2.h>
+#include <string>
+
+namespace react_native_smb {
+class SmbSecurity {
+   public:
+    static std::string convertSidToString(struct smb2_sid* sid);
+
+    static std::vector<std::string> convertControlFlags(const std::uint16_t& control, bool longForm = true);
+
+    static std::vector<std::string> convertAccessMask(const uint32_t& mask);
+    static std::vector<std::string> convertAccessMask(const uint32_t& mask, bool isDirectory);
+
+    static std::string convertAceType(const uint8_t& aceType);
+    static std::vector<std::string> convertAceFlags(const uint8_t& aceFlags);
+
+    static SmbAcl convertAclToSmbAcl(struct smb2_acl* acl);
+    static SmbAce convertAceToSmbAce(struct smb2_ace* ace);
+
+    static SmbSecurityDescriptor processSecurityDescriptor(struct smb2_security_descriptor* sd);
+
+   private:
+    static void freeAcl(struct smb2_acl* acl);
+};
+}  // namespace react_native_smb

package/cpp/shared/io/SmbTreeOps.hpp

@@ -0,0 +1,112 @@
+#pragma once
+
+#include <smb2/libsmb2.h>
+#include <smb2/smb2.h>
+
+#include <cctype>
+#include <sstream>
+#include <string>
+#include <vector>
+
+#include "../ReactNativeSmb.hpp"  // SmbFileInfo
+#include "../core/CancellationToken.hpp"
+#include "SmbDirScan.hpp"
+#include "SmbPathUtil.hpp"
+
+namespace react_native_smb {
+
+// Tree helpers for delete, copy, and duplicate operators.
+namespace tree_ops {
+
+// Depth-first collect of every descendant (children appended before parent so
+// callers can rmdir deepest-first). Skips inaccessible sub-dirs.
+inline void collectAllItems(smb2_context* ctx, const std::string& path, std::vector<SmbFileInfo>& allItems, const CancellationToken& cancel) {
+    try {
+        std::vector<SmbFileInfo> contents = listOnCtx(ctx, path, false, 0, cancel);
+        for (const auto& item : contents) {
+            if (item.isDirectory) collectAllItems(ctx, item.path, allItems, cancel);
+            allItems.push_back(item);
+        }
+    } catch (const std::exception&) {
+        // Permission errors on sub-dirs: skip; parent rmdir reports "not empty".
+    }
+}
+
+// Recursively total the byte size of a path. Returns partial size on errors.
+inline int64_t calculateTotalSize(smb2_context* ctx, const std::string& path, bool recursive, const CancellationToken& cancel) {
+    const std::string norm = path_util::normalized(path);
+    struct smb2_stat_64 stat;
+    if (smb2_stat(ctx, norm.c_str(), &stat) < 0) return 0;
+
+    const bool isDirectory = (stat.smb2_type & SMB2_TYPE_DIRECTORY) != 0;
+    if (!isDirectory) return static_cast<int64_t>(stat.smb2_size);
+    if (!recursive) return 0;
+
+    int64_t total = 0;
+    try {
+        std::vector<SmbFileInfo> contents = listOnCtx(ctx, path, false, 0, cancel);
+        for (const auto& item : contents) {
+            if (item.isDirectory)
+                total += calculateTotalSize(ctx, item.path, true, cancel);
+            else
+                total += item.size;
+        }
+    } catch (const std::exception&) {
+        // Ignore inaccessible directories; return partial size.
+    }
+    return total;
+}
+
+// Generate a unique "<base> copy[ N]<ext>" name not present in parentPath.
+inline std::string generateUniqueCopyName(smb2_context* ctx, const std::string& parentPath, const std::string& originalName, const CancellationToken& cancel) {
+    size_t lastDot = originalName.find_last_of('.');
+    std::string baseName = (lastDot != std::string::npos && lastDot > 0) ? originalName.substr(0, lastDot) : originalName;
+    std::string extension = (lastDot != std::string::npos && lastDot > 0) ? originalName.substr(lastDot) : "";
+
+    // Strip a previous " copy" / " copy N" suffix so copies-of-copies stay tidy.
+    const std::string copySuffix = " copy";
+    size_t copyPos = baseName.rfind(copySuffix);
+    if (copyPos != std::string::npos) {
+        std::string remainder = baseName.substr(copyPos + copySuffix.length());
+        bool isClean = false;
+        if (remainder.empty()) {
+            isClean = true;
+        } else if (remainder[0] == ' ') {
+            isClean = true;
+            for (size_t i = 1; i < remainder.length(); i++) {
+                if (!std::isdigit(static_cast<unsigned char>(remainder[i]))) {
+                    isClean = false;
+                    break;
+                }
+            }
+        }
+        if (isClean) baseName = baseName.substr(0, copyPos);
+    }
+
+    std::vector<SmbFileInfo> existingFiles = listOnCtx(ctx, parentPath, false, 0, cancel);
+    std::vector<std::string> existingNames;
+    existingNames.reserve(existingFiles.size());
+    for (const auto& item : existingFiles) existingNames.push_back(item.name);
+
+    int counter = 1;
+    while (true) {
+        std::stringstream ss;
+        ss << baseName << " copy";
+        if (counter > 1) ss << " " << counter;
+        ss << extension;
+        std::string candidate = ss.str();
+
+        bool found = false;
+        for (const auto& existing : existingNames) {
+            if (existing == candidate) {
+                found = true;
+                break;
+            }
+        }
+        if (!found) return candidate;
+        if (++counter > 10000) return candidate;  // safety break
+    }
+}
+
+}  // namespace tree_ops
+}  // namespace react_native_smb

package/cpp/shared/operators/Operator.hpp

@@ -0,0 +1,35 @@
+#pragma once
+
+#include "OperatorBase.hpp"
+
+// For JSIConverter<T> in publishThisResult convenience.
+#include "../ReactNativeSmb.hpp"  // brings the JSIConverter specializations in margelo::nitro namespace
+
+namespace jsi = facebook::jsi;
+
+namespace react_native_smb {
+
+// Operators that produce a value store it here; the concrete HybridSMB method
+// reads it back via result() once the task completes (typed, no erasure).
+// void-producing operators derive from OperatorBase directly.
+template <typename T>
+class Operator : public OperatorBase {
+   public:
+    const T& result() const { return result_; }
+
+   protected:
+    T result_{};
+
+    // Convenience for value-producing operators: publish our result_ + the
+    // correct converter directly to the owning task. Call this at the end of a
+    // successful run() (before or after emitStatus(Success)).
+    void publishThisResult() {
+        publishResult(std::any(result_), [](jsi::Runtime& rt, const std::any& a) -> jsi::Value {
+            const T* v = std::any_cast<T>(&a);
+            if (!v) return jsi::Value::undefined();
+            return margelo::nitro::JSIConverter<T>::toJSI(rt, *v);
+        });
+    }
+};
+
+}  // namespace react_native_smb

package/cpp/shared/operators/OperatorBase.cpp

@@ -0,0 +1,57 @@
+#include "OperatorBase.hpp"
+
+#include "../connection/SmbConnectionPool.hpp"
+#include "../core/SmbTask.hpp"
+
+namespace react_native_smb {
+
+void OperatorBase::start(SmbTask* task, SmbConnectionPool* pool, const CancellationToken& cancel, size_t opIndex) {
+    setContext(OperatorContext{task, pool, cancel, opIndex});
+    if (cancel.cancelled()) return;
+    run();
+}
+
+std::string OperatorBase::owningTaskId() const { return ctx_.task ? ctx_.task->getId() : std::string(); }
+
+MetadataContextLease OperatorBase::makeMetadataLease() {
+    if (ctx_.task) ctx_.task->markPending();
+    MetadataContextLease lease(pool(), kind(), owningTaskId());
+    if (ctx_.task && !isCancelled()) ctx_.task->markRunning();
+    return lease;
+}
+
+PoolContextHandle OperatorBase::requestContext(AcquireMode mode) {
+    if (ctx_.task) ctx_.task->markPending();
+    PoolContextHandle handle = pool().requestContext(mode, kind(), owningTaskId());
+    if (ctx_.task && !isCancelled()) ctx_.task->markRunning();
+    return handle;
+}
+
+void OperatorBase::emitStatus(SmbTaskStatus s, const std::string& error, int code) {
+    if (!ctx_.task) return;
+    if (isCancelled() && s == SmbTaskStatus::Success) return;
+    if (ctx_.task->getStatus() == SmbTaskStatus::Cancelled && s == SmbTaskStatus::Success) return;
+    ctx_.task->onOpStatus(ctx_.opIndex, s, error, code);
+}
+
+void OperatorBase::emitProgress(double done, double total) {
+    if (ctx_.task) ctx_.task->onOpProgress(ctx_.opIndex, done, total);
+}
+
+size_t OperatorBase::spawn(std::vector<std::unique_ptr<OperatorBase>> moreOps) {
+    return ctx_.task ? ctx_.task->spawn(std::move(moreOps)) : 0;
+}
+
+void OperatorBase::addExpectedBytes(int64_t bytes) {
+    if (ctx_.task) ctx_.task->addExpectedBytes(bytes);
+}
+
+void OperatorBase::setSourceDestination(const std::string& source, const std::string& destination) {
+    if (ctx_.task) ctx_.task->setPaths(source, destination);
+}
+
+void OperatorBase::publishResult(std::any value, std::function<jsi::Value(jsi::Runtime&, const std::any&)> converter) {
+    if (ctx_.task) ctx_.task->publishResult(std::move(value), std::move(converter));
+}
+
+}  // namespace react_native_smb