SPB Git

Repository Public License

macos-storage-capability-matrix.md 13.3 KB

# macOS storage capability matrix

What ORIX Clean 1.0.0 can and cannot do on macOS, feature by feature, and which permission each one depends on. The classification describes the application as built (project.yml: not sandboxed, Hardened Runtime, empty entitlements file, no privileged helper), not what macOS would allow some other kind of process to do.

# How to read this document

Each feature is placed in exactly one class.

Class Meaning for ORIX Clean
No additional permission Works with the POSIX rights of the logged-in user. No prompt.
User-selected folder access macOS shows a TCC consent prompt the first time the process touches the location.
Full Disk Access Works only after the user adds the app under System Settings > Privacy & Security > Full Disk Access.
Special entitlement Would need an entitlement in the code signature.
Unsupported Not implemented, or refused by design.
Explicit user interaction The app measures or explains, but the action itself is done by the user, in the app or in another tool.

Two points apply to the whole table.

These are TCC prompts, not security-scoped bookmarks. The app is not sandboxed (ENABLE_APP_SANDBOX: NO). A sandboxed app receives access to a folder through an open panel and keeps it with a security-scoped bookmark. ORIX Clean has neither: it opens paths directly, and macOS Transparency, Consent and Control (TCC) decides per protected class of location. The consent is remembered by macOS per application, listed under Privacy & Security > Files and Folders, and revocable there. The app stores no bookmark and no path grant of its own. The texts shown in the prompts are the five usage strings in App/Info.plist (NSDesktopFolderUsageDescription, NSDocumentsFolderUsageDescription, NSDownloadsFolderUsageDescription, NSRemovableVolumesUsageDescription, NSNetworkVolumesUsageDescription), with fr-CA versions generated by Scripts/localize.py into InfoPlist.xcstrings.

No row uses "Special entitlement". App/ORIXClean.entitlements is an empty dictionary and Scripts/sign.sh fails the build if get-task-allow is present. Where the platform route would need an entitlement, the row is marked Unsupported and the note names the entitlement.

What was verified. Behaviour was observed on one machine, macOS 27.0 (26A5425a). Statements about what macOS does in a situation that was not exercised there are marked not verified on this build. macOS 15 and 26 were not run at all.

# Matrix: reading and measuring

Feature Class API used by the code Notes
Scan a folder chosen by the user No additional permission NSOpenPanel in AppModel.chooseFolderAndScan, then open(2) with O_DIRECTORY|O_NOFOLLOW and getattrlistbulk(2) For an ordinary folder. If the chosen folder is in a TCC class, the rows below apply. Whether choosing a protected folder in the panel suppresses the prompt for a non-sandboxed app: not verified on this build.
Scan the home folder User-selected folder access same The walk itself needs nothing, but it reaches Desktop, Documents and Downloads, each of which prompts. Folders that need Full Disk Access are recorded as permissionDenied issues and flagged unreadable; their content is missing from the totals and the Overview says so.
Desktop, Documents, Downloads User-selected folder access same; DownloadsAnalyzer.analyze uses FileManager.contentsOfDirectory One prompt per folder. If refused, the folder is unreadable; the Downloads section shows the refusal message from AppModel.loadDownloads.
Other apps' containers (~/Library/Containers, ~/Library/Group Containers) Full Disk Access getattrlistbulk, Measure.item The Settings text states that containers are included with Full Disk Access. Recent macOS versions also have a separate "access data from other apps" consent; whether that prompt appears for this app and is sufficient: not verified on this build.
Mail, Safari and Messages data Full Disk Access same Permissions.hasFullDiskAccess probes exactly this class: it tries open(2) on /Library/Application Support/com.apple.TCC/TCC.db, ~/Library/Safari/Bookmarks.plist and ~/Library/Mail. Probed, never bypassed.
~/.Trash listing Full Disk Access TrashAnalyzer.locations: lstat, DirectoryReader.open, contentsOfDirectory When the open fails the location is returned with accessible == false and the Trash section shows a banner instead of a size.
Volume Trashes (/Volumes/<name>/.Trashes/<uid>) User-selected folder access same Follows the consent for the volume (removable or network). Verified on an APFS disk image in the tests; behaviour on physical removable media: not verified on this build.
/Library No additional permission scanner World-readable parts are measured. Root-only and TCC-protected sub-folders are reported as unreadable.
/System No additional permission scanner Read-only measurement. A scan of /System/Library completed and reported 68 unreadable folders (see docs/development/performance.md). Nothing under /System can be selected for removal (SafetyPolicy).
Other users' home folders Unsupported scanner POSIX permissions refuse the read; the folder is listed as unreadable with size unknown. The app never elevates.
Removable volumes User-selected folder access scanner; Volumes.mounted NSRemovableVolumesUsageDescription. Exercised only on a small APFS disk image.
Network volumes User-selected folder access scanner NSNetworkVolumesUsageDescription. Not measured. Network volumes are excluded from history sampling (AppModel.refreshEnvironment). If the filesystem rejects the extended attributes, the reader retries without them and private sizes are unavailable.
iCloud Drive files that are not downloaded (dataless) No additional permission ATTR_CMN_FLAGS, tested against SF_DATALESS Detected from metadata and flagged dataless; shown as "in iCloud". A dataless directory is not traversed, and dataless files are excluded from hashing and image analysis, so nothing is downloaded. Whether traversing ~/Library/Mobile Documents triggers its own consent prompt: not verified on this build.
Photos library internals Unsupported PackageTypes.extensions, SafetyPolicy.librariesWithPrivateStructure The library is one package item with a total size, where macOS lets the app read it. Files inside are not offered as duplicates or similar images by default, and removal of anything inside is refused. Which permission reading inside the library needs: not verified on this build.
APFS private size, clone id, sharing flags No additional permission getattrlistbulk with FSOPT_ATTR_CMN_EXTENDED and ATTR_CMNEXT_PRIVATESIZE, ATTR_CMNEXT_CLONEID, ATTR_CMNEXT_EXT_FLAGS Public attributes in <sys/attr.h>. On EINVAL or ENOTSUP the read is retried without them.
Volume capacity and free space No additional permission FileManager.mountedVolumeURLs, URLResourceKey.volumeTotalCapacityKey, .volumeAvailableCapacityKey, statfs(2)
Purgeable space No additional permission .volumeAvailableCapacityForImportantUsageKey minus .volumeAvailableCapacityKey A figure reported by the system, shown when above 500 MB. The app cannot purge it.
APFS local snapshots Unsupported none Not enumerated, measured or deleted. The platform call (fs_snapshot_list) requires root or the com.apple.developer.vfs.snapshot entitlement. Reports carry a limitation line saying snapshots can keep removed data on disk.
Spotlight last-used date of an application No additional permission MDItemCreate, MDItemCopyAttribute with kMDItemLastUsedDate Nil when Spotlight has no record.
Code-signature information No additional permission SecStaticCodeCreateWithPath, SecCodeCopySigningInformation, SecStaticCodeCheckValidity with kSecCSBasicValidateOnly Static check; the application is not executed.
Running-application detection No additional permission NSWorkspace.shared.runningApplications Used to refuse cleaning data of an application that is running.
Registered-application lookup for leftovers No additional permission LSCopyApplicationURLsForBundleIdentifier Used so that an identifier known to Launch Services is not reported as a leftover.
Quick Look, thumbnails, Reveal in Finder No additional permission QLPreviewPanel, QLThumbnailGenerator, NSWorkspace.activateFileViewerSelecting Subject to the same read access as the file itself.

