Seeking clarification on macOS URLs with security scope

An update: I thought it would be enlightening to write a simple demonstration app. I did that and learned a few things.

Apple documentation describes two entitlements that are required for security scoped bookmarks. This document is strange. For one thing, the URL is under video applications. And it's ancient, referring to changes in macOS 10.7.3. It's also wrong. The entitlement "com.apple.security.files.bookmarks.app-scope" is not necessary and has no effect.

More importantly, the entitlement "com.apple.security.files.bookmarks.document-scope" is required for security scoped bookmarks with document scope. You'll get an error if you attempt to use them without this entitlement. Unfortunately, they also don't work at all. The entitlement error is straightforward and tells you that you need the entitlement. But then, when you provide it, all attempts fail with error 256 "Item URL disallowed by security policy". It does seem to be modifying the metadata of the reference URL, but then it just doesn't work. That's too bad. I prefer to have data where I can see it.

As far as security-scoped bookmarks and URLs, it's just really complicated now. It's impossible to create security-scoped bookmarks for certain URLs. I've only found two paths that are guaranteed failures: / and /System/Volumes/Data. These are kinda the same thing, but also kinda not. Unfortunately, if you allow the end user to select a directory, there's nothing stopping them from selecting these two locations.

My recommendation is to wrap a URL in a class that can manage both the start/stopAccessingSecurityScopedResource and when creating a security scoped bookmark, fall back to a standard bookmark (or just an absolute string) on failure and hope that's useable after restart.

Maybe this is just a bug in macOS 26 and it'll be fixed before launch. But even if this happens, this is obviously an API that's at risk for breakage.

So, going through lots of details in no particular order:

The entitlement "com.apple.security.files.bookmarks.app-scope" is not necessary and has no effect.

Looking at our code, it's not that it’s unnecessary, it's actually that User selected read/write are both accepted as well. If you wanted to create a process that created bookmarks but didn't present open/save panels (for example, as a helper process), then you could use it.

But what's confusing is this other, directly-related API where a security-scoped bookmark cannot be created under any circumstances because of the URL itself, some specific way the URL was initially created, and/or manipulated?

So, the way to understand this is to invert the question, to "Are there URLs which you're ALWAYS allowed to access?". The answer to that is "yes". You can poke around to find other examples but they include directories like "/Applications/", /Library/, and even "/". Two notes on that:

1. The right to access a given directory does NOT mean you have access to all of its subdirectories.

2. The access you "get" to a given location depends on HOW you got access to that location and the bookmark will preserve that access.

In concrete terms, a bookmark created directly to "/" (hard-coded path) will be able to read "/" (the top level) but will NOT be able to read "/Users/". However, a bookmark created from an open panel WILL be able to read "/Users/".

In any case, the first step when testing this is to make sure you're using a directory/file you CAN'T otherwise access.

Moving to here:

But if start returns false, then it isn't needed, so don't call stop.

That's true, but also a problem. On the Mac, start returning "false" generally means that you don't have access to the file, which generally means you're doing something wrong.

So, what I'm asking is if someone could elaborate on what would cause a failure to create a security-scoped bookmark?

Your app sandbox needs to have access to "extended" to that location. In practice, that means the URL needs to have "come" from the system, typically through an open/save panel or something like drag and drop.

What kinds of URLs are valid for creation of security-scoped bookmarks?

It's not something you can "see" like that. My general advice here is to treat any URL you receive from the system as a "magic" object. In practice, I generally convert it to a bookmark, then resolve the bookmark again, and use that new URL*, discarding the original ("magic") URL.

*This ensures that the rest of my app is ALWAYS working with "a URL that came from a bookmark", instead of a "split" flow.

Are there operations on a URL that will then cause a failure to create a security-scoped bookmark?

Sort of. The problem here is that when you receive a URL from the system, your access is tied to components you can't see or control. That's why I recommend the "immediate" conversion above— by generating and then resolving, you’re changing the "source" of your access to something you directly control.

