Supported quarantine preservation when copying files from an App Sandbox process

What supported public API and verification contract should a sandboxed macOS file manager use to preserve a copied file's quarantine/provenance metadata? We observe different results in App Sandbox versus Finder and an otherwise-matched non-sandbox diagnostic. We want to keep App Sandbox and all security protections enabled, not remove quarantine or invent undocumented flag masks.

Environment: macOS 26.6.2 (25G83), Apple Silicon, local APFS. Optimized Foundation-only diagnostic, Apple Development signing, Hardened Runtime, launched directly as an executable. The sandbox variant has app-sandbox, user-selected read/write and app-scope bookmark entitlements. This is not a notarized distribution-build comparison.

Reproduction:

  1. Use an existing regular JPEG with naturally present com.apple.quarantine metadata identifying Chrome, raw flags 0283 and a nonempty event field. Keep the original read-only. Record SHA-256, length, full raw extended attributes and fresh NSURL quarantinePropertiesKey observations.
  2. Keep access to a user-granted local test directory active. Copy to a new, absent destination in a fresh directory using each of these three arms:
    • fclonefileat with CLONE_ACL | CLONE_NOFOLLOW_ANY | CLONE_RESOLVE_BENEATH (28).
    • copyfile with COPYFILE_CLONE | COPYFILE_ACL; record COPYFILE_STATE_WAS_CLONED.
    • FileManager.copyItem(at:to:).
  3. Observe source and destination without setting, removing or repairing metadata. Each arm waits at least 1.1 seconds before copying; the source quarantine timestamp is much older than call time.
  4. Repeat with fresh destinations. Also copy the same source through actual Finder Copy/Paste twice.
  5. Compare two signed variants made from the same compiled payload, with identical executable name, bundle ID, Development identity and Hardened Runtime. The only signed entitlement difference is app-sandbox=true versus its omission. The sandbox variant resolves the existing exact folder grant; the non-sandbox diagnostic uses that same fixed test directory directly.

Results:

  • Sandbox diagnostic: all six calls succeed and data hashes/lengths match. All six outputs change raw flags 0283 to 0082, agent Chrome to the diagnostic app, event field nonempty to empty, and timestamp. Public output lacks the source event identifier and adds LSQuarantineTypeSandboxed.
  • Matched non-sandbox diagnostic: all six copies preserve the full observed raw quarantine record and public quarantine dictionary. copyfile reports WAS_CLONED=true in both contexts.
  • Finder: both copies preserve the full observed raw quarantine record and public dictionary.
  • Source bytes and declared preserved metadata remain unchanged. Other compared raw attributes, mode, flags, birth/modification times, owner/group and ACL match in these cases.

We also reproduced timestamp-only differences with files naturally quarantined by the diagnostic itself. The foreign-agent control above shows that the difference is not limited to timestamp. The chosen source exposes no public origin/data URL, so their preservation is untested. We have not traced the responsible internal component, tested Gatekeeper effects, or established whether the transformation is security-equivalent. We do not claim the three APIs use independent implementations or that all possible public API combinations have been tested.

Could you clarify:

  1. Is this transformation expected for copying from an App Sandbox process, or should we file it as a bug? What documented preservation behavior should a sandboxed file manager rely on?
  2. Is there a supported API or operation that preserves the source's quarantine/provenance metadata in this context without disabling App Sandbox or weakening security protections?
  3. If exact raw equality is intentionally not guaranteed, which supported public properties or behaviors should verification check? Is a quarantine-properties dictionary round-trip supported, and what information does it preserve or omit? We have not attempted a metadata repair.

Separately, a pathname-based repair after cloning would require its own destination-identity/race safety review because the clone call does not return a creation-bound destination descriptor. We are asking for supported API semantics, not private implementation details or a security bypass.

We can prepare a minimal sanitized standalone reproducer if needed. No user files, sandbox grants, private logs or diagnostic binaries are attached to this initial question.

Answered by DTS Engineer in 905546022
  1. Is this transformation expected for copying from an App Sandbox process, or should we file it as a bug? What documented preservation behavior should a sandboxed file manager rely on?

It's the expected default behavior, but not necessarily appropriate for all situations.

  1. Is there a supported API or operation that preserves the source's quarantine/provenance metadata in this context without disabling App Sandbox or weakening security protections?