# Matrix: changing things

Feature Class API used by the code Notes
Moving an item to the Trash Explicit user interaction FileManager.trashItem(at:resultingItemURL:) Only after the cleanup preview is confirmed (CleanupAuthorization). Needs write access to the item's parent and, for a TCC-protected parent, the same consent as reading.
Putting an item back Explicit user interaction FileManager.moveItem from the recorded Trash path Only while the item is still in the Trash and the original path is free. Reading the home Trash path may itself require Full Disk Access: not verified on this build.
Emptying the Trash Full Disk Access FileManager.removeItem Needs the Trash listing above. Also requires typing DELETE in the preview. Permanent mode is refused for any item whose category is not trash.
Uninstalling an application the user can write to Explicit user interaction AppInventory.uninstallItems, then the Trash path above Bundle plus the associated files the user ticks, each with a stated confidence.
Uninstalling an App Store application owned by root Explicit user interaction same The engine does not elevate. If macOS refuses the move, the record is failed with "Permission denied by macOS" and the user removes the application in Finder or Launchpad. Outcome for a root-owned bundle: not verified on this build.
Uninstalling system applications Unsupported InstalledApp.isSystem, SafetyPolicy Applications under /System/ or /Library/Apple/ yield no uninstall items, and the policy denies those paths.
Simulator devices and runtimes Explicit user interaction CleanupCatalog.manualHints Measured and listed with the supported command (xcrun simctl delete unavailable, Xcode > Settings > Components). Never removed by the app. Simulator dyld caches under CoreSimulator/Caches are an ordinary low-risk candidate.
Docker data Explicit user interaction CleanupCatalog.manualHints The disk image under ~/Library/Containers/com.docker.docker/Data/vms is measured, when readable, and shown with docker system prune as guidance. Never removed by the app.
Deleting local snapshots, thinning purgeable space Unsupported none See snapshots above.
Removing root-owned files, items in /System, /usr, /private/var/db Unsupported SafetyPolicy.evaluate Refused before any filesystem call.

# What Full Disk Access does not grant

Full Disk Access lifts the TCC privacy restrictions for one application. It does not change who the process is.

  • System Integrity Protection. SIP-protected locations stay read-only for every process, including root. ORIX Clean reads sizes there and SafetyPolicy refuses removal independently of SIP.
  • The sealed system volume. The startup volume is a signed, read-only snapshot. Volumes.info reports / as writable only because what matters to the user is the Data volume mounted behind it; nothing on the sealed volume can be modified.
  • Other users' files. POSIX permissions and ACLs still apply. A folder with mode 700 owned by another user stays unreadable and is reported as such.
  • Root-owned items. They can be measured if readable, but not removed: the app has no privileged helper, never asks for an administrator password, and Scripts/check.sh fails if the sources contain AuthorizationExecuteWithPrivileges, SMJobBless, NSAppleScript or /usr/bin/sudo.
  • Data vaults of system services. Some system services keep data in locations that only processes with an Apple-private entitlement can open. These remain unreadable with Full Disk Access; which locations are affected on a given macOS version is not verified on this build. They appear as unreadable folders.
  • Snapshots. Listing or deleting APFS snapshots needs root or a dedicated entitlement, not Full Disk Access.
  • A way around the application's own rules. The deletion engine's deny list is evaluated regardless of what macOS would allow.

# How the app reports what it could not read

  • Every unreadable directory becomes a ScanIssue (permissionDenied, vanished, ioError, pathTooLong) and the node is flagged unreadable; the map list labels it "not readable".
  • The Overview shows the count of unreadable folders and how many were refused for lack of permission.
  • ReportBuilder.limitations writes the same facts at the top of every exported report, including whether Full Disk Access was granted and whether the filesystem reported shared blocks.
  • Settings > Privacy & Access shows the Full Disk Access state from the probe, with a button that opens x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles.
Files main
Menu

Theme