release(v3.18.0): file operation hardening

- security(upload): reject shared-upload filename collisions and require edit authority for replacements
- security(metadata): use collision-resistant folder metadata filenames

Author: error311

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## Changes 06/23/2026 (v3.18.0)
+
+`release(v3.18.0): file operation hardening`
+
+**Commit message**
+
+```text
+release(v3.18.0): file operation hardening
+
+- security(upload): reject shared-upload filename collisions and require edit authority for replacements
+- security(metadata): use collision-resistant folder metadata filenames
+```
+
+**Fixed**
+
+- **Upload overwrite hardening**
+  - Public shared-folder and portal uploads are now create-only when the destination filename already exists.
+  - Authenticated uploads now require edit authority plus ownership, folder ownership, admin, or bypass ownership before replacing an existing file.
+  - Upload collision errors preserve the original file content and return an explicit conflict/permission response.
+
+- **Folder metadata isolation hardening**
+  - Folder metadata filenames now preserve distinct logical folder paths instead of flattening separators and spaces into the same name.
+  - Ownership and `read_own` checks now resolve metadata from the same isolated path used by uploads, file operations, WebDAV, and background transfer handling.
+  - Simple non-colliding folder metadata filenames remain compatible; existing metadata for collision-prone folders is copied into the isolated filename on first access.
+
+---
+
 ## Changes 06/20/2026 (v3.17.0)
 
 `release(v3.17.0): phpseclib dependency security update`

src/FileRise/Domain/FileModel.php

@@ -5,6 +5,7 @@
 use FileRise\Support\ACL;
 use FileRise\Support\CryptoAtRest;
 use FileRise\Support\FS;
+use FileRise\Support\MetadataPath;
 use FileRise\Support\UploadNamePolicy;
 use FileRise\Support\WorkerLauncher;
 use FileRise\Storage\StorageAdapterInterface;
@@ -65,11 +66,7 @@ private static function metaRootForId(string $sourceId): string
 
     private static function getMetadataFilePathForRoot(string $metaRoot, string $folder): string
     {
-        $metaRoot = rtrim($metaRoot, "/\\") . DIRECTORY_SEPARATOR;
-        if (strtolower($folder) === 'root' || trim($folder) === '') {
-            return $metaRoot . "root_metadata.json";
-        }
-        return $metaRoot . str_replace(['/', '\\', ' '], '-', trim($folder)) . '_metadata.json';
+        return MetadataPath::path($metaRoot, $folder);
     }
 
     private static function trashRoot(): string
