What does a Mac sandboxed app get access to when the user selects a folder?

Question

I'm reading about Mac app sandboxing and am wondering what exactly happens when a user selects a folder in an NSOpenPanel or NSSavePanel. The “App Sandbox Design Guide” gives the following example:

When a user of your app specifies they want to use a file or a folder, the system adds the associated path to your app’s sandbox. Say, for example, a user drags the ~/Documents folder onto your app’s Dock tile (or onto your app’s Finder icon, or into an open window of your app), thereby indicating they want to use that folder. In response, the system makes the ~/Documents folder, its contents, and its subfolders available to your app.

It's not clear to me what's meant by the “contents” here. Is this limited to seeing what files are in the folder without being able to read what's in those files? Or does this simply mean that the app will be able to read any file that's (recursively) inside the Documents folder (so it can, for example, read both ~/Documents/Foo.txt and ~/Documents/Bar/Baz.txt)? And what about write operations (writing to an existing file, deleting one or creating a new file or folder)?

Answer 1

The app can read all files in the selected folder as well as its subfolders. Same is true for writing, both for new files as well as overwriting existing ones. Deleting is also possible as well as new folder creation, folder movement within the bounds of the folder (or other folders you have the required rights for).

Simply put, you have the freedom to do whatever you want within this folder and its subfolders.

Caveat: When the save panel opens up and it shows Documents as target, it might be ~/Library/Containers/<app signature>/Data/Documents. You may change the location, but the first time I was baffled after the file had successfully been saved but was not located at ~/Documents.