So, I believe the entitlement "com.apple.security.files.user-selected.executable" is what you need to add. It's normally described in the context of apps that generate true executable files, but I think there's a reasonable argument that it’s also appropriate for dedicated file management apps.

  1. If exact raw equality is intentionally not guaranteed, which supported public properties or behaviors should verification check? Is a quarantine-properties dictionary round-trip supported, and what information does it preserve or omit? We have not attempted a metadata repair.

My recollection is that "com.apple.security.files.user-selected.executable" means your app has full access to the quarantine attribute, so you'd preserve or remove it as needed.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Accepted Answer
  1. Is this transformation expected for copying from an App Sandbox process, or should we file it as a bug? What documented preservation behavior should a sandboxed file manager rely on?

It's the expected default behavior, but not necessarily appropriate for all situations.

  1. Is there a supported API or operation that preserves the source's quarantine/provenance metadata in this context without disabling App Sandbox or weakening security protections?

So, I believe the entitlement "com.apple.security.files.user-selected.executable" is what you need to add. It's normally described in the context of apps that generate true executable files, but I think there's a reasonable argument that it’s also appropriate for dedicated file management apps.

  1. If exact raw equality is intentionally not guaranteed, which supported public properties or behaviors should verification check? Is a quarantine-properties dictionary round-trip supported, and what information does it preserve or omit? We have not attempted a metadata repair.

My recollection is that "com.apple.security.files.user-selected.executable" means your app has full access to the quarantine attribute, so you'd preserve or remove it as needed.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Thank you, Kevin. We tested com.apple.security.files.user-selected.executable in a matched, Development-signed sandbox comparison on macOS 27.0.

With our original entitlements, exact raw and public quarantine metadata preservation failed in all 6 attempts. Adding only this entitlement produced exact matches in all 6 attempts across fclonefileat, copyfile, and FileManager.copyItem.

We then added the entitlement to Filery and verified its normal UI Copy/Paste path on local APFS. The file bytes and SHA-256, complete raw com.apple.quarantine value, and fresh NSURL.quarantinePropertiesKey dictionary all matched the source.

This resolves the issue for our measured case while retaining App Sandbox and user-granted folder access. We’ll separately verify the final Mac App Store archive’s effective entitlements and broader filesystem cases.

Thank you for pointing us to the supported entitlement.

Some quick follow-up on this:

We’ll separately verify the final Mac App Store archive’s effective entitlements and broader filesystem cases.

This is a fairly "sensitive" entitlement, so I don't know whether or not your app will be allowed to use the entitlement on the Mac App Store, as it depends entirely on exactly what your app does and why that makes the entitlement essential. A few points to be aware of:

  • When you submit your app for review, include a note describing why you've added the entitlement. This shouldn't be an elaborate argument, just a straightforward description along the lines of "I've included the entitlement because when the user does <blah>, the quarantine shift to my app causes <description of user problems it creates>".

  • It's entirely possible your app will still be rejected, even with the description above. Frankly, App Review gets a lot of app submissions which include all sorts of unnecessary entitlements, but that also means they sometimes reject apps that should be allowed to use the entitlement. If that happens, the next step is to write up a more in-depth version of the description I mentioned above and then appeal your rejection.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Quarantine preservation on exFAT with user-selected.executable enabled

Thank you for the earlier guidance. We added com.apple.security.files.user-selected.executable and confirmed preservation in the previously reported same-volume APFS case. We now have a separate cross-volume APFS-to-exFAT case where that result does not carry over.

Environment: Apple Silicon, macOS 27.2.1 (26B131), Apple Development-signed installed app. Its effective signature includes App Sandbox, user-selected read/write, user-selected.executable, app-scope bookmarks, network client, and get-task-allow. The destination is an attached exFAT volume. The app retains its actual existing folder access; no grants are borrowed from another application. This is a development-build observation, not a distribution-build or Mac App Store qualification.

Input: an ordinary, naturally downloaded JPEG with a nonempty four-field com.apple.quarantine attribute and com.apple.metadata:kMDItemWhereFroms. Tests copy into fresh disposable destination directories. The source is only read. No quarantine is removed, flags normalized, private entitlement added, or AppleDouble contents manually rewritten.

