Add single file mount support via hardlink-based isolation

Sources/Containerization/AttachedFilesystem.swift

@@ -16,6 +16,7 @@
 
 import ContainerizationExtras
 import ContainerizationOCI
+import Foundation
 
 /// A filesystem that was attached and able to be mounted inside the runtime environment.
 public struct AttachedFilesystem: Sendable {
@@ -27,12 +28,22 @@ public struct AttachedFilesystem: Sendable {
     public var destination: String
     /// The options to use when mounting the filesystem.
     public var options: [String]
+    /// True if this is a single file mount using hardlink isolation
+    var isFile: Bool
 
     #if os(macOS)
     public init(mount: Mount, allocator: any AddressAllocator<Character>) throws {
+        self.isFile = mount.isFile
+
         switch mount.type {
         case "virtiofs":
-            let name = try hashMountSource(source: mount.source)
+            let shareSource: String
+            if mount.isFile {
+                shareSource = try mount.createIsolatedFileShare()
+            } else {
+                shareSource = mount.source
+            }
+            let name = try hashMountSource(source: shareSource)
             self.source = name
         case "ext4":
             let char = try allocator.allocate()
@@ -42,7 +53,13 @@ public struct AttachedFilesystem: Sendable {
         }
         self.type = mount.type
         self.options = mount.options
-        self.destination = mount.destination
+
+        // For file mounts with hardlink isolation, mount at parent directory
+        if mount.isFile && mount.type == "virtiofs" {
+            self.destination = URL(fileURLWithPath: mount.destination).deletingLastPathComponent().path
+        } else {
+            self.destination = mount.destination
+        }
     }
     #endif
 }

Sources/Containerization/Mount.swift

@@ -132,6 +132,120 @@ public struct Mount: Sendable {
 #if os(macOS)
 
 extension Mount {
+    var isFile: Bool {
+        var isDirectory: ObjCBool = false
+        let exists = FileManager.default.fileExists(atPath: self.source, isDirectory: &isDirectory)
+        return exists && !isDirectory.boolValue
+    }
+
+    var parentDirectory: String {
+        URL(fileURLWithPath: self.source).deletingLastPathComponent().path
+    }
+
+    var filename: String {
+        URL(fileURLWithPath: self.source).lastPathComponent
+    }
+
+    /// Create an isolated temporary directory containing only the target file via hardlink
+    func createIsolatedFileShare() throws -> String {
+        // Create deterministic temp directory
+        let combinedPath = "\(self.source)|\(self.destination)"
+        let sourceHash = try hashMountSource(source: combinedPath)
+        let tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("containerization-file-mount-\(sourceHash)")
+
+        // Use destination filename for the hardlink instead of source filename
+        let destinationFilename = URL(fileURLWithPath: self.destination).lastPathComponent
+        let isolatedFile = tempDir.appendingPathComponent(destinationFilename)
+
+        // Check if hard link already exists
+        if FileManager.default.fileExists(atPath: isolatedFile.path) {
+            // Hard link already exists - nothing to do
+            return tempDir.path
+        }
+
+        // Validate source file exists and is a regular file
+        try validateSourceFile()
+
+        // Atomically create directory
+        try createDirectory(at: tempDir)
+
+        let sourceFile = URL(fileURLWithPath: self.source)
+
+        // Create the hard link, handling race conditions
+        do {
+            try FileManager.default.linkItem(at: sourceFile, to: isolatedFile)
+        } catch CocoaError.fileWriteFileExists {
+            // Another thread created the hardlink - that's fine
+        } catch {
+            throw ContainerizationError(.internalError, message: "Failed to create hardlink: \(error.localizedDescription)")
+        }
+
+        // Final verification that the hardlinked file exists
+        guard FileManager.default.fileExists(atPath: isolatedFile.path) else {
+            throw ContainerizationError(.notFound, message: "Failed to create hardlink at: \(isolatedFile.path)")
+        }
+
+        return tempDir.path
+    }
+
+    /// Release reference to an isolated file share directory
+    /// No-op to avoid race conditions in parallel test execution
+    static func releaseIsolatedFileShare(source: String, destination: String) {
+        // No cleanup during tests to avoid race conditions
+        // OS will clean up temp directories on reboot
+    }
+
+    /// Validate that the source file exists, is readable, and is not a symlink
+    private func validateSourceFile() throws {
+
+        // Check if file exists
+        guard FileManager.default.fileExists(atPath: self.source) else {
+            throw ContainerizationError(.notFound, message: "Source file does not exist: \(self.source)")
+        }
+
+        // Get file attributes to check if it's a regular file
+        let attributes = try FileManager.default.attributesOfItem(atPath: self.source)
+        let fileType = attributes[.type] as? FileAttributeType
+
+        // Reject symlinks to prevent following links to unintended targets
+        guard fileType != .typeSymbolicLink else {
+            throw ContainerizationError(.invalidArgument, message: "Cannot mount symlink: \(self.source)")
+        }
+
+        // Ensure it's a regular file
+        guard fileType == .typeRegular else {
+            throw ContainerizationError(.invalidArgument, message: "Source must be a regular file: \(self.source)")
+        }
+
+        // Check if file is readable
+        guard FileManager.default.isReadableFile(atPath: self.source) else {
+            throw ContainerizationError(.invalidArgument, message: "Source file is not readable: \(self.source)")
+        }
+    }
+
+    /// Atomically create directory (to prevent TOCTOU race conditions)
+    private func createDirectory(at url: URL) throws {
+        do {
+            try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])
+            // Register for cleanup
+            if url.path.contains("containerization-file-mount-") {
+                VZVirtualMachineInstance.registerTempDirectory(url.path)
+            }
+        } catch CocoaError.fileWriteFileExists {
+            // Directory already exists, verify it's actually a directory
+            var isDirectory: ObjCBool = false
+            guard FileManager.default.fileExists(atPath: url.path, isDirectory: &isDirectory),
+                isDirectory.boolValue
+            else {
+                throw ContainerizationError(.invalidArgument, message: "Path exists but is not a directory: \(url.path)")
+            }
+            // Directory exists and is valid, continue
+        } catch {
+            throw ContainerizationError(.internalError, message: "Failed to create directory \(url.path): \(error.localizedDescription)")
+        }
+    }
+
     func configure(config: inout VZVirtualMachineConfiguration) throws {
         switch self.runtimeOptions {
         case .virtioblk(let options):
@@ -140,11 +254,18 @@ extension Mount {
             config.storageDevices.append(attachment)
         case .virtiofs(_):
             guard FileManager.default.fileExists(atPath: self.source) else {
-                throw ContainerizationError(.notFound, message: "directory \(source) does not exist")
+                throw ContainerizationError(.notFound, message: "path \(source) does not exist")
+            }
+
+            let shareSource: String
+            if isFile {
+                shareSource = try createIsolatedFileShare()
+            } else {
+                shareSource = self.source
             }
 
-            let name = try hashMountSource(source: self.source)
-            let urlSource = URL(fileURLWithPath: source)
+            let name = try hashMountSource(source: shareSource)
+            let urlSource = URL(fileURLWithPath: shareSource)
 
             let device = VZVirtioFileSystemDeviceConfiguration(tag: name)
             device.share = VZSingleDirectoryShare(