Is it allowed to pass the URL and/or bookmark back and forth between Objective-C and Swift?

Yes, however, you need to be careful about what you actually "do" with that object, as you will lose access if your "magic" URL (the object you created by resolving) goes away.

Having said that, in most cases, the better option here is to create your own class which "handles" access to that object and "owns" both the bookmark and any URL. If it has problems, then it just resolves the bookmark again.

Finally, here:

I've only found two paths that are guaranteed failures: / and /System/Volumes/Data.

This is a bug (r.157722315). I'm not sure of the full scope, but I know it will effect the ROSV (Read Only System Volume) pair (the case above) and certain FAT/EXFAT files/volumes.

I think this started happening with macOS 26, but that doesn't really matter. If this is new behaviour in macOS 26, then I must live with it.

I'm not sure this will be fixed in macOS 26.0, but fixing it is a very high priority.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

If you wanted to create a process that created bookmarks but didn't present open/save panels (for example, as a helper process), then you could use it.

The only time I imagine this could be executed would be if a helper resolved a bookmark and found it stale. Don't know how I could test that, but I guess this means "com.apple.security.files.bookmarks.app-scope" actually is required. Thanks for the insight.

In concrete terms, a bookmark created directly to "/" (hard-coded path) will be able to read "/" (the top level) but will NOT be able to read "/Users/". However, a bookmark created from an open panel WILL be able to read "/Users/".

My issue here is the type of bookmark. I cannot create a security-scoped bookmark to / from an open panel. That's what I meant about being lucky. For this app, in this instance, I don't need to read /Users. I just want the size and free space on the volume itself. The app is currently working just by creating whole-volume URLs from the path.

Originally, I thought I would need security-scoped URLs. Then they didn't work. Then I figured out I didn't need them at all. But I would still prefer to code defensively.

On the Mac, start returning "false" generally means that you don't have access to the file, which generally means you're doing something wrong.

That is not the focus of my question here. I think I've seen it return false, and noted it in passing, but didn't have any problems. It could have been on iOS. I have a large cross-platform project on temporary hiatus. That project is where I adopted the practice of checking the result of start.

My general advice here is to treat any URL you receive from the system as a "magic" object. In practice, I generally convert it to a bookmark, then resolve the bookmark again, and use that new URL*, discarding the original ("magic") URL.

*This ensures that the rest of my app is ALWAYS working with "a URL that came from a bookmark", instead of a "split" flow.

But converting certain "magic" URLs always fails, therefore a "split" flow is unavoidable.

the better option here is to create your own class which "handles" access to that object and "owns" both the bookmark and any URL. If it has problems, then it just resolves the bookmark again.

Yes. That's what I'm going to do, in order to manage this split flow. Your advice makes a lot of sense, especially for this issue. When I get a URL from the system, convert it to a bookmark. First try a security-scoped bookmark. But if that fails (as it will for / and /System/Volumes/Data), then try a standard bookmark, and if that fails just use the path. Then resolve that "persisted resource" to my own URL and use that.

I think a better approach than wrapping the URL is just to create a "URLResource" object that will contain a type enum and data. It will handle security-scoped bookmarks, regular bookmarks, and absolute strings. It'll still be sendable too.

The only time I imagine this could be executed would be if a helper resolved a bookmark and found it stale. Don't know how I could test that, but I guess this means "com.apple.security.files.bookmarks.app-scope" actually is required. Thanks for the insight.

I should have said "resolve", not just "create". The use case here is a helper tool/process that's given a URL "target" (for example, through XPC) but something like (like your main app), so the user never actually selects files "for" it.

My issue here is the type of bookmark. I cannot create a security-scoped bookmark to / from an open panel.

So, again, the issue here is purely a bug.

However:

That's what I meant about being lucky. For this app, in this instance, I don't need to read /Users. I just want the size and free space on the volume itself. The app is currently working just by creating whole-volume URLs from the path.

So, volumes themselves are actually another special case here, as retrieving volume level metadata goes through a completely different code path than "normal" file access. I just tested it myself and, as far as I can tell, you can directly retrieve all four of the volume capacity keys using an "arbitrary" path* on the file system without being given any user authorization to that location. In the low level system, this works because that a call like "statfs" actually does is pass that path to VFS system, which then uses that path to determine the target volume, and then returns the data from the volume itself. The target path itself was never opened or "examined" in any meaningful way.

*I hard-coded the path to a folder inside my downloads directory.

Stepping back for a moment, what's your larger goal here? If you're specifically interacting with volumes then the other, often better, option is to move down a level in the system and use DiskArb, which ends up bypassing most of these issues.

But converting certain "magic" URLs always fails; therefore, a "split" flow is unavoidable.

Yes, but this comes back to "what are you trying to do“? Looking at the two you've mentioned:

1. "/" -> The fact that bookmarks are failing here is a bug; however, bookmarking "/" isn't something you'd normally do anyway.

2. "/System/Volumes/Data” -> How did you get this? It doesn't show up in open panels on macOS 15, and it shouldn't be showing up on macOS 26. If you're somehow allowing its selection yourself... well, that leads to much larger questions.

Basically, the open panel shouldn't be giving you any object you can't bookmark. Similarly, the fact that security-scoped bookmarks are failing while regular bookmarks are not is basically an accidental detail of the specifics of the bug, not something I'd consider "common" or reliable.

Note that if you're getting file references from other sources (like navigating the hierarchy yourself), there are lots of objects that can't be bookmarked, but many of those are also in the category of "don't treat this like a file at all" (for example, the contents of /dev/).

One qualifier here:

Your advice makes a lot of sense, especially for this issue. When I get a URL from the system, convert it to a bookmark.

This assumes you'll be preserving file access with a bookmark. If you're just interacting with a file the user gave you, then don't bother creating a bookmark.

Shifting to here:

It will handle security-scoped bookmarks, regular bookmarks, and absolute strings.

Two points here:

1. On macOS, I would assume that you won't be able to restore access to a resource unless you have a security-scoped bookmark. The other references might be useful for things hinting to the open panel about the target (to restore access).

2. I think paths and bookmarks should be treated as fundamentally different concepts, not as replacements for each other. A path is a static reference to a precise location in the file system tree, while a bookmark is a persistent reference to an object on a particular file system.

Expanding on #2, the problem here is that those two different references often point to "the same thing"... until they don't. For example, a volume name collision can change the target of a path but has no effect on a bookmark. This might seem like a minor semantic difference, but I've seen too many bugs that we caused by engineers not really understanding these issues.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

I should have said "resolve", not just "create". The use case here is a helper tool/process that's given a URL "target" (for example, through XPC) but something like (like your main app), so the user never actually selects files "for" it.

In my current app, it turned out that I don't need bookmarks. But I have apps in development that will need bookmarks for both files and directories.

I've seen some recent threads here involving bookmarks. I can't find the exact one, but I remember one in particular that discussed some complicated interactions between processes and bookmarks. In following these threads, bookmarks seem less and less straightforward.

the issue here is purely a bug.

The word "bug" is a bit of a value judgement. I think it might be better to refer to bugs as simply "behaviour". Apple might be able to differentiate between expected and unexpected behaviour. But for 3rd party developers, it's all just behaviour. The only thing that's important is that said behaviour is documented.

Stepping back for a moment, what's your larger goal here? If you're specifically interacting with volumes then the other, often better, option is to move down a level in the system and use DiskArb, which ends up bypassing most of these issues.

Currently, it's just a login item that checks volume free space. I had planned on using security-scoped bookmarks just because it seemed to be the standard way to persist URLs in a sandboxed app.

I am using Disk Arbitration, as well as IOKit, but that's for collecting additional information about the location referred to by the URL, as a URL for an external volume is not reliable. That being said, I do need to use a URL as a starting point to see if it's the correct volume.

bookmarking "/" isn't something you'd normally do anyway.

I realize that now. But the issue here is that if I allow the end user to select a URL, which in the Mac App Store, I must do, then I need to handle the location selected, by any means necessary.

"/System/Volumes/Data” -> How did you get this?

Primarily this is for FSEvents. It's not related to the login item, any security-scoped bookmarks, or any persistence issues. I was poking around to learn more about this unexpected behaviour and this seems related.

Basically, the open panel shouldn't be giving you any object you can't bookmark.

Again, "shouldn't" is a value judgement. It's my job to write code that works properly with observed behaviour, expected or otherwise. Judgements are out of scope.

Note that if you're getting file references from other sources (like navigating the hierarchy yourself), there are lots of objects that can't be bookmarked, but many of those are also in the category of "don't treat this like a file at all" (for example, the contents of /dev/).

Exactly! Thankfully, I can't even navigate to /dev in an open panel. But what about other locations? Originally, this would have been a bigger problem. I've avoided that by restricting the user selection to whole volumes. I would prefer not to do this, but "/" is likely to be a popular choice, so I have to support it. If I allow arbitrary paths, then I have to handle both the unbookmarkable / and bookmarks. I might still do that, just not tonight.

I would assume that you won't be able to restore access to a resource unless you have a security-scoped bookmark.

Yes. That was my assumption too, leading to the catch-22.

I think paths and bookmarks should be treated as fundamentally different concepts, not as replacements for each other. A path is a static reference to a precise location in the file system tree, while a bookmark is a persistent reference to an object on a particular file system.

Which is why I'd prefer to use bookmarks.

For example, a volume name collision can change the target of a path but has no effect on a bookmark.

That was one of the reasons I wanted to use bookmarks in the first place. However, I don't think that guarantee is actually documented, so I had always intended to use data from Disk Arbitration and IOKit to double-check.

But I think we're going in circles at this point. I wanted to get some clarification and I did. It's a bug new behaviour, which is likely to change in the future. But it's August 29, so macOS 26 is likely to ship with this new behaviour, so I'll need to handle it permanently, and any likely new behaviours. The internals, and public API, is far more complex than I had assumed. But I've learned some strategies to minimize the impact on my code.

I've seen some recent threads here involving bookmarks. I can't find the exact one, but I remember one in particular that discussed some complicated interactions between processes and bookmarks.

I suspect what you're referring to here is that standard (vs document) scoped bookmarks can only be opened by the executable that created them, which means a bookmark created by your main app can't be resolved by your helper process. There are a number of options depending on what you’re trying to do, but yes, this does mean that making passing file access between app components more complicated.

The word "bug" is a bit of a value judgement. I think it might be better to refer to bugs as simply "behaviour". Apple might be able to differentiate between expected and unexpected behaviour. But for 3rd party developers, it's all just behaviour. The only thing that's important is that said behaviour is documented.

I understand what you're saying here, but I want to be clear that the specific issue you're describing around scoped bookmarks to "/" failing is explicitly "a bug". It was accidentally broken by a specific security fix, and I expect it to be fixed in fairly short order.

I realize that now. But the issue here is that if I allow the end user to select a URL, which in the Mac App Store, I must do, then I need to handle the location selected, by any means necessary.

That's a totally fair point, but bookmarking "/" WILL work. The fact that it doesn't work now is an unfortunate accident that will be fixed. My concern here is that you're designing as if this was a common failure case when it simply isn't. I think it's very reasonable to be thinking of having a "backup" solution in place (for example, storing the path and using that to prime an open panel), but I also want to make sure that you’re approaching that as a "general" backup (in case resolution to other locations fails), not assuming the behavior you're seeing now will continue.

That's particularly important because of this:

"/System/Volumes/Data” -> How did you get this?

Primarily, this is for FSEvents. It's not related to the login item, any security-scoped bookmarks, or any persistence issues. I was poking around to learn more about this unexpected behaviour, and this seems related.

The failure here isn't a bug. The modern boot architecture of the system involves some very strange file system manipulations (in particular, what firmlinks do), and that file path and the inability to bookmark it are both manifestations of that. If you move "below" the file system layer "presented" by our higher-level APIs (like the open panel), then you need to be aware that there are LOTS of complicating edge cases that you may need to manually address.