@@ -1188,8 +1185,7 @@ public static function renameFile($folder, $oldName, $newName)
         // Perform the rename.
         if ($storage->move($oldPath, $newPath)) {
             // Update the metadata file.
-            $metadataKey = ($folder === 'root') ? "root" : $folder;
-            $metadataFile = self::metaRoot() . str_replace(['/', '\\', ' '], '-', trim($metadataKey)) . '_metadata.json';
+            $metadataFile = self::getMetadataFilePath($folder);
 
             if (file_exists($metadataFile)) {
                 $metadata = json_decode(file_get_contents($metadataFile), true);
@@ -1300,9 +1296,7 @@ public static function saveFile(string $folder, string $fileName, $content, ?str
         }
 
         // Metadata
-        $metadataKey      = strtolower($folder) === "root" ? "root" : $folder;
-        $metadataFileName = str_replace(['/', '\\', ' '], '-', trim($metadataKey)) . '_metadata.json';
-        $metadataFilePath = self::metaRoot() . $metadataFileName;
+        $metadataFilePath = self::getMetadataFilePath($folder);
 
         $metadata = file_exists($metadataFilePath) ? (json_decode(file_get_contents($metadataFilePath), true) ?: []) : [];
 
@@ -3213,12 +3207,7 @@ public static function restoreFiles(array $trashFiles)
         }
 
         // Helper to get metadata file path for a folder.
-        $getMetadataFilePath = function ($folder) {
-            if (strtolower($folder) === 'root' || trim($folder) === '') {
-                return self::metaRoot() . "root_metadata.json";
-            }
-            return self::metaRoot() . str_replace(['/', '\\', ' '], '-', trim($folder)) . '_metadata.json';
-        };
+        $getMetadataFilePath = static fn($folder): string => self::getMetadataFilePath((string)$folder);
 
         // Process each provided trash file name.
         foreach ($trashFiles as $trashFileName) {
@@ -3524,9 +3513,7 @@ public static function saveFileTag(string $folder, string $file, array $tags, bo
         $tags = self::sanitizeTags($tags);
 
         // Determine the folder metadata file.
-        $metadataFile = (strtolower($folder) === "root")
-            ? self::metaRoot() . "root_metadata.json"
-            : self::metaRoot() . str_replace(['/', '\\', ' '], '-', trim($folder)) . '_metadata.json';
+        $metadataFile = self::getMetadataFilePath($folder);
 
         // Load existing metadata for this folder.
         $metadata = [];
@@ -3650,15 +3637,7 @@ public static function getFileList(string $folder, array $options = []): array
             return ["error" => "Invalid folder name."];
         }
 
-        // Helper: Build the metadata file path.
-        $getMetadataFilePath = function (string $folder): string {
-            $metaRoot = self::metaRoot();
-            if (strtolower($folder) === 'root' || trim($folder) === '') {
-                return $metaRoot . "root_metadata.json";
-            }
-            return $metaRoot . str_replace(['/', '\\', ' '], '-', trim($folder)) . '_metadata.json';
-        };
-        $metadataFile = $getMetadataFilePath($folder);
+        $metadataFile = self::getMetadataFilePath($folder);
         $metadata = file_exists($metadataFile) ? (json_decode(file_get_contents($metadataFile), true) ?: []) : [];
 
         $dirStat = $storage->stat($directory);
@@ -4031,9 +4010,7 @@ public static function createFile(string $folder, string $filename, string $uplo
         }
 
         // 5) write metadata
-        $metaKey  = (strtolower($folder) === 'root' || trim($folder) === '') ? 'root' : $folder;
-        $metaName = str_replace(['/', '\\', ' '], '-', $metaKey) . '_metadata.json';
-        $metaPath = self::metaRoot() . $metaName;
+        $metaPath = self::getMetadataFilePath($folder);
 
         $collection = [];
         if (file_exists($metaPath)) {

src/FileRise/Domain/FolderModel.php

@@ -5,6 +5,7 @@
 use FileRise\Support\ACL;
 use FileRise\Support\CryptoAtRest;
 use FileRise\Support\FS;
+use FileRise\Support\MetadataPath;
 use FileRise\Support\UploadNamePolicy;
 use FileRise\Storage\StorageAdapterInterface;
 use FileRise\Storage\SourceContext;
@@ -1492,10 +1493,7 @@ public static function moveFolderAcrossSources(
     /** Build metadata file path for a given (relative) folder. */
     private static function getMetadataFilePath(string $folder): string
     {
-        if (strtolower($folder) === 'root' || trim($folder) === '') {
-            return self::metaRoot() . "root_metadata.json";
-        }
-        return self::metaRoot() . str_replace(['/', '\\', ' '], '-', trim($folder)) . '_metadata.json';
+        return MetadataPath::path(self::metaRoot(), $folder);
     }
 
     /**
@@ -1634,14 +1632,7 @@ public static function deleteFolderRecursiveAdmin(string $folder): array
 
     // Remove metadata JSONs for this subtree
         $relative = trim($relative, "/\\ ");
-        if ($relative !== '' && $relative !== 'root') {
-            $prefix = str_replace(['/', '\\', ' '], '-', $relative);
-            $globPat = self::metaRoot() . $prefix . '*_metadata.json';
-            $metaFiles = glob($globPat) ?: [];
-            foreach ($metaFiles as $mf) {
-                @unlink($mf);
-            }
-        }
+        MetadataPath::deleteSubtree(self::metaRoot(), $relative);
 
     // Remove ownership mappings for the subtree.
         self::removeOwnerForTree($relative);
@@ -1711,14 +1702,7 @@ private static function deleteFolderRecursiveAdminRemote(string $folder): array
 
         // Remove metadata JSONs for this subtree
         $relative = trim($relative, "/\\ ");
-        if ($relative !== '' && $relative !== 'root') {
-            $prefix = str_replace(['/', '\\', ' '], '-', $relative);
-            $globPat = self::metaRoot() . $prefix . '*_metadata.json';
-            $metaFiles = glob($globPat) ?: [];
-            foreach ($metaFiles as $mf) {
-                @unlink($mf);
-            }
-        }
+        MetadataPath::deleteSubtree(self::metaRoot(), $relative);
 
         // Remove ownership mappings for the subtree.
         self::removeOwnerForTree($relative);
@@ -1884,17 +1868,7 @@ public static function renameFolder(string $oldFolder, string $newFolder): array
         }
 
         // Update metadata filenames (prefix-rename)
-        $oldPrefix = str_replace(['/', '\\', ' '], '-', $oldRel);
-        $newPrefix = str_replace(['/', '\\', ' '], '-', $newRel);
-        $globPat   = self::metaRoot() . $oldPrefix . '*_metadata.json';
-        $metadataFiles = glob($globPat) ?: [];
-
-        foreach ($metadataFiles as $oldMetaFile) {
-            $baseName   = basename($oldMetaFile);
-            $newBase    = preg_replace('/^' . preg_quote($oldPrefix, '/') . '/', $newPrefix, $baseName);
-            $newMeta    = self::metaRoot() . $newBase;
-            @rename($oldMetaFile, $newMeta);
-        }
+        MetadataPath::renameSubtree(self::metaRoot(), $oldRel, $newRel);
 
         // Update ownership mapping for the entire subtree.
         self::renameOwnersForTree($oldRel, $newRel);

src/FileRise/Domain/McpCoreOpsService.php

@@ -8,6 +8,7 @@
 use FileRise\Storage\StorageAdapterInterface;
 use FileRise\Storage\StorageRegistry;
 use FileRise\Support\ACL;
+use FileRise\Support\MetadataPath;
 use RuntimeException;
 use Throwable;
 
@@ -2057,13 +2058,7 @@ private static function folderMetadataPath(string $folder): string
             : rtrim((string)META_DIR, '/\\') . DIRECTORY_SEPARATOR;
 
         $folder = ACL::normalizeFolder($folder);
-        if ($folder === 'root') {
-            return rtrim($metaRoot, '/\\') . DIRECTORY_SEPARATOR . 'root_metadata.json';
-        }
-
-        return rtrim($metaRoot, '/\\') . DIRECTORY_SEPARATOR
-            . str_replace(['/', '\\', ' '], '-', $folder)
-            . '_metadata.json';
+        return MetadataPath::path($metaRoot, $folder);
     }
 
     private static function normalizeFolder(string $folder): string