luajitos

SafeFS.lua (77255B)

---

 -- SafeFS: Sandboxed Filesystem Access
 -- Provides isolated filesystem access with path validation and security
 
 local SafeFS = {}
 SafeFS.__index = SafeFS
 SafeFS.__metatable = false  -- Prevent metatable access/modification
 
 -- Capture C ramdisk functions at module load time (before sandbox restricts access)
 local _CRamdiskList = CRamdiskList
 local _CRamdiskOpen = CRamdiskOpen
 local _CRamdiskRead = CRamdiskRead
 local _CRamdiskWrite = CRamdiskWrite
 local _CRamdiskClose = CRamdiskClose
 local _CRamdiskExists = CRamdiskExists
 local _CRamdiskMkdir = CRamdiskMkdir
 local _CRamdiskRemove = CRamdiskRemove
 
 -- Internal file handler registry (not accessible from sandbox)
 -- Format: { ["txt"] = { appId = "com.luajitos.lunareditor", functionName = "openFile" }, ... }
 -- This table is stored at module level, not on instances, so it persists across SafeFS instances
 -- and cannot be accessed by sandboxed code
 local _fileHandlers = {}
 
 -- Helper: Split path into components
 local function splitPath(path)
     local parts = {}
     for part in string.gmatch(path, "[^/]+") do
         table.insert(parts, part)
     end
     return parts
 end
 
 -- Helper: Join path components
 local function joinPath(parts)
     if #parts == 0 then
         return "/"
     end
     return "/" .. table.concat(parts, "/")
 end
 
 -- Helper: Check if a path is within allowed bounds
 local function isPathAllowed(path, allowedRoots)
     for _, root in ipairs(allowedRoots) do
         -- Check exact match
         if path == root then
             return true
         end
         -- Check if path is under this root
         if path:sub(1, #root + 1) == root .. "/" then
             return true
         end
         -- Check if path is a parent of this root (needed for .. navigation)
         -- For example, if allowed is /apps/com.example/data, we should allow /apps/com.example
         if root:sub(1, #path + 1) == path .. "/" then
             return true
         end
     end
     return false
 end
 
 -- Helper: Normalize path (resolve . and .., but only within SafeFS bounds)
 local function normalizePath(path, allowedRoots)
     -- Remove leading/trailing whitespace
     path = path:match("^%s*(.-)%s*$")
 
     -- Handle empty path
     if path == "" or path == "/" then
         return "/"
     end
 
     -- Ensure path starts with /
     if path:sub(1, 1) ~= "/" then
         path = "/" .. path
     end
 
     local parts = splitPath(path)
     local normalized = {}
 
     for _, part in ipairs(parts) do
         if part == "." then
             -- Skip current directory references
         elseif part == ".." then
             -- Go up one level, but check if parent is allowed
             if #normalized > 0 then
                 -- Build parent path to check if it's allowed
                 local tempNormalized = {}
                 for i = 1, #normalized - 1 do
                     tempNormalized[i] = normalized[i]
                 end
                 local parentPath = joinPath(tempNormalized)
 
                 -- Only go up if parent is allowed
                 if isPathAllowed(parentPath, allowedRoots) then
                     table.remove(normalized)
                 else
                     -- Parent not allowed, ignore the ..
                     -- This prevents escaping the allowed directory tree
                 end
             end
         else
             table.insert(normalized, part)
         end
     end
 
     local result = joinPath(normalized)
 
     -- Verify the normalized path is within allowed bounds
     if not isPathAllowed(result, allowedRoots) then
         return nil, "Path outside allowed directories: " .. result
     end
 
     return result
 end
 
 -- Helper: Check if path matches pattern (supports * wildcard)
 local function matchesPattern(path, pattern)
     -- Handle exact match
     if path == pattern then
         return true
     end
 
     -- Handle wildcard patterns like "/tmp/*"
     if pattern:sub(-2) == "/*" then
         local prefix = pattern:sub(1, -3)
         if path == prefix then
             return true
         end
         if path:sub(1, #prefix + 1) == prefix .. "/" then
             return true
         end
     end
 
     return false
 end
 
 -- Helper: Check if a path would clash with a pseudo file
 local function checkPseudoFileClash(parentDir, filename)
     if not parentDir or not parentDir.files then
         return false, nil
     end
 
     -- Check if there's a pseudo file with this exact name
     for _, file in ipairs(parentDir.files) do
         if file.isPseudo and file.name == filename then
             return true, file
         end
     end
 
     -- Check if filename looks like it has arguments (matches "pseudofile .*")
     local spacePos = filename:find(" ")
     if spacePos then
         local baseName = filename:sub(1, spacePos - 1)
         for _, file in ipairs(parentDir.files) do
             if file.isPseudo and file.name == baseName then
                 return true, file
             end
         end
     end
 
     return false, nil
 end
 
 -- Helper: Check if creating at this path would place something directly in root
 -- Returns true if the path's parent is "/" (the root directory)
 local function isDirectlyInRoot(path)
     if not path or path == "/" then
         return false
     end
 
     local parts = splitPath(path)
     -- If there's only one component (e.g., "/newfile" or "/newdir"),
     -- then parent is root
     return #parts == 1
 end
 
 -- Helper: Deep copy a node and isolate it (remove external references)
 local function deepCopyNode(node, parentNode, allowedPath)
     if not node then
         return nil
     end
 
     local copy = {
         name = node.name,
         type = node.type,
         parent = parentNode  -- Set to new parent, not original
     }
 
     if node.type == "directory" then
         copy.dirs = {}
         copy.files = {}
 
         -- Copy child directories
         if node.dirs then
             for _, dir in ipairs(node.dirs) do
                 local childPath = allowedPath .. "/" .. dir.name
                 local dirCopy = deepCopyNode(dir, copy, childPath)
                 if dirCopy then
                     table.insert(copy.dirs, dirCopy)
                 end
             end
         end
 
         -- Copy child files
         if node.files then
             for _, file in ipairs(node.files) do
                 local fileCopy = {
                     name = file.name,
                     type = "file",
                     parent = copy,
                     content = file.content  -- Reference to content (not copied)
                 }
                 table.insert(copy.files, fileCopy)
             end
         end
     elseif node.type == "file" then
         copy.content = node.content  -- Reference to content
     end
 
     return copy
 end
 
 -- Helper: Find node in tree (for original rootNode traversal)
 local function findNode(rootNode, path)
     -- Check if rootNode has a traverse function (C-based filesystem)
     if type(rootNode) == "table" and type(rootNode.traverse) == "function" then
         -- Use the traverse function
         local node, err = rootNode:traverse(path)
         if not node then
             return nil, err or "Path not found"
         end
         return node
     end
 
     -- Fall back to manual traversal for Lua-based filesystem nodes
     if path == "/" then
         -- Find actual root
         local root = rootNode
         while root.parent do
             root = root.parent
         end
         return root
     end
 
     local parts = splitPath(path)
     local current = rootNode
 
     -- Find root first
     while current.parent do
         current = current.parent
     end
 
     if osprint then
         osprint("[SafeFS.findNode] Starting traversal for path: " .. path .. "\n")
         osprint("[SafeFS.findNode] Path parts: " .. table.concat(parts, ", ") .. "\n")
         osprint("[SafeFS.findNode] Starting at root: " .. tostring(current.name or "/") .. "\n")
     end
 
     -- Traverse path
     for i, part in ipairs(parts) do
         if osprint then
             osprint("[SafeFS.findNode] Step " .. i .. ": Looking for '" .. part .. "' in current node\n")
             osprint("[SafeFS.findNode]   Current node type: " .. tostring(current.type) .. "\n")
             osprint("[SafeFS.findNode]   Current node name: " .. tostring(current.name) .. "\n")
         end
 
         if current.type ~= "directory" then
             if osprint then
                 osprint("[SafeFS.findNode]   ERROR: Current node is not a directory!\n")
             end
             return nil, "Not a directory"
         end
 
         local found = false
 
         -- Check directories
         if current.dirs then
             if osprint then
                 osprint("[SafeFS.findNode]   Checking " .. #current.dirs .. " subdirectories\n")
             end
             for _, dir in ipairs(current.dirs) do
                 -- Strip leading slash from node name for comparison
                 local nodeName = dir.name
                 if nodeName:sub(1, 1) == "/" then
                     nodeName = nodeName:sub(2)
                 end
 
                 if osprint then
                     osprint("[SafeFS.findNode]     - " .. tostring(dir.name) .. " (comparing as: " .. nodeName .. ")\n")
                 end
 
                 if nodeName == part then
                     current = dir
                     found = true
                     if osprint then
                         osprint("[SafeFS.findNode]   FOUND! Moving to: " .. tostring(dir.name) .. "\n")
                     end
                     break
                 end
             end
         end
 
         -- Check files (only for last component)
         if not found and i == #parts and current.files then
             for _, file in ipairs(current.files) do
                 -- Strip leading slash from node name for comparison
                 local fileName = file.name
                 if fileName:sub(1, 1) == "/" then
                     fileName = fileName:sub(2)
                 end
 
                 if fileName == part then
                     return file
                 end
             end
         end
 
         if not found then
             if osprint then
                 osprint("[SafeFS.findNode]   NOT FOUND: Could not find '" .. part .. "'\n")
             end
             return nil, "Path not found: " .. part
         end
     end
 
     if osprint then
         osprint("[SafeFS.findNode] Traversal complete! Reached: " .. tostring(current.name) .. "\n")
     end
 
     return current
 end
 
 -- Helper: Find node in SafeFS isolated tree
 local function findInSafeFS(safeFS, path)
     if osprint then
         osprint("[findInSafeFS] Looking for path: " .. path .. "\n")
         osprint("[findInSafeFS] Available roots:\n")
         for rootPath, rootNode in pairs(safeFS.roots) do
             osprint("  " .. rootPath .. " -> " .. tostring(rootNode) .. "\n")
         end
     end
 
     if path == "/" then
         return nil, "Root directory not accessible"
     end
 
     -- Find which root this path belongs to
     local matchedRoot = nil
     local matchedNode = nil
 
     for rootPath, rootNode in pairs(safeFS.roots) do
         if path == rootPath then
             if osprint then
                 osprint("[findInSafeFS] Exact match! Returning root node for " .. rootPath .. "\n")
             end
             return rootNode
         end
         if path:sub(1, #rootPath + 1) == rootPath .. "/" then
             matchedRoot = rootPath
             matchedNode = rootNode
             if osprint then
                 osprint("[findInSafeFS] Partial match! " .. path .. " starts with " .. rootPath .. "/\n")
             end
             break
         end
     end
 
     if not matchedNode then
         if osprint then
             osprint("[findInSafeFS] No matching root found for " .. path .. "\n")
         end
         return nil, "Path not in SafeFS"
     end
 
     -- Get relative path from root
     local relativePath = path:sub(#matchedRoot + 2)  -- +2 to skip the /
     if relativePath == "" then
         return matchedNode
     end
 
     local parts = splitPath(relativePath)
     local current = matchedNode
 
     for i, part in ipairs(parts) do
         if current.type ~= "directory" then
             return nil, "Not a directory"
         end
 
         local found = false
 
         -- Check directories in node.dirs array
         if current.dirs then
             for _, dir in ipairs(current.dirs) do
                 -- Strip leading slash for comparison
                 local dirName = dir.name
                 if dirName:sub(1, 1) == "/" then
                     dirName = dirName:sub(2)
                 end
                 if dirName == part then
                     -- Check if this is a pseudo directory with onTraverse
                     if dir.isPseudo and dir.onTraverse then
                         -- Build the remaining relative path
                         local remainingParts = {}
                         for j = i + 1, #parts do
                             table.insert(remainingParts, parts[j])
                         end
                         local remainingPath = table.concat(remainingParts, "/")
 
                         -- Call onTraverse with the remaining path
                         local result = dir.onTraverse(remainingPath)
                         if result then
                             -- If there's no remaining path, return the result
                             if remainingPath == "" then
                                 return result
                             end
                             -- Otherwise, onTraverse handled the full traversal
                             return result
                         end
                     end
                     current = dir
                     found = true
                     break
                 end
             end
         end
 
         -- If not found and node.dirs is nil, try _CRamdiskList fallback
         if not found and not current.dirs and _CRamdiskList then
             -- Build the full path up to this point
             local pathSoFar = matchedRoot
             for j = 1, i - 1 do
                 pathSoFar = pathSoFar .. "/" .. parts[j]
             end
 
             if osprint then
                 osprint("[findInSafeFS] Using _CRamdiskList to find '" .. part .. "' in " .. pathSoFar .. "\n")
             end
 
             local items = _CRamdiskList(pathSoFar)
             if items then
                 for _, item in ipairs(items) do
                     -- Strip leading slash from name
                     local itemName = item.name
                     if itemName:sub(1, 1) == "/" then
                         itemName = itemName:sub(2)
                     end
 
                     if itemName == part then
                         if item.type == "directory" or item.type == "dir" then
                             -- For _CRamdiskList results, we need to use traverse to get the actual node
                             local fullPath = pathSoFar .. "/" .. part
                             if osprint then
                                 osprint("[findInSafeFS] Found directory via _CRamdiskList, using traverse for: " .. fullPath .. "\n")
                             end
                             -- Use the global root_fs or safeFS.rootNode to traverse
                             local rootFs = safeFS.rootNode or _G.root_fs
                             if rootFs and rootFs.traverse then
                                 local node, err = rootFs:traverse(fullPath)
                                 if node then
                                     current = node
                                     found = true
                                 else
                                     -- Create a minimal directory node for traversal
                                     current = { name = part, type = "directory", path = fullPath }
                                     found = true
                                 end
                             else
                                 -- Create a minimal directory node for traversal
                                 current = { name = part, type = "directory", path = fullPath }
                                 found = true
                             end
                         elseif i == #parts and (item.type == "file") then
                             -- For files, construct a minimal file node
                             return { name = itemName, type = "file", path = pathSoFar .. "/" .. part }
                         end
                         break
                     end
                 end
             end
         end
 
         -- Check files (only for last component)
         if not found and i == #parts and current.files then
             for _, file in ipairs(current.files) do
                 -- Strip leading slash for comparison
                 local fileName = file.name
                 if fileName:sub(1, 1) == "/" then
                     fileName = fileName:sub(2)
                 end
                 if fileName == part then
                     return file
                 end
             end
         end
 
         if not found then
             if osprint then
                 osprint("[findInSafeFS] Could not find '" .. part .. "' in current node\n")
             end
             return nil, "Path not found: " .. part
         end
     end
 
     return current
 end
 
 -- Helper: Ensure directory exists in SafeFS
 local function ensureDirectory(safeFS, path)
     local parts = splitPath(path)
 
     -- Find which root this belongs to
     local matchedRoot = nil
     local matchedNode = nil
 
     for rootPath, rootNode in pairs(safeFS.roots) do
         if path == rootPath or path:sub(1, #rootPath + 1) == rootPath .. "/" then
             matchedRoot = rootPath
             matchedNode = rootNode
             break
         end
     end
 
     if not matchedNode then
         return nil, "Path not in SafeFS"
     end
 
     -- Get relative path
     local relativePath = path:sub(#matchedRoot + 2)
     if relativePath == "" or relativePath == "/" then
         return matchedNode
     end
 
     local relParts = splitPath(relativePath)
     local current = matchedNode
 
     for _, part in ipairs(relParts) do
         if current.type ~= "directory" then
             return nil, "Not a directory"
         end
 
         -- Look for existing directory
         local found = false
         if current.dirs then
             for _, dir in ipairs(current.dirs) do
                 if dir.name == part then
                     current = dir
                     found = true
                     break
                 end
             end
         end
 
         -- Create if not found
         if not found then
             if not current.dirs then
                 current.dirs = {}
             end
 
             local newDir = {
                 name = part,
                 type = "directory",
                 parent = current,
                 dirs = {},
                 files = {}
             }
             table.insert(current.dirs, newDir)
             current = newDir
         end
     end
 
     return current
 end
 
 -- Internal registry for SafeFS privileged functions (stored in _G, not exposed to sandbox)
 -- Key is the SafeFS instance, value is a table of internal functions
 if not _G._safefsInternal then
     _G._safefsInternal = setmetatable({}, {__mode = "k"})  -- Weak keys so instances can be GC'd
 end
 
 -- Dynamically add an allowed path to a SafeFS instance
 -- This is stored in _G._safefsInternal, not on the instance itself, so sandbox can't access it
 local function _addAllowedPath(self, path)
     if not path or type(path) ~= "string" then
         return false, "Invalid path"
     end
 
     -- Handle wildcard suffix
     local isWildcard = path:sub(-2) == "/*"
     local cleanPath = isWildcard and path:sub(1, -3) or path
 
     -- Remove trailing slash if present
     if cleanPath ~= "/" and cleanPath:sub(-1) == "/" then
         cleanPath = cleanPath:sub(1, -2)
     end
 
     -- Check if already allowed
     if self.roots[cleanPath] then
         return true, "Already allowed"
     end
 
     -- For diskfs paths, create a PseudoDir mount if needed
     local isDiskFS = cleanPath:match("^/mnt/hd%d")
     if isDiskFS and self.createDiskFSMount then
         -- Extract bus/drive from path like /mnt/hd0
         local hdNum = tonumber(cleanPath:match("^/mnt/hd(%d)"))
         if hdNum then
             -- Try to mount the disk
             local mountPath = "/mnt/hd" .. hdNum
             if not self.roots[mountPath] then
                 local pseudoDir, err = self:createDiskFSMount(mountPath, 0, hdNum)
                 if pseudoDir then
                     if osprint then
                         osprint("[SafeFS] Dynamically mounted disk at " .. mountPath .. "\n")
                     end
                     return true
                 else
                     if osprint then
                         osprint("[SafeFS] Failed to mount disk: " .. tostring(err) .. "\n")
                     end
                 end
             else
                 return true, "Disk already mounted"
             end
         end
     end
 
     -- Try to find the node in the root filesystem
     local node, err = findNode(self.rootNode, cleanPath)
     if node and node.type == "directory" then
         self.roots[cleanPath] = node
         table.insert(self.allowedRoots, cleanPath)
         table.insert(self.allowedDirs, path)
         if osprint then
             osprint("[SafeFS] Dynamically added allowed path: " .. cleanPath .. "\n")
         end
         return true
     end
 
     return false, err or "Path not found"
 end
 
 -- Create a new SafeFS instance
 -- rootNode: The root filesystem node
 -- allowedDirs: List of directory patterns (e.g., {"/tmp/*", "/apps/com.dev.app/data/*"})
 -- currentUser: Optional username for ~ expansion (default: "root")
 -- appId: Optional app identifier for file handler registration and $ expansion (e.g., "com.luajitos.lunareditor")
 -- appPath: Optional app path for $ expansion (e.g., "/apps/com.luajitos.lunareditor")
 -- Returns: SafeFS instance, or nil and error message on failure
 function SafeFS.new(rootNode, allowedDirs, currentUser, appId, appPath)
     if osprint then osprint("SafeFS.new: ENTERED\n") end
 
     if not rootNode then
         if osprint then osprint("SafeFS.new: rootNode is nil, returning error\n") end
         return nil, "rootNode is required"
     end
 
     if osprint then osprint("SafeFS.new: Creating self object\n") end
     local self = setmetatable({}, SafeFS)
     if osprint then osprint("SafeFS.new: Self created\n") end
 
     self.rootNode = rootNode
     self.allowedDirs = allowedDirs or {}
     self.currentUser = currentUser or "root"
     self._appId = appId  -- Store app ID for file handler registration (internal, not exposed)
     self._appPath = appPath or (appId and ("/apps/" .. appId) or nil)  -- App path for $ expansion
     self.cwd = "/"  -- Current working directory
     self.roots = {}  -- Isolated root nodes for each allowed directory
     self.allowedRoots = {}  -- List of root paths for validation
 
     -- Automatically add $/data/* access if appPath is set
     if self._appPath then
         local dataPath = self._appPath .. "/data/*"
         local hasDataPath = false
         for _, pattern in ipairs(self.allowedDirs) do
             if pattern == dataPath or pattern == self._appPath .. "/data" then
                 hasDataPath = true
                 break
             end
         end
         if not hasDataPath then
             table.insert(self.allowedDirs, dataPath)
             if osprint then osprint("SafeFS.new: Auto-added $/data/* access: " .. dataPath .. "\n") end
         end
     end
 
     if osprint then osprint("SafeFS.new: Processing allowed directories (" .. #self.allowedDirs .. " patterns)\n") end
 
     -- Helper to add a path to roots
     local function addRoot(cleanPath)
         -- Check if already added
         if self.roots[cleanPath] then
             return true
         end
 
         local node, err = findNode(rootNode, cleanPath)
         if node and node.type == "directory" then
             self.roots[cleanPath] = node
             table.insert(self.allowedRoots, cleanPath)
             if osprint then osprint("SafeFS: Added allowed root: " .. cleanPath .. "\n") end
             return true
         end
         return false
     end
 
     -- Process allowed directories and create isolated trees
     local foundAtLeastOne = false
     for i, pattern in ipairs(self.allowedDirs) do
         if osprint then osprint("SafeFS.new: Processing pattern " .. i .. ": " .. pattern .. "\n") end
 
         -- Check if pattern ends with /* (wildcard)
         local isWildcard = pattern:sub(-2) == "/*"
 
         -- Remove /* suffix if present
         local cleanPath = pattern
         if isWildcard then
             cleanPath = cleanPath:sub(1, -3)
         end
 
         -- Handle ~ expansion
         if cleanPath:sub(1, 2) == "~/" then
             cleanPath = "/home/" .. self.currentUser .. cleanPath:sub(2)
         elseif cleanPath == "~" then
             cleanPath = "/home/" .. self.currentUser
         end
 
         -- Handle $ expansion
         if self._appPath then
             if cleanPath:sub(1, 2) == "$/" then
                 cleanPath = self._appPath .. cleanPath:sub(2)
             elseif cleanPath == "$" then
                 cleanPath = self._appPath
             end
         end
 
         -- Find node in original filesystem
         if osprint then osprint("SafeFS.new: Finding node for: " .. cleanPath .. "\n") end
 
         if addRoot(cleanPath) then
             foundAtLeastOne = true
         else
             if osprint then osprint("SafeFS: Failed to find directory: " .. cleanPath .. "\n") end
         end
     end
 
     -- Return error if no allowed directories were found
     if not foundAtLeastOne and #self.allowedDirs > 0 then
         return nil, "No allowed directories found"
     end
 
     -- Register internal functions for this instance (accessible via _G._safefsInternal)
     _G._safefsInternal[self] = {
         addAllowedPath = function(path) return _addAllowedPath(self, path) end
     }
 
     return self
 end
 
 -- Resolve path with ~, $ expansion and CWD support
 function SafeFS:resolvePath(path)
     -- Handle ~ expansion (home directory)
     if path:sub(1, 2) == "~/" then
         path = "/home/" .. self.currentUser .. path:sub(2)
     elseif path == "~" then
         path = "/home/" .. self.currentUser
     end
 
     -- Handle $ expansion (app directory)
     if self._appPath then
         if path:sub(1, 2) == "$/" then
             path = self._appPath .. path:sub(2)
         elseif path == "$" then
             path = self._appPath
         end
     end
 
     -- Handle relative paths (paths that don't start with /)
     if path:sub(1, 1) ~= "/" then
         -- Make path relative to CWD
         local cwd = self.cwd or "/"
         -- Ensure CWD ends without trailing slash for joining
         if cwd ~= "/" and cwd:sub(-1) == "/" then
             cwd = cwd:sub(1, -2)
         end
         -- Join CWD and relative path
         if cwd == "/" then
             path = "/" .. path
         else
             path = cwd .. "/" .. path
         end
     end
 
     -- Normalize path
     return normalizePath(path, self.allowedRoots)
 end
 
 -- Get current working directory
 function SafeFS:getCWD()
     return self.cwd
 end
 
 -- Set current working directory
 function SafeFS:setCWD(path)
     -- Resolve the path first (this already validates against allowed roots)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return false, err
     end
 
     -- Additional check: ensure the resolved path is actually allowed
     -- This catches edge cases where path resolution might succeed but access shouldn't
     local pathAllowed = false
     for _, root in ipairs(self.allowedRoots) do
         if resolvedPath == root or resolvedPath:sub(1, #root + 1) == root .. "/" then
             pathAllowed = true
             break
         end
         -- Also allow parent directories if they contain an allowed root
         if root:sub(1, #resolvedPath + 1) == resolvedPath .. "/" then
             pathAllowed = true
             break
         end
     end
 
     if not pathAllowed then
         return false, "Path not in allowed directories"
     end
 
     -- Check if path exists and is a directory
     local node, err = findInSafeFS(self, resolvedPath)
     if not node then
         return false, err or "Directory not found"
     end
 
     if node.type ~= "directory" then
         return false, "Not a directory"
     end
 
     -- Set the CWD
     self.cwd = resolvedPath
     return true
 end
 
 -- Read file contents
 function SafeFS:read(path)
     -- Check if path contains arguments (space after filename)
     local filePath = path
     local args = nil
     local spacePos = path:find(" ")
 
     if spacePos then
         filePath = path:sub(1, spacePos - 1)
         args = path:sub(spacePos + 1)
     end
 
     local resolvedPath, err = self:resolvePath(filePath)
     if not resolvedPath then
         return nil, err
     end
 
     local node, err = findInSafeFS(self, resolvedPath)
     if not node then
         return nil, err or "File not found"
     end
 
     if node.type ~= "file" then
         return nil, "Not a file"
     end
 
     -- Handle pseudo files with onRead callback
     if node.isPseudo then
         if node.onRead then
             -- Pass arguments to onRead if present
             if args then
                 return node.onRead(args)
             else
                 return node.onRead()
             end
         else
             return nil, "Pseudo file has no onRead callback"
         end
     end
 
     -- If node has content, return it
     if node.content then
         return node.content
     end
 
     -- If node has a path but no content, read from CRamdisk
     if node.path and _CRamdiskOpen and _CRamdiskRead and _CRamdiskClose then
         local handle = _CRamdiskOpen(node.path, "r")
         if handle then
             local content = _CRamdiskRead(handle)
             _CRamdiskClose(handle)
             return content
         else
             return nil, "Failed to open file: " .. node.path
         end
     end
 
     -- Try to read using the resolved path directly
     if _CRamdiskOpen and _CRamdiskRead and _CRamdiskClose then
         local handle = _CRamdiskOpen(resolvedPath, "r")
         if handle then
             local content = _CRamdiskRead(handle)
             _CRamdiskClose(handle)
             return content
         end
     end
 
     return nil, "File has no content"
 end
 
 -- Write file contents (creates file if it doesn't exist)
 function SafeFS:write(path, content)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return false, err
     end
 
     -- Protect root directory - cannot create files directly in root
     if isDirectlyInRoot(resolvedPath) then
         return false, "Cannot create files in root directory"
     end
 
     -- Split path into directory and filename
     local parts = splitPath(resolvedPath)
     local filename = parts[#parts]
     table.remove(parts)
     local dirPath = joinPath(parts)
 
     -- Ensure parent directory exists
     local parentDir, err = ensureDirectory(self, dirPath)
     if not parentDir then
         return false, err or "Parent directory not found"
     end
 
     -- Look for existing file
     if parentDir.files then
         for _, file in ipairs(parentDir.files) do
             if file.name == filename then
                 -- Handle pseudo files with onWrite callback
                 if file.isPseudo then
                     if file.onWrite then
                         file.onWrite(content)
                         return true
                     else
                         return false, "Pseudo file has no onWrite callback"
                     end
                 end
 
                 -- Update existing file
                 file.content = content
                 -- Also update in C ramdisk
                 if _CRamdiskOpen and _CRamdiskWrite and _CRamdiskClose then
                     local handle = _CRamdiskOpen(resolvedPath, "w")
                     if handle then
                         _CRamdiskWrite(handle, content)
                         _CRamdiskClose(handle)
                     end
                 end
                 return true
             end
         end
     end
 
     -- Check if creating this file would clash with a pseudo file
     local clashes, pseudoFile = checkPseudoFileClash(parentDir, filename)
     if clashes then
         return false, "Cannot create file: would clash with pseudo file '" .. pseudoFile.name .. "'"
     end
 
     -- Create new file in SafeFS tree
     if not parentDir.files then
         parentDir.files = {}
     end
 
     local newFile = {
         name = filename,
         type = "file",
         parent = parentDir,
         content = content
     }
     table.insert(parentDir.files, newFile)
 
     -- Also write to C ramdisk so other apps can see it
     if _CRamdiskOpen and _CRamdiskWrite and _CRamdiskClose then
         local handle, err = _CRamdiskOpen(resolvedPath, "w")
         if handle then
             _CRamdiskWrite(handle, content)
             _CRamdiskClose(handle)
             if osprint then
                 osprint("[SafeFS] Wrote to C ramdisk: " .. resolvedPath .. "\n")
             end
         else
             if osprint then
                 osprint("[SafeFS] Failed to open for write: " .. resolvedPath .. " err=" .. tostring(err) .. "\n")
             end
         end
     end
 
     return true
 end
 
 -- Create a default pseudo file handle with read/write/seek/close methods
 -- This is returned when onOpen is not set on a pseudo file
 local function createDefaultPseudoHandle(pseudoFile, path, mode)
     local handle = {
         _pseudoFile = pseudoFile,
         _path = path,
         _mode = mode,
         _content = "",
         _pos = 1,
         _size = 0
     }
 
     -- Initialize content for read modes
     if mode == "r" or mode == "r+" then
         if pseudoFile.onRead then
             handle._content = pseudoFile.onRead() or ""
         end
         handle._size = #handle._content
     elseif mode == "a" or mode == "a+" then
         -- Append mode - get existing content first
         if pseudoFile.onRead then
             handle._content = pseudoFile.onRead() or ""
         end
         handle._pos = #handle._content + 1
         handle._size = #handle._content
     else
         -- Write mode - start empty
         handle._content = ""
         handle._size = 0
     end
 
     function handle:read(format)
         if self._mode == "w" or self._mode == "a" then
             return nil, "Cannot read in write-only mode"
         end
 
         format = format or "*l"
 
         if format == "*a" or format == "*all" then
             local result = self._content:sub(self._pos)
             self._pos = #self._content + 1
             return result
         elseif format == "*l" or format == "*line" then
             local start = self._pos
             local lineEnd = self._content:find("\n", start, true)
             if lineEnd then
                 local line = self._content:sub(start, lineEnd - 1)
                 self._pos = lineEnd + 1
                 return line
             else
                 if self._pos <= #self._content then
                     local line = self._content:sub(start)
                     self._pos = #self._content + 1
                     return line
                 else
                     return nil
                 end
             end
         elseif type(format) == "number" then
             if self._pos > #self._content then
                 return nil
             end
             local result = self._content:sub(self._pos, self._pos + format - 1)
             self._pos = self._pos + format
             return result
         end
     end
 
     function handle:write(data)
         if self._mode == "r" then
             return nil, "Cannot write in read-only mode"
         end
 
         data = tostring(data)
 
         if self._mode == "a" or self._mode == "a+" then
             -- Append mode - always add to end
             self._content = self._content .. data
             self._pos = #self._content + 1
         else
             -- Write mode or r+ - insert at current position
             local before = self._content:sub(1, self._pos - 1)
             local after = self._content:sub(self._pos + #data)
             self._content = before .. data .. after
             self._pos = self._pos + #data
         end
 
         self._size = #self._content
         return true
     end
 
     function handle:seek(whence, offset)
         whence = whence or "cur"
         offset = offset or 0
 
         local newPos
         if whence == "set" then
             newPos = offset + 1
         elseif whence == "cur" then
             newPos = self._pos + offset
         elseif whence == "end" then
             newPos = #self._content + offset + 1
         else
             return nil, "Invalid whence: " .. tostring(whence)
         end
 
         if newPos < 1 then
             newPos = 1
         end
 
         self._pos = newPos
         return self._pos - 1  -- Return 0-based position like Lua's file:seek()
     end
 
     function handle:close()
         -- Write content back via onWrite callback
         if self._mode ~= "r" and self._pseudoFile.onWrite then
             self._pseudoFile.onWrite(self._content)
         end
         return true
     end
 
     function handle:flush()
         -- Flush current content via onWrite
         if self._mode ~= "r" and self._pseudoFile.onWrite then
             self._pseudoFile.onWrite(self._content)
         end
         return true
     end
 
     function handle:lines()
         return function()
             return self:read("*l")
         end
     end
 
     return handle
 end
 
 -- Open file (returns file handle-like table)
 function SafeFS:open(path, mode)
     mode = mode or "r"
 
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     -- Protect root directory for write modes
     if (mode == "w" or mode == "a") and isDirectlyInRoot(resolvedPath) then
         return nil, "Cannot create files in root directory"
     end
 
     -- Check if this is a pseudo file
     local parts = splitPath(resolvedPath)
     local filename = parts[#parts]
     table.remove(parts)
     local parentPath = joinPath(parts)
 
     local parentNode, parentErr = findInSafeFS(self, parentPath)
     if parentNode and parentNode.files then
         for _, file in ipairs(parentNode.files) do
             if file.name == filename and file.isPseudo then
                 -- Found a pseudo file
                 if file.onOpen then
                     -- Custom onOpen handler
                     return file.onOpen(resolvedPath, mode)
                 else
                     -- Default pseudo file handle
                     return createDefaultPseudoHandle(file, resolvedPath, mode)
                 end
             end
         end
     end
 
     -- Regular file handling
     if mode == "r" then
         -- Read mode
         local content, err = self:read(resolvedPath)
         if not content then
             return nil, err
         end
 
         local handle = {
             _content = content,
             _pos = 1,
             _path = resolvedPath,
             _safeFS = self
         }
 
         function handle:read(format)
             format = format or "*l"
 
             if format == "*a" or format == "*all" then
                 local result = self._content:sub(self._pos)
                 self._pos = #self._content + 1
                 return result
             elseif format == "*l" or format == "*line" then
                 local start = self._pos
                 local lineEnd = self._content:find("\n", start, true)
                 if lineEnd then
                     local line = self._content:sub(start, lineEnd - 1)
                     self._pos = lineEnd + 1
                     return line
                 else
                     if self._pos <= #self._content then
                         local line = self._content:sub(start)
                         self._pos = #self._content + 1
                         return line
                     else
                         return nil
                     end
                 end
             elseif type(format) == "number" then
                 local result = self._content:sub(self._pos, self._pos + format - 1)
                 self._pos = self._pos + format
                 return result
             end
         end
 
         function handle:seek(whence, offset)
             whence = whence or "cur"
             offset = offset or 0
 
             local newPos
             if whence == "set" then
                 newPos = offset + 1
             elseif whence == "cur" then
                 newPos = self._pos + offset
             elseif whence == "end" then
                 newPos = #self._content + offset + 1
             else
                 return nil, "Invalid whence"
             end
 
             if newPos < 1 then newPos = 1 end
             self._pos = newPos
             return self._pos - 1
         end
 
         function handle:close()
             -- Nothing to do for read mode
         end
 
         return handle
 
     elseif mode == "w" or mode == "a" then
         -- Write or append mode
         local existingContent = ""
         if mode == "a" then
             existingContent = self:read(resolvedPath) or ""
         end
 
         local handle = {
             _content = existingContent,
             _pos = #existingContent + 1,
             _path = resolvedPath,
             _safeFS = self
         }
 
         function handle:write(data)
             self._content = self._content .. tostring(data)
             self._pos = #self._content + 1
             return true
         end
 
         function handle:seek(whence, offset)
             whence = whence or "cur"
             offset = offset or 0
 
             local newPos
             if whence == "set" then
                 newPos = offset + 1
             elseif whence == "cur" then
                 newPos = self._pos + offset
             elseif whence == "end" then
                 newPos = #self._content + offset + 1
             else
                 return nil, "Invalid whence"
             end
 
             if newPos < 1 then newPos = 1 end
             self._pos = newPos
             return self._pos - 1
         end
 
         function handle:close()
             self._safeFS:write(self._path, self._content)
         end
 
         return handle
     else
         return nil, "Invalid mode: " .. mode
     end
 end
 
 -- Delete file or directory
 function SafeFS:delete(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return false, err
     end
 
     -- Find parent directory
     local parts = splitPath(resolvedPath)
     local targetName = parts[#parts]
     table.remove(parts)
     local parentPath = joinPath(parts)
 
     local parentNode, err = findInSafeFS(self, parentPath)
     if not parentNode then
         return false, err or "Parent directory not found"
     end
 
     if parentNode.type ~= "directory" then
         return false, "Parent is not a directory"
     end
 
     -- Remove from directories
     if parentNode.dirs then
         for i, dir in ipairs(parentNode.dirs) do
             if dir.name == targetName then
                 table.remove(parentNode.dirs, i)
                 return true
             end
         end
     end
 
     -- Remove from files
     if parentNode.files then
         for i, file in ipairs(parentNode.files) do
             if file.name == targetName then
                 -- Call onDelete callback for pseudo files
                 if file.isPseudo and file.onDelete then
                     local success, err = pcall(file.onDelete, file)
                     if not success then
                         return false, "onDelete callback error: " .. tostring(err)
                     end
                 end
 
                 table.remove(parentNode.files, i)
                 return true
             end
         end
     end
 
     return false, "Not found"
 end
 
 -- List directories in path
 function SafeFS:dirs(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     local node, err = findInSafeFS(self, resolvedPath)
     if not node then
         return nil, err or "Path not found"
     end
 
     if node.type ~= "directory" then
         return nil, "Not a directory"
     end
 
     -- Refresh pseudo directory contents from callbacks
     if node.isPseudo and node.refresh then
         node:refresh()
     end
 
     if osprint then
         osprint("[SafeFS.dirs] Node found for path: " .. resolvedPath .. "\n")
         osprint("[SafeFS.dirs] Node keys:\n")
         for k,v in pairs(node) do
             osprint("  " .. k .. " = " .. tostring(v) .. "\n")
         end
         if node.dirs then
             osprint("[SafeFS.dirs] node.dirs has " .. #node.dirs .. " entries\n")
             for i, dir in ipairs(node.dirs) do
                 osprint("  [" .. i .. "] name=" .. tostring(dir.name) .. " type=" .. tostring(dir.type) .. "\n")
             end
         else
             osprint("[SafeFS.dirs] node.dirs is nil\n")
         end
     end
 
     local result = {}
 
     -- If node doesn't have dirs array, use _CRamdiskList to get them
     if not node.dirs and _CRamdiskList then
         if osprint then
             osprint("[SafeFS.dirs] node.dirs is nil, using _CRamdiskList(" .. resolvedPath .. ")\n")
         end
 
         local items = _CRamdiskList(resolvedPath)
         if items then
             for _, item in ipairs(items) do
                 if item.type == "directory" or item.type == "dir" then
                     -- Strip leading slash from name if present
                     local itemName = item.name
                     if itemName:sub(1, 1) == "/" then
                         itemName = itemName:sub(2)
                     end
                     table.insert(result, itemName)
                 end
             end
         end
     elseif node.dirs then
         for _, dir in ipairs(node.dirs) do
             -- Strip leading slash from name if present
             local dirName = dir.name
             if dirName:sub(1, 1) == "/" then
                 dirName = dirName:sub(2)
             end
             table.insert(result, dirName)
         end
     end
 
     return result
 end
 
 -- List files in path
 function SafeFS:files(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     if osprint then
         osprint("[SafeFS.files] Looking for files in path: " .. resolvedPath .. "\n")
     end
 
     local node, err = findInSafeFS(self, resolvedPath)
     if not node then
         if osprint then
             osprint("[SafeFS.files] Node not found: " .. tostring(err) .. "\n")
         end
         return nil, err or "Path not found"
     end
 
     if node.type ~= "directory" then
         return nil, "Not a directory"
     end
 
     -- Refresh pseudo directory contents from callbacks
     if node.isPseudo and node.refresh then
         node:refresh()
     end
 
     if osprint then
         osprint("[SafeFS.files] Node found, node.files=" .. tostring(node.files) .. "\n")
         osprint("[SafeFS.files] _CRamdiskList available: " .. tostring(_CRamdiskList ~= nil) .. "\n")
     end
 
     local result = {}
 
     -- If node doesn't have files array, use _CRamdiskList to get them
     if not node.files and _CRamdiskList then
         if osprint then
             osprint("[SafeFS.files] Using _CRamdiskList fallback for: " .. resolvedPath .. "\n")
         end
         local items = _CRamdiskList(resolvedPath)
         if items then
             if osprint then
                 osprint("[SafeFS.files] _CRamdiskList returned " .. #items .. " items\n")
             end
             for _, item in ipairs(items) do
                 if osprint then
                     osprint("[SafeFS.files]   Item: name=" .. tostring(item.name) .. " type=" .. tostring(item.type) .. "\n")
                 end
                 if item.type == "file" then
                     -- Strip leading slash from name if present
                     local itemName = item.name
                     if itemName:sub(1, 1) == "/" then
                         itemName = itemName:sub(2)
                     end
                     table.insert(result, itemName)
                     if osprint then
                         osprint("[SafeFS.files]   Added file: " .. itemName .. "\n")
                     end
                 end
             end
         else
             if osprint then
                 osprint("[SafeFS.files] _CRamdiskList returned nil\n")
             end
         end
     elseif node.files then
         if osprint then
             osprint("[SafeFS.files] Using node.files array (" .. #node.files .. " files)\n")
         end
         for _, file in ipairs(node.files) do
             -- Strip leading slash from name if present
             local fileName = file.name
             if fileName:sub(1, 1) == "/" then
                 fileName = fileName:sub(2)
             end
             table.insert(result, fileName)
         end
     end
 
     if osprint then
         osprint("[SafeFS.files] Returning " .. #result .. " files\n")
     end
 
     return result
 end
 
 -- Check if path exists
 function SafeFS:exists(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return false
     end
 
     local node = findInSafeFS(self, resolvedPath)
     return node ~= nil
 end
 
 -- Get path type ("file", "directory", or nil)
 function SafeFS:getType(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     local node = findInSafeFS(self, resolvedPath)
     if not node then
         return nil
     end
 
     return node.type
 end
 
 -- Create directory
 function SafeFS:mkdir(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return false, err
     end
 
     -- Protect root directory - cannot create directories directly in root
     if isDirectlyInRoot(resolvedPath) then
         return false, "Cannot create directories in root directory"
     end
 
     local node, err = ensureDirectory(self, resolvedPath)
     if not node then
         return false, err
     end
 
     return true
 end
 
 -- Get the filename (last component) from a path
 function SafeFS:fileName(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     -- Handle root case
     if resolvedPath == "/" then
         return "/"
     end
 
     -- Split path and get last component
     local parts = splitPath(resolvedPath)
     if #parts == 0 then
         return "/"
     end
 
     return parts[#parts]
 end
 
 -- Get the parent directory path
 function SafeFS:parentDir(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     -- Root has no parent
     if resolvedPath == "/" then
         return nil, "Root has no parent"
     end
 
     -- Split path and remove last component
     local parts = splitPath(resolvedPath)
     if #parts <= 1 then
         return "/"
     end
 
     table.remove(parts)
     return joinPath(parts)
 end
 
 -- Join multiple path segments without validation
 -- Example: join("/folder", "subfolder/test.txt") -> "/folder/subfolder/test.txt"
 -- Example: join("/apps", "com.luajit.calculator", "/data/", "/test.txt") -> "/apps/com.luajit.calculator/data/test.txt"
 function SafeFS:join(...)
     local segments = {...}
     if #segments == 0 then
         return ""
     end
 
     local result = ""
 
     for i, segment in ipairs(segments) do
         if segment and segment ~= "" then
             -- Remove leading slashes from all segments except the first
             if i > 1 and segment:sub(1, 1) == "/" then
                 segment = segment:sub(2)
             end
 
             -- Remove trailing slashes from all segments
             while segment:sub(-1) == "/" and #segment > 1 do
                 segment = segment:sub(1, -2)
             end
 
             -- Add segment to result
             if result == "" then
                 result = segment
             elseif result == "/" then
                 result = "/" .. segment
             else
                 result = result .. "/" .. segment
             end
         end
     end
 
     return result
 end
 
 -- Get relative path from base to target without validation
 -- Example: relativeTo("/Program Files", "/Program Files/Microsoft") -> "Microsoft"
 -- Example: relativeTo("/apps/test", "/apps/test/data/file.txt") -> "data/file.txt"
 function SafeFS:relativeTo(base, target)
     -- Normalize paths by removing trailing slashes
     if base:sub(-1) == "/" and #base > 1 then
         base = base:sub(1, -2)
     end
     if target:sub(-1) == "/" and #target > 1 then
         target = target:sub(1, -2)
     end
 
     -- Check if target starts with base
     if target:sub(1, #base) == base then
         -- If they're exactly equal, return empty string
         if #target == #base then
             return ""
         end
 
         -- Check that the next character is a slash (to avoid partial matches)
         if target:sub(#base + 1, #base + 1) == "/" then
             return target:sub(#base + 2)  -- Skip the slash
         end
     end
 
     -- If target doesn't start with base, return the full target
     return target
 end
 
 -- Copy a file or directory from source to destination
 function SafeFS:copy(source, destination)
     local sourceResolved, err = self:resolvePath(source)
     if not sourceResolved then
         return nil, err
     end
 
     local destResolved, err = self:resolvePath(destination)
     if not destResolved then
         return nil, err
     end
 
     -- Protect root directory - cannot copy to root
     if isDirectlyInRoot(destResolved) then
         return nil, "Cannot copy to root directory"
     end
 
     -- Check if source exists
     local sourceNode = self.root:traverse(sourceResolved)
     if not sourceNode then
         return nil, "Source does not exist: " .. source
     end
 
     -- Check source type
     local sourceType = sourceNode.type
     if sourceType ~= "file" and sourceType ~= "dir" then
         return nil, "Invalid source type"
     end
 
     -- Helper function to recursively copy directory
     local function copyDir(srcNode, destPath)
         -- Create destination directory
         local success, err = self:mkdir(destPath)
         if not success then
             return nil, err
         end
 
         -- Copy all files in the directory
         for _, file in ipairs(srcNode.files) do
             local srcFilePath = self:join(sourceResolved, file.name)
             local destFilePath = self:join(destPath, file.name)
             local content, err = self:read(srcFilePath)
             if not content then
                 return nil, "Failed to read " .. srcFilePath .. ": " .. (err or "unknown error")
             end
             local success, err = self:write(destFilePath, content)
             if not success then
                 return nil, "Failed to write " .. destFilePath .. ": " .. (err or "unknown error")
             end
         end
 
         -- Recursively copy subdirectories
         for _, dir in ipairs(srcNode.dirs) do
             local srcDirPath = self:join(sourceResolved, dir.name)
             local destDirPath = self:join(destPath, dir.name)
             local success, err = copyDir(dir, destDirPath)
             if not success then
                 return nil, err
             end
         end
 
         return true
     end
 
     -- Copy based on type
     if sourceType == "file" then
         -- Copy file
         local content, err = self:read(sourceResolved)
         if not content then
             return nil, "Failed to read source: " .. (err or "unknown error")
         end
         return self:write(destResolved, content)
     else
         -- Copy directory
         return copyDir(sourceNode, destResolved)
     end
 end
 
 -- Move a file or directory from source to destination
 function SafeFS:move(source, destination)
     local destResolved, err = self:resolvePath(destination)
     if not destResolved then
         return nil, err
     end
 
     -- Protect root directory - cannot move to root
     if isDirectlyInRoot(destResolved) then
         return nil, "Cannot move to root directory"
     end
 
     -- Copy first
     local success, err = self:copy(source, destination)
     if not success then
         return nil, "Failed to copy: " .. (err or "unknown error")
     end
 
     -- Delete source
     local success, err = self:delete(source)
     if not success then
         return nil, "Failed to delete source: " .. (err or "unknown error")
     end
 
     return true
 end
 
 -- Create a pseudo file that uses callbacks instead of content
 -- The file node will call onRead(args) to get content and onWrite(data) to receive writes
 function SafeFS:createPseudoFile(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     -- Split path into directory and filename
     local parts = splitPath(resolvedPath)
     local filename = parts[#parts]
     table.remove(parts)
     local dirPath = joinPath(parts)
 
     -- Ensure parent directory exists
     local parentDir, err = ensureDirectory(self, dirPath)
     if not parentDir then
         return nil, err or "Parent directory not found"
     end
 
     -- Check if file already exists
     if parentDir.files then
         for _, file in ipairs(parentDir.files) do
             if file.name == filename then
                 return nil, "File already exists"
             end
 
             -- Check if there's any file that looks like it has arguments matching this pseudo file
             -- e.g., creating "/sys/date" when "/sys/date file.txt" exists
             if not file.isPseudo then
                 local spacePos = file.name:find(" ")
                 if spacePos then
                     local baseName = file.name:sub(1, spacePos - 1)
                     if baseName == filename then
                         return nil, "Cannot create pseudo file: file with arguments pattern exists"
                     end
                 end
             end
         end
     end
 
     -- Create the pseudo file node
     if not parentDir.files then
         parentDir.files = {}
     end
 
     local pseudoFile = {
         name = filename,
         type = "file",
         parent = parentDir,
         isPseudo = true,
         onRead = nil,    -- User sets this callback: function() return content end
         onWrite = nil,   -- User sets this callback: function(data) end
         onOpen = nil,    -- User sets this callback: function(path, mode) return handle end
         onDelete = nil   -- User sets this callback: function() end
     }
 
     -- Add delete method to remove itself from parent
     function pseudoFile:delete()
         -- Call onDelete callback if set
         if self.onDelete then
             local success, err = pcall(self.onDelete, self)
             if not success then
                 return false, "onDelete callback error: " .. tostring(err)
             end
         end
 
         -- Remove from parent's files list
         if self.parent and self.parent.files then
             for i, file in ipairs(self.parent.files) do
                 if file == self then
                     table.remove(self.parent.files, i)
                     return true
                 end
             end
         end
 
         return false, "Could not find file in parent directory"
     end
 
     table.insert(parentDir.files, pseudoFile)
 
     return pseudoFile
 end
 
 -- Create a pseudo directory that uses callbacks to list contents
 -- The directory node will call onFiles() and onDirs() to get contents
 -- @param path: Path to create the pseudo directory at
 -- @return pseudoDir object or nil, error
 function SafeFS:createPseudoDir(path)
     local resolvedPath, err = self:resolvePath(path)
     if not resolvedPath then
         return nil, err
     end
 
     -- Split path into directory and name
     local parts = splitPath(resolvedPath)
     local dirname = parts[#parts]
     table.remove(parts)
     local parentPath = joinPath(parts)
 
     -- Ensure parent directory exists
     local parentDir, err = ensureDirectory(self, parentPath)
     if not parentDir then
         return nil, err or "Parent directory not found"
     end
 
     -- Check if directory already exists
     if parentDir.dirs then
         for _, dir in ipairs(parentDir.dirs) do
             if dir.name == dirname then
                 return nil, "Directory already exists"
             end
         end
     end
 
     -- Create the pseudo directory node
     if not parentDir.dirs then
         parentDir.dirs = {}
     end
 
     local pseudoDir = {
         name = dirname,
         type = "directory",
         parent = parentDir,
         isPseudo = true,
         onFiles = nil,    -- User sets this: function() return {"file1.txt", "file2.txt"} end
         onDirs = nil,     -- User sets this: function() return {"subdir1", "subdir2"} end
         onRead = nil,     -- User sets this: function(filename) return content end (for reading files in this dir)
         onWrite = nil,    -- User sets this: function(filename, data) end (for writing files in this dir)
         onDelete = nil,   -- User sets this: function() end
         onTraverse = nil, -- User sets this: function(relativePath) return node end (called when traversing into this dir)
         -- Virtual files/dirs caches (populated from callbacks)
         files = {},
         dirs = {}
     }
 
     -- Default onTraverse returns self
     pseudoDir.onTraverse = function(relativePath)
         return pseudoDir
     end
 
     -- Method to refresh the virtual contents from callbacks
     function pseudoDir:refresh()
         self.files = {}
         self.dirs = {}
 
         -- Get files from callback
         if self.onFiles then
             local fileNames = self.onFiles()
             if fileNames and type(fileNames) == "table" then
                 for _, name in ipairs(fileNames) do
                     -- Create a virtual file entry that delegates to parent's onRead/onWrite
                     local virtualFile = {
                         name = name,
                         type = "file",
                         parent = self,
                         isPseudo = true,
                         _parentPseudoDir = self
                     }
                     -- Set up onRead to delegate to parent
                     virtualFile.onRead = function()
                         if self.onRead then
                             return self.onRead(name)
                         end
                         return nil
                     end
                     -- Set up onWrite to delegate to parent
                     virtualFile.onWrite = function(data)
                         if self.onWrite then
                             self.onWrite(name, data)
                         end
                     end
                     table.insert(self.files, virtualFile)
                 end
             end
         end
 
         -- Get directories from callback
         if self.onDirs then
             local dirNames = self.onDirs()
             if dirNames and type(dirNames) == "table" then
                 for _, name in ipairs(dirNames) do
                     local virtualDir = {
                         name = name,
                         type = "directory",
                         parent = self,
                         isPseudo = true,
                         files = {},
                         dirs = {}
                     }
                     table.insert(self.dirs, virtualDir)
                 end
             end
         end
     end
 
     -- Add delete method
     function pseudoDir:delete()
         if self.onDelete then
             local success, err = pcall(self.onDelete, self)
             if not success then
                 return false, "onDelete callback error: " .. tostring(err)
             end
         end
 
         -- Remove from parent's dirs list
         if self.parent and self.parent.dirs then
             for i, dir in ipairs(self.parent.dirs) do
                 if dir == self then
                     table.remove(self.parent.dirs, i)
                     return true
                 end
             end
         end
 
         return false, "Could not find directory in parent"
     end
 
     table.insert(parentDir.dirs, pseudoDir)
 
     return pseudoDir
 end
 
 -- Register a file handler for an extension
 -- extension: file extension without dot (e.g., "txt", "lua")
 -- functionName: name of the function to call on the app (e.g., "openFile")
 -- The handler will be associated with the calling app's ID
 function SafeFS:addFileHandler(extension, functionName)
     if not extension or type(extension) ~= "string" then
         return false, "Extension must be a string"
     end
 
     if not functionName or type(functionName) ~= "string" then
         return false, "Function name must be a string"
     end
 
     -- Normalize extension (remove leading dot if present, lowercase)
     extension = extension:gsub("^%.", ""):lower()
 
     -- Get the app ID from the SafeFS instance
     -- The app ID should be stored when the SafeFS instance is created
     local appId = self._appId
     if not appId then
         return false, "No app ID associated with this SafeFS instance"
     end
 
     -- Register the handler in the internal table
     _fileHandlers[extension] = {
         appId = appId,
         functionName = functionName
     }
 
     if osprint then
         osprint("[SafeFS] Registered file handler: ." .. extension .. " -> " .. appId .. ":" .. functionName .. "\n")
     end
 
     return true
 end
 
 -- Remove a file handler for an extension
 -- Only the app that registered the handler can remove it
 function SafeFS:removeFileHandler(extension)
     if not extension or type(extension) ~= "string" then
         return false, "Extension must be a string"
     end
 
     -- Normalize extension
     extension = extension:gsub("^%.", ""):lower()
 
     -- Check if handler exists
     local handler = _fileHandlers[extension]
     if not handler then
         return false, "No handler registered for extension: " .. extension
     end
 
     -- Only the app that registered the handler can remove it
     local appId = self._appId
     if handler.appId ~= appId then
         return false, "Cannot remove handler registered by another app"
     end
 
     -- Remove the handler
     _fileHandlers[extension] = nil
 
     if osprint then
         osprint("[SafeFS] Removed file handler for: ." .. extension .. "\n")
     end
 
     return true
 end
 
 -- Module-level function to get a file handler (used by sys.openFile)
 -- This is not exposed on SafeFS instances, only at the module level
 function SafeFS.getFileHandler(extension)
     if not extension or type(extension) ~= "string" then
         return nil
     end
 
     -- Normalize extension
     extension = extension:gsub("^%.", ""):lower()
 
     return _fileHandlers[extension]
 end
 
 -- Module-level function to get all registered file handlers
 function SafeFS.getAllFileHandlers()
     -- Return a copy to prevent modification
     local copy = {}
     for ext, handler in pairs(_fileHandlers) do
         copy[ext] = {
             appId = handler.appId,
             functionName = handler.functionName
         }
     end
     return copy
 end
 
 -- Create a PseudoDir for a DiskFS drive that handles all file operations via the C diskfs API
 -- @param mountPath: The mount path (e.g., "/mnt/hd0")
 -- @param bus: ATA bus number
 -- @param drive: ATA drive number
 -- @return pseudoDir object or nil, error
 function SafeFS:createDiskFSMount(mountPath, bus, drive)
     -- Check if diskfs is available
     if not diskfs then
         return nil, "diskfs module not available"
     end
 
     -- Resolve the mount path
     local resolvedPath, err = self:resolvePath(mountPath)
     if not resolvedPath then
         return nil, err
     end
 
     -- Split path into parent and mount name
     local parts = splitPath(resolvedPath)
     local mountName = parts[#parts]
     table.remove(parts)
     local parentPath = joinPath(parts)
 
     -- Ensure parent directory exists (e.g., /mnt)
     local parentDir, err = ensureDirectory(self, parentPath)
     if not parentDir then
         return nil, err or "Parent directory not found"
     end
 
     -- Check if directory already exists
     if parentDir.dirs then
         for _, dir in ipairs(parentDir.dirs) do
             if dir.name == mountName then
                 return nil, "Mount point already exists"
             end
         end
     end
 
     -- Create the pseudo directory for the disk mount
     if not parentDir.dirs then
         parentDir.dirs = {}
     end
 
     local diskMount = {
         name = mountName,
         type = "directory",
         parent = parentDir,
         isPseudo = true,
         _bus = bus,
         _drive = drive,
         _mountPath = resolvedPath,
         files = {},
         dirs = {}
     }
 
     -- Helper to build full diskfs path
     local function buildDiskPath(relativePath)
         if not relativePath or relativePath == "" then
             return resolvedPath
         end
         return resolvedPath .. "/" .. relativePath
     end
 
     -- onTraverse handles path traversal into the disk filesystem
     -- Returns a virtual node representing the file/dir at the given path
     diskMount.onTraverse = function(relativePath)
         local fullPath = buildDiskPath(relativePath)
 
         -- Check if path exists on disk
         if not diskfs.exists(fullPath) then
             return nil
         end
 
         -- Create appropriate virtual node
         if diskfs.isdir(fullPath) then
             -- Return a virtual directory node
             local virtualDir = {
                 name = relativePath:match("([^/]+)$") or mountName,
                 type = "directory",
                 isPseudo = true,
                 _diskPath = fullPath,
                 _bus = bus,
                 _drive = drive,
                 files = {},
                 dirs = {}
             }
 
             -- Populate files and dirs from diskfs.list
             local items = diskfs.list(fullPath)
             if items then
                 for _, item in ipairs(items) do
                     if item.type == "dir" then
                         table.insert(virtualDir.dirs, {
                             name = item.name,
                             type = "directory",
                             isPseudo = true,
                             _diskPath = fullPath .. "/" .. item.name
                         })
                     else
                         -- Create virtual file with diskfs callbacks
                         local virtualFile = {
                             name = item.name,
                             type = "file",
                             isPseudo = true,
                             _diskPath = fullPath .. "/" .. item.name
                         }
                         virtualFile.onRead = function()
                             local handle = diskfs.open(virtualFile._diskPath, "r")
                             if handle then
                                 local content = diskfs.read(handle)
                                 diskfs.close(handle)
                                 return content
                             end
                             return nil
                         end
                         virtualFile.onWrite = function(data)
                             local handle = diskfs.open(virtualFile._diskPath, "w")
                             if handle then
                                 diskfs.write(handle, data)
                                 diskfs.close(handle)
                             end
                         end
                         table.insert(virtualDir.files, virtualFile)
                     end
                 end
             end
 
             -- Add onTraverse for subdirectory traversal
             virtualDir.onTraverse = function(subPath)
                 if not subPath or subPath == "" then
                     return virtualDir
                 end
                 local newFullPath = fullPath .. "/" .. subPath
                 if diskfs.exists(newFullPath) then
                     -- Recursively create node for subpath
                     return diskMount.onTraverse(relativePath .. "/" .. subPath)
                 end
                 return nil
             end
 
             return virtualDir
         else
             -- Return a virtual file node
             local virtualFile = {
                 name = relativePath:match("([^/]+)$") or relativePath,
                 type = "file",
                 isPseudo = true,
                 _diskPath = fullPath
             }
             virtualFile.onRead = function()
                 local handle = diskfs.open(fullPath, "r")
                 if handle then
                     local content = diskfs.read(handle)
                     diskfs.close(handle)
                     return content
                 end
                 return nil
             end
             virtualFile.onWrite = function(data)
                 local handle = diskfs.open(fullPath, "w")
                 if handle then
                     diskfs.write(handle, data)
                     diskfs.close(handle)
                 end
             end
             return virtualFile
         end
     end
 
     -- onFiles returns list of files in root of disk
     diskMount.onFiles = function()
         local items = diskfs.list(resolvedPath)
         local files = {}
         if items then
             for _, item in ipairs(items) do
                 if item.type == "file" then
                     table.insert(files, item.name)
                 end
             end
         end
         return files
     end
 
     -- onDirs returns list of directories in root of disk
     diskMount.onDirs = function()
         local items = diskfs.list(resolvedPath)
         local dirs = {}
         if items then
             for _, item in ipairs(items) do
                 if item.type == "dir" then
                     table.insert(dirs, item.name)
                 end
             end
         end
         return dirs
     end
 
     -- onRead for files in the disk root
     diskMount.onRead = function(filename)
         local filePath = resolvedPath .. "/" .. filename
         local handle = diskfs.open(filePath, "r")
         if handle then
             local content = diskfs.read(handle)
             diskfs.close(handle)
             return content
         end
         return nil
     end
 
     -- onWrite for files in the disk root
     diskMount.onWrite = function(filename, data)
         local filePath = resolvedPath .. "/" .. filename
         local handle = diskfs.open(filePath, "w")
         if handle then
             diskfs.write(handle, data)
             diskfs.close(handle)
         end
     end
 
     -- refresh populates files/dirs arrays from callbacks
     function diskMount:refresh()
         self.files = {}
         self.dirs = {}
 
         -- Get files from callback
         local fileNames = self.onFiles()
         if fileNames and type(fileNames) == "table" then
             for _, name in ipairs(fileNames) do
                 local virtualFile = {
                     name = name,
                     type = "file",
                     parent = self,
                     isPseudo = true,
                     _diskPath = resolvedPath .. "/" .. name
                 }
                 virtualFile.onRead = function()
                     return self.onRead(name)
                 end
                 virtualFile.onWrite = function(data)
                     self.onWrite(name, data)
                 end
                 table.insert(self.files, virtualFile)
             end
         end
 
         -- Get directories from callback
         local dirNames = self.onDirs()
         if dirNames and type(dirNames) == "table" then
             for _, name in ipairs(dirNames) do
                 local virtualDir = {
                     name = name,
                     type = "directory",
                     parent = self,
                     isPseudo = true,
                     _diskPath = resolvedPath .. "/" .. name,
                     files = {},
                     dirs = {}
                 }
                 table.insert(self.dirs, virtualDir)
             end
         end
     end
 
     -- Add to parent's dirs
     table.insert(parentDir.dirs, diskMount)
 
     return diskMount
 end
 
 -- Mount all detected DiskFS drives at /mnt/hdX
 -- This should be called after SafeFS is created with /mnt/* access
 function SafeFS:mountAllDiskDrives()
     if not diskfs then
         return false, "diskfs module not available"
     end
 
     local mounts = diskfs.getMounts()
     if not mounts then
         return false, "No drives detected"
     end
 
     local mountCount = 0
     for i, mount in ipairs(mounts) do
         if mount.formatted then
             local mountPath = "/mnt/hd" .. (i - 1)
             local pseudoDir, err = self:createDiskFSMount(mountPath, mount.bus, mount.drive)
             if pseudoDir then
                 mountCount = mountCount + 1
                 if osprint then
                     osprint("[SafeFS] Mounted DiskFS drive at " .. mountPath .. " (" .. (mount.volume_name or "unnamed") .. ")\n")
                 end
             else
                 if osprint then
                     osprint("[SafeFS] Failed to mount " .. mountPath .. ": " .. tostring(err) .. "\n")
                 end
             end
         end
     end
 
     return mountCount > 0, "Mounted " .. mountCount .. " drive(s)"
 end
 
 return SafeFS