# ambiguous ReFS writable namespace paths are refused (#421)

* # reject ambiguous ReFS writable namespace paths

Case-insensitive writable lookups selected the first matching row even when a directory contained names distinguished only by case. This could direct replacement, deletion or block clone at an unintended file. Require unique resolution both in the namespace walker and at the mutation entry points, and verify ambiguous synthetic images remain unchanged. The evidence is the existing ReFS row model and synthetic case-collision fixture; no external on-disk grammar is inferred.

* * ReFS ambiguity tests prove the ambiguity check fired

Symptom: the offline-mutation test asserted only NotSupportedException, which
Add also throws for a path it will not create, so the test passed even with
the ambiguity check removed.

Fix: assert the ambiguity message for every refused mutation, cover an
ambiguous clone destination as well as an ambiguous source, and add the
equivalence class of a unique case-folded path that must still resolve.

Author: Hawkynt

Compression.Tests/Refs/RefsAmbiguousNamespaceTests.cs

@@ -0,0 +1,58 @@
+using Compression.Registry;
+using FileSystem.Refs;
+
+namespace Compression.Tests.Refs;
+
+[TestFixture]
+public sealed class RefsAmbiguousNamespaceTests {
+  [Test, Category("ErrorHandling")]
+  public void WritableResolver_RejectsCaseFoldedDuplicateNames() {
+    var image = new RefsSyntheticVolume()
+      .WithFile("alpha.bin", [1, 2, 3])
+      .WithFile("ALPHA.bin", [4, 5, 6])
+      .Build();
+    using var stream = new MemoryStream(image, writable: true);
+
+    var resolver = new RefsWritableNamespace(RefsMetadataReader.Open(stream));
+    Assert.That(() => resolver.ResolveDirectoryEntry("alpha.bin"),
+      Throws.TypeOf<NotSupportedException>().With.Message.Contains("ambiguous"));
+  }
+
+  [Test, Category("ErrorHandling")]
+  public void OfflineMutations_RejectAmbiguousPathBeforeWriting() {
+    var image = new RefsSyntheticVolume()
+      .WithFile("alpha.bin", [1, 2, 3])
+      .WithFile("ALPHA.bin", [4, 5, 6])
+      .WithFile("destination.bin", [7, 8, 9])
+      .Build();
+    var original = image.ToArray();
+    using var stream = new MemoryStream(image, writable: true);
+
+    // Add also refuses a missing path with NotSupportedException, so the
+    // message is what proves the ambiguity check fired rather than that one.
+    static NUnit.Framework.Constraints.IResolveConstraint Ambiguous() => Throws.TypeOf<NotSupportedException>().With.Message.Contains("ambiguous");
+    Assert.Multiple(() => {
+      Assert.That(() => RefsOfflineModifier.Add(
+        stream, [ArchiveInputInfo.InMemory("alpha.bin", [9, 9, 9])]), Ambiguous());
+      Assert.That(() => RefsOfflineModifier.Remove(stream, ["alpha.bin"]), Ambiguous());
+      Assert.That(() => RefsOfflineBlockCloner.CloneWholeFile(
+        stream, "alpha.bin", "destination.bin"), Ambiguous());
+      Assert.That(() => RefsOfflineBlockCloner.CloneWholeFile(
+        stream, "destination.bin", "ALPHA.BIN"), Ambiguous());
+      Assert.That(image, Is.EqualTo(original));
+    });
+  }
+
+  [Test, Category("HappyPath")]
+  public void UniqueCaseFoldedPath_StillResolvesToTheOnlyMatch() {
+    var image = new RefsSyntheticVolume()
+      .WithFile("alpha.bin", [1, 2, 3])
+      .WithFile("beta.bin", [4, 5, 6])
+      .Build();
+    using var stream = new MemoryStream(image, writable: true);
+
+    var location = new RefsWritableNamespace(RefsMetadataReader.Open(stream)).ResolveDirectoryEntry("ALPHA.BIN");
+
+    Assert.That(location.EntryRow.Key.AsSpan(4).ToArray(), Is.EqualTo(System.Text.Encoding.Unicode.GetBytes("alpha.bin")));
+  }
+}

Hawkynt.FileFormats.FileSystems/FileSystems/FileSystem.Refs/RefsNamespaceLookup.cs