Observed results:

  1. Actual Finder copies preserve file bytes and both raw attributes. In a larger control, all 376 media files matched by SHA-256 and the 223 media files carrying download attributes retained both attributes exactly. Finder also retained the hidden folder-settings file and its observed FinderInfo/quarantine/hidden state. These are local observations for this fixture and OS, not a universal Finder guarantee.

  2. The installed app's descriptor-based fsetxattr of the source quarantine onto its own newly created destination fails with EPERM. Its signed user-selected.executable entitlement is present. We stopped that copy before payload writes. The current application.sb also contains a direct quarantine-xattr write denial; we have not changed this policy.

  3. Earlier installed-app fcopyfile-based metadata attempts did not pass exact raw quarantine read-back verification. We do not assert that a changed record is security-equivalent, and have not substituted a comparison of undocumented flag masks for preservation verification.

  4. A fresh standalone NSWorkspace performFileOperation copy preserved both raw attributes. However, the same public operation called from inside the normally launched, signed installed app returned success but left the copied JPEG without com.apple.quarantine. Its 5,948,236 data bytes matched the source by SHA-256 and WhereFroms matched exactly. The source still had its quarantine record. The missing destination attribute was independently read after the operation returned. We rejected this candidate. This older API is deprecated; we are not proposing it as the preferred production solution.

  5. A standalone FSPathCopyObjectSync control returned success but changed raw quarantine, while retaining WhereFroms. It is also deprecated and was not adopted.

The standalone and installed comparisons above are not otherwise-matched signed A/B binaries, so they do not isolate a single responsible component. They do establish that standalone copy success has not qualified the installed app. We have not tested downstream Gatekeeper decisions and are not alleging a generally reproducible macOS defect from these results.

Questions:

  • Which supported public copy API should an App-Sandboxed file manager use to preserve a downloaded file's quarantine/provenance when copying to exFAT, with user-selected.executable already enabled?
  • Does the entitlement's preservation behavior have a filesystem or cross-volume limitation? Is the observed missing quarantine after the workspace operation expected, or suitable for a focused Feedback report?
  • If exact raw preservation is intentionally unavailable, what documented metadata-preservation contract should the app verify? We need an explicit answer before changing a fidelity promise; merely observing successful payload copying or a changed record does not establish equivalence.

We can prepare a sanitized minimal reproduction if requested. This follow-up contains no source media, local paths, saved grants, raw quarantine values, download URLs, event identifiers, credentials, or private logs.

Local disposition: the diagnostic code was removed, its disposable copy was cleaned up, and the prior installed app was restored. The issue remains unresolved. No Finder automation permission or security-setting change has been made, and no experimental copy path is being presented as fixed.

So, let me start here:

We added com.apple.security.files.user-selected.executable and confirmed preservation in the previously reported same-volume APFS case.

This works because you're actually calling clonefile, not "copying the file". All of our "copy" APIs use clonefile when copying within the same volume and that ends up preserving the quarantine data.

We now have a separate cross-volume APFS-to-exFAT case where that result does not carry over.

That's unfortunate. I thought the entitlement would let you preserve quarantine, but it looks like it just lets you avoid setting it at all.

Which supported public copy API should an App-Sandboxed file manager use to preserve a downloaded file's quarantine/provenance when copying to exFAT, with user-selected.executable already enabled?

I'm not sure there is one. The only reason NSWorkspace.performFileOperation works is that it IS in fact using the Finder to do the copy, which isn't really what you need/want.

That leads to here:

If exact raw preservation is intentionally unavailable, what documented metadata-preservation contract should the app verify?

What are you ACTUALLY trying to do here? More specifically, if your goal is to prove "the file is the same as the original", then I think you need to rethink your approach and just ignore quarantine entirely. One of the reasons xattrs exist at all is so that the system can attach metadata to objects while simultaneously NOT treating that metadata as "part of the file". Critically, the choice about how a given xattr should be handled is a choice that varies based on both the specific xattr AND the larger context of what the copy is "for". You can see how copyfile implements its logic for this here.

In the case of quarantine, that's a particularly strange edge case, as quarantine SHOULDN'T be preserved when crossing file systems. The point of quarantine is to track what app has manipulated a given file and, when crossing file systems, there's no way for the system to reliably determine the relationship between the "source" and the "destination". All the system actually "knows" is that you wrote a file out, so it attaches your quarantine data to that file.

Within that context, the Finder (and possibly a few other tools) are "special", in that we know that they WON'T modify a file's contents, so we choose to preserve quarantine unchanged. However, that's not really a behavior any app can mimic.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware