DEV Community

Toprak
Toprak

Posted on • Originally published at toprak.sh

How I made it impossible for my Mac cleaner to delete the wrong thing

#macos #swift #opensource #showdev

Originally written for Dusty, a free, open-source macOS disk cleaner.

I kept running out of disk on a 512 GB MacBook, and I could never tell where the space went. It was always caches I had forgotten about: Xcode DerivedData, a pile of old simulators, npm and pip and gradle leftovers. The annoying part was never the cleanup. It was that every tool I tried wanted me to trust it. You press one button, a progress bar says it freed 14 GB, and you have no idea what those 14 GB were. That works right up until the day it deletes something you needed.

So I wrote my own, and the whole thing started from one rule: it should be physically unable to delete the wrong thing, even if I write a bug. This is how that rule turned into code.

Allowlist, not denylist

The usual way to make a cleaner "safe" is a blocklist: delete anything except the things on a list of protected folders. That is backwards. A blocklist is safe until you forget an entry, and you will forget an entry. The failure mode is "oops, that one wasn't on the list."

An allowlist fails the other way. It refuses to delete something it could safely have deleted. That is the side I want to fail on. So a path is deletable only if it sits inside a known, named cache directory that someone deliberately added. Everything else is rejected by default.

One door for every delete

All of the deletion logic lives in a separate Swift package with its own unit tests, not buried in the UI. Inside it there is exactly one function that every candidate path has to pass through before anything is removed: validateDeletionPath. The UI cannot delete a file. It can only ask the validator, which returns a typed Result that is either .success or a specific SafetyError. There is no path around it.

public func validateDeletionPath(
    _ path: String,
    for target: CleanupTarget,
    allowlistedRoots: [String]
) -> Result<Void, SafetyError> {
    guard allowedTargetIDs.contains(target.id) else {
        return .failure(.pathNotInAllowlist(path))
    }
    if containsPathTraversal(path) {                 // reject anything with ".."
        return .failure(.pathTraversal(path))
    }
    let standardized = (path as NSString).standardizingPath
    let url = URL(fileURLWithPath: standardized, isDirectory: true)

    if isSymlink(at: url) {                           // never follow a symlinked leaf
        return .failure(.symlinkRefusal(standardized))
    }
    if matchesProhibitedPath(standardized) {          // Documents, Photos, Mail, Keychains...
        return .failure(.prohibitedPath(standardized))
    }
    guard isPath(standardized, underAnyOf: allowlistedRoots, for: target) else {
        return .failure(.pathNotInAllowlist(standardized))
    }
    guard isPath(standardized, underAnyOfResolvingSymlinks: allowlistedRoots) else {
        return .failure(.symlinkRefusal(standardized))   // ancestor symlink defense
    }
    if !isOnBootVolume(url) {                          // no external drives, no network mounts
        return .failure(.outsideBootVolume(standardized))
    }
    return .success(())
}
Enter fullscreen mode Exit fullscreen mode

Read top to bottom, that is the whole safety model. A candidate path has to survive all of it:

  1. Known target. The cleanup target has to be one the app actually ships.
  2. No traversal. Any path containing .. is rejected before it is even normalized.
  3. No symlinked leaf. If the final component is a symlink, refuse it.
  4. Not a protected folder. Documents, Desktop, Photos, Mail, iCloud, Keychains, and unnamed Application Support are out, even as parents.
  5. Inside an allowlist root. It must descend from a registered cache directory.
  6. Still inside after resolving symlinks. Resolve every link on both sides, then require it to still be inside that root.
  7. On the boot volume. Same volume as your home folder, checked with statfs.

The two checks worth explaining

Protected folders are rejected even as a parent. Your home Documents, Desktop, Pictures, Photos library, Music, Movies, Mail, iCloud Drive, and Keychains are blocked, not only on an exact match:

public static let prohibitedPrefixes: [String] = [
    "Documents", "Desktop", "Pictures", "Photos Library.photoslibrary",
    "Music", "Movies", "Mail", "Mobile Documents", "Keychains",
]
Enter fullscreen mode Exit fullscreen mode

Application Support is the dangerous one, because it holds both throwaway caches and real, irreplaceable data: app databases, your actual messages, project files. So Dusty refuses all of ~/Library/Application Support unless the path ends in one specific, named cache subfolder, like /Code/Cache or /Slack/GPUCache. It will never take an app's whole Application Support directory, because that is where the data you cannot get back tends to live.

Symlinks get two passes. The leaf check rejects a path that is itself a symlink. But normalizing a path does not resolve symlinks higher up, so a symlinked directory anywhere above the leaf, say a relocated ~/Library/Caches, could otherwise redirect a delete out of the allowlist. So the sixth check resolves symlinks fully on both the candidate and every allowlist root, then requires the resolved path to still live inside a resolved root. An ancestor symlink cannot smuggle a delete outside its box.

What the rules buy you in the UI

Because the engine refuses anything off the list, the app does not need a "clean everything" button, and it does not have one. It scans, sizes every path, and shows you the list before it touches a thing. You can do a dry run. When you do delete, it can move files to the Trash instead of unlinking them, so there is an undo, and it writes a log of what it removed. The scary part of a cleaner is the part you cannot see. The point here is that there isn't one.

What it doesn't do

It will not find every last gigabyte. It cleans known caches and developer leftovers, not your 40 GB of forgotten video exports sitting in Documents, because reaching into Documents is the exact thing it refuses to do. It is not a disk visualizer and not an uninstaller. If you want an aggressive "reclaim everything" tool, this isn't it, on purpose.

It is free, MIT licensed, signed and notarized. The engine and its tests are in the repo if you would rather check the claims than take my word for it.

brew install --cask yagcioglutoprak/tap/dusty
Enter fullscreen mode Exit fullscreen mode

Code: https://github.com/yagcioglutoprak/dusty

If there is a cache you would want it to recognize that it does not yet, adding one is a single entry in the registry, so that is the easiest kind of contribution to take.

Top comments (0)