@@ -0,0 +1,22 @@
+#pragma warning disable CS1591
+
+namespace FileSystem.Refs;
+
+/// <summary>
+/// A writable path must identify exactly one namespace row. ReFS directories
+/// can contain names that differ only by case, while the offline API resolves
+/// paths case-insensitively; choosing either row would silently edit the wrong
+/// file when the caller did not supply case-sensitive lookup semantics.
+/// </summary>
+internal static class RefsNamespaceLookup {
+  public static RefsFileRecord? FindUnique(IEnumerable<RefsFileRecord> files, string path) {
+    RefsFileRecord? match = null;
+    foreach (var file in files) {
+      if (!string.Equals(file.Path, path, StringComparison.OrdinalIgnoreCase)) continue;
+      if (match != null)
+        throw new NotSupportedException($"ReFS path '{path}' is ambiguous under case-insensitive lookup.");
+      match = file;
+    }
+    return match;
+  }
+}

Hawkynt.FileFormats.FileSystems/FileSystems/FileSystem.Refs/RefsOfflineBlockCloner.cs

@@ -246,7 +246,7 @@ private static RefsFileRecord FindRegularFile(
       IEnumerable<RefsFileRecord> files,
       string path,
       string parameterName) {
-    var file = files.FirstOrDefault(item => string.Equals(item.Path, path, StringComparison.OrdinalIgnoreCase))
+    var file = RefsNamespaceLookup.FindUnique(files, path)
       ?? throw new FileNotFoundException($"ReFS file '{path}' was not found.", path);
     if (file.IsDirectory)
       throw new ArgumentException($"ReFS path '{path}' names a directory.", parameterName);

Hawkynt.FileFormats.FileSystems/FileSystems/FileSystem.Refs/RefsOfflineModifier.cs

@@ -40,9 +40,8 @@ public static void Add(Stream image, IReadOnlyList<ArchiveInputInfo> inputs) {
         throw new ArgumentException("ReFS entry path must not be empty.", nameof(inputs));
 
       var metadata = RefsMetadataReader.Open(image);
-      var existing = new RefsNamespaceReader(metadata).ReadAll().FirstOrDefault(f =>
-        !f.IsDirectory && string.Equals(f.Path, path, StringComparison.OrdinalIgnoreCase));
-      if (existing == null)
+      var existing = RefsNamespaceLookup.FindUnique(new RefsNamespaceReader(metadata).ReadAll(), path);
+      if (existing == null || existing.IsDirectory)
         throw new NotSupportedException(
           $"ReFS offline R/W currently replaces existing regular files; creating the new namespace entry '{path}' " +
           "is withheld until all file-identity/security/link fields are proven for the active ReFS profile.");
@@ -161,9 +160,10 @@ private static void ValidateFilename(string name) {
   private static void ReplaceExisting(Stream image, string path, byte[] data) {
     var metadata = RefsMetadataReader.Open(image);
     var files = new RefsNamespaceReader(metadata).ReadAll();
-    var file = files.FirstOrDefault(f =>
-      !f.IsDirectory && string.Equals(f.Path, path, StringComparison.OrdinalIgnoreCase))
+    var file = RefsNamespaceLookup.FindUnique(files, path)
       ?? throw new FileNotFoundException($"ReFS file '{path}' is no longer reachable.", path);
+    if (file.IsDirectory)
+      throw new InvalidOperationException($"ReFS path '{path}' names a directory, not a writable file.");
     if (file.Extents.Any(e => e.IsSparse || e.Flags == 0x1C00D0 || (e.Flags & 0x04) != 0))
       throw new NotSupportedException(
         $"ReFS file '{path}' uses sparse/integrity/shared allocation semantics outside the offline CRUD profile.");
@@ -250,7 +250,7 @@ private static void ReplaceExisting(Stream image, string path, byte[] data) {
   private static void RemoveOne(Stream image, string path) {
     var metadata = RefsMetadataReader.Open(image);
     var files = new RefsNamespaceReader(metadata).ReadAll();
-    var file = files.FirstOrDefault(f => string.Equals(f.Path, path, StringComparison.OrdinalIgnoreCase))
+    var file = RefsNamespaceLookup.FindUnique(files, path)
       ?? throw new FileNotFoundException($"ReFS entry '{path}' was not found.", path);
 
     if (file.IsDirectory && files.Any(f =>

Hawkynt.FileFormats.FileSystems/FileSystems/FileSystem.Refs/RefsWritableNamespace.cs

@@ -55,8 +55,9 @@ public RefsWritableEntryLocation ResolveDirectoryEntry(string path) {
         if (row.Key.Length < 4 || BinaryPrimitives.ReadUInt16LittleEndian(row.Key) != 0x30) continue;
         var name = DecodeName(row.Key.AsSpan(4));
         if (name.Equals(parts[partIndex], StringComparison.OrdinalIgnoreCase)) {
+          if (match != null)
+            throw new NotSupportedException($"ReFS path '{path}' is ambiguous at '{parts[partIndex]}' under case-insensitive lookup.");
           match = row;
-          break;
         }
       }
       if (match == null)