That leads to here:

Exactly! Thankfully, I can't even navigate to /dev in an open panel. But what about other locations?

Neither the Finder nor our open panels present an accurate view of the actual file system. They SEEM like they do, but that's because many locations happen to directly correlate, not because the goal was to present what's actually being stored on disk. A few examples:

1. The merging of the data and boot volumes into a single hierarchy.

2. The presentation of the contents of iCloud Drive, as well as other FileProvider volumes.

3. The presentation of "/Applications/" (which is actually the contents of two different directories).

Note that 2 & 3 are both fairly "superficial" overlays that don't actually attempt to fully mimic how a unified directory would behave. For example, both of them allow the creation of items with duplicate names, as long as the two objects are coming from different source locations.

That leads to here:

Basically, the open panel shouldn't be giving you any object you can't bookmark.

Again, "shouldn't" is a value judgement. It's my job to write code that works properly with observed behaviour, expected or otherwise. Judgements are out of scope.

No, it's a bit stronger than that. Speaking as the person who has spent significant time working with the engineering team on these issues, the expected behavior of the bookmark system on macOS is that it should be able to:

• Bookmark everything our open panel returns.

• Correctly resolve everything it bookmarks within the limitations inherent to filesystems and/or storage data source.

If you find an exception to those points, then it's a bug that we need to fix. I'll admit that the security side of this means that bugs do happen (mostly around resolution), however, these bugs are also taken quite seriously and tend to be resolved fairly quickly*.

*Note that the nature of how we handle major OS release can make it look like an issue "exists" longer than it really does. The relevant timeframe here is the time between when the version was released to the public ("15.0") and when a fix for that bug shipped to the public ("15.1"), not how long the bug existed in our seed builds.

Finally, two quick notes on the "limitations" point:

1. Bookmark resolution ultimately relies on metadata supplied by the filesystem, so it can only work as well as the file system does. Resolution works correctly on "our" file systems, but I'm sure there are 3rd party file systems where it won't.

2. DiskImages can make things weird. Basically "all" file systems include some mechanism to ensure uniqueness, which is how bookmarks know which volume is the "right" volume. The problem is that DiskImages make it trivial to violate that contract (just duplicate the image), at which point you now have two file system sources which the bookmark system can resolve to.

You might be able to partially address #1 by using IOKit/DiskArb to identify information like the physical interface and using that to do your own identification, but that won't really help with #2. The problem with #2 is that there isn't really any "right" answer, as both volumes ARE "the volume". However, I suppose IOKit/DiskArb would let you identify that volume duplication is occurring, which might be useful.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

I suspect what you're referring to here is that standard (vs document) scoped bookmarks can only be opened by the executable that created them, which means a bookmark created by your main app can't be resolved by your helper process.

Yes. Because of that issue, my original design had a fairly convoluted idea for getting those bookmarks to the helper. But in this limited use case, it turned out that none of that (including bookmarks themselves) was necessary.

But since you mentioned document-scoped bookmarks, I should reiterate that I tried those too. They're completely non-functional, for any URL.

Code=256 "Item URL disallowed by security policy"

I won't need this functionality until a 2.0 version of a later project, so I can't spend any time on it now.

That's a totally fair point, but bookmarking "/" WILL work. The fact that it doesn't work now is an unfortunate accident that will be fixed.

Yeah, I get it. But released versions aren't like betas. Once a new beta version drops, I don't have to worry about any previous beta behaviour ever again. But any behaviour in any released version is permanent.

Even when an API bug like this gets fixed, I'll need an OS version check and only use the new behaviour on a newer OS version that supports it.

Neither the Finder nor our open panels present an accurate view of the actual file system.

Yes. I'm aware of all that. But end users might not be.

Thanks for reminding me about /Applications. I need a special warning if users navigate there. Although it isn't an important location for my storage management app, end users think it is, and they would get confused. I have a number of such end user warnings.

DiskImages can make things weird.

Thanks for reminding me about that too! I can just disallow those. They're not applicable to my task.

Yes. Because of that issue, my original design had a fairly convoluted idea for getting those bookmarks to the helper. But in this limited use case, it turned out that none of that (including bookmarks themselves) was necessary.

But since you mentioned document-scoped bookmarks, I should reiterate that I tried those too. They're completely non-functional for any URL.

I'm not sure what you were testing, but they absolutely do work. The main things to be aware of here are:

• You do have to add "com.apple.security.files.bookmarks.document-scope" to your entitlement file yourself, instead of adding it as a capability (r.159787652).

• The object you're using as the bookmark "anchor" needs to be a file, not a directory, and must be a file you already have full read/write access to.

• The object you're targeting needs to be a file as well.

• Document scoped bookmarks are designed to be used to track groups of user files (for example, like an Xcode project), so a small number of directories have been blocked. For example, "/Library/", "/private/", "/Library/", and "/.ssh/" won't work as target paths but will work for the "anchor" file.

Code=256 "Item URL disallowed by security policy"

You'll get this error if the objects aren't files or your target is in a blocked directory.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

You do have to add "com.apple.security.files.bookmarks.document-scope" to your entitlement file yourself,

Already done.

The object you're using as the bookmark "anchor" needs to be a file, not a directory, and must be a file you already have full read/write access to.

Already done.

The object you're targeting needs to be a file as well.

That's an important plot point. My current app looks at folders exclusively. So that's all I tested.

Document scoped bookmarks are designed to be used to track groups of user files (for example, like an Xcode project), so a small number of directories have been blocked.

It sounds like a large number of directories have been blocked - i.e. all of them. Or are these blocked target file prefixes rather than directories?

Ah well, such is life.

I'm working an an iOS/macOS GUI version of a command-line GIS tool. I had wanted to allow the user to specify a directory to be used as a library. Power users could then use my sandboxed and Metal-powered version of the command line app they are already familiar with in this library folder.

When I learned how to actually create a document-scoped bookmark, it seemed like a much better way to go. I could have a little metadata file in my app group directory to host the bookmark. Then, my raster, vector, and AI apps could all use the same library. But that's at least a couple of years out.

You'll get this error if the objects aren't files or your target is in a blocked directory.

That's better than the error message it throws now. But I'm a bit confused about your object/target nomenclature. But I guess it doesn't matter. Directories can't be used in any way with document-scoped bookmarks. That's all I need to know. Thanks!

It sounds like a large number of directories have been blocked - i.e. all of them. Or are these blocked target file prefixes rather than directories?

Looking at my previous post, our editor mangled things a bit. Phrasing things a bit more plainly, document-scoped bookmarks can't track files in "/Library" (either the system or user level), "/private/", or ".ssh". None of those are directories I'd expect the user to be saving "their" data in. I could see <home>/Library being a potential problem, however, that doesn't seem to have been much of an issue in practice since this is the first time I've ever noticed the limitation (and that was simply from looking at code).

That's better than the error message it throws now. But I'm a bit confused about your object/target nomenclature.

Sorry about that, I flipped my terminology mid-post. Restating things:

1. "target” -> the file you’re actually creating a bookmark "to".

2. "anchor” -> the file you're attaching the document scope onto.

So your anchor can be wherever you want, but the target can't be in the directories above. Notably:

When I learned how to actually create a document-scoped bookmark, it seemed like a much better way to go. I could have a little metadata file in my app group directory to host the bookmark.

This would actually work fine, as the anchor could be in the app group directory.

__
Kevin Elliott
DTS Engineer, CoreOS/Hardware

Sorry about that, I flipped my terminology mid-post.

You were pretty clear that neither of them could be directories. But at least it's good to know this before I write 3 separate apps that can't share data.

I can confirm that latest beta does not allow to bookmark the root folder "/" for later access. This leads to an error "The file couldn’t be opened.".

Do you know if this will be fixed before the RC version of macOS?