HelpViewer app can't display our bundled help book on 12.0.1, due to being sandboxed itself.

Question

Created Nov ’21

Replies 6

Boosts 0

Views 1.2k

Participants 2

In our app, we're packaging a help book bundle with the app, which works fine on all our test systems from macOS 10.10 through 11.5.

However, in 12 and 12.0.1, attempting to open the help book via the menu item in the "Help" menu or directly via -[NSApplication showHelp:] will open the builtin HelpViewer app with a blank window, unless the application bundle itself is stored in /Applications. This seems to be due to a sandboxing problem with HelpViewer, where it is not allowed to access the packaged help bundle, if the app is not stored in /Applications.

Here's an excerpt from Console.app when running our app from my desktop and trying the open the help book via the default "Help" menu entry.

error	22:10:48.792960+0100	kernel	Sandbox: HelpViewer(39221) deny(1) file-issue-extension target:/Users/gck/Desktop/OUR_APP.app/Contents/Resources/OUR_APP_Help.help/Contents/Resources/en.lproj class:com.apple.app-sandbox.read
error	22:19:13.577568+0100	kernel	Sandbox: HelpViewer(39861) deny(1) file-read-data /Users/gck/Desktop/OUR_APP.app/Contents/Resources/OUR_APP_Help.help
error	22:19:13.758827+0100	kernel	1 duplicate report for Sandbox: HelpViewer(39861) deny(1) file-read-data /Users/gck/Desktop/OUR_APP.app/Contents/Resources/OUR_APP_Help.help
error	22:19:13.758835+0100	kernel	Sandbox: HelpViewer(39861) deny(1) file-issue-extension target:/Users/gck/Desktop/OUR_APP.app/Contents/Resources/OUR_APP_Help.help/Contents/Resources class:com.apple.app-sandbox.read
error	22:19:13.759459+0100	kernel	Sandbox: HelpViewer(39861) deny(1) file-issue-extension target:/Users/gck/Desktop/OUR_APP.app/Contents/Resources/OUR_APP_Help.help/Contents/Resources/en.lproj class:com.apple.app-sandbox.read

If the app is stored in /Applications, HelpViewer can access the help bundle just fine and displays it properly. All versions of macOS before 12 do not exhibit this problem.

This is quite impactful, since a user downloading our app from the browser (as opposed to the App Store) will typically launch it the first time either from ~/Downloads or drag it to ~/Desktop – We are referring to our help book during the onboarding process, but users on Monterey will only be presented with a white screen in HelpViewer if they open it. We could only display a warning that the app needs to be in /Applications for the help book to work (and get indexed), but this is clearly not the intended behavior.

The app is correctly code-signed and notarized (with stapled receipt).

It is possible that this problem might only occur on arm64, since we currently don't have an x86_64 system with Monterey available for testing.

As a workaround, we can open the help book in the browser on 12.0+ for now, if the app is not launched from /Applications, but that is crummy...

Did anyone encounter the same problem and found a better solution? Is there an entitlement to allow HelpViewer to access the bundled help book in 12.0? Any help/idea would be appreciated much!

Cheers, Georg

Boost

Answer 1

DTS Engineer OP

Apple

Nov ’21

due to being sandboxed itself

This doesn’t look like a sandbox issue but rather a MAC issue. See On File System Permissions.

It is possible that this problem might only occur on arm64

That’s unlikely. Problems like this are usually pretty CPU agnostic.

Does that mean you can reproduce this in your office?

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

0

Answer 2

gck OP

Nov ’21

This doesn’t look like a sandbox issue but rather a MAC issue. See On File System Permissions.

Ah, thank you for this clarification! That's interesting to know!

That’s unlikely. Problems like this are usually pretty CPU agnostic.

Yes, that's what I thought too, but since the only macOS 12 testing device we currently have around is arm64, I wanted to mention it just in case.

Does that mean you can reproduce this in your office?

Yes, absolutely, it's perfectly repeatable for me – so much, that we've overridden -[NSApplication showHelp:] for now on macOS 12 to open the help book in the browser, rather than HelpViewer, because we can't get it to work outside of /Applications.

I've also submitted the issue through FeedbackAssistant (FB9745443) yesterday, by the way, including the full system diagnostics for reference.

0

Answer 3

DTS Engineer OP

Apple

Nov ’21

Yes, absolutely, it's perfectly repeatable for me

OK. In that case I’d definitely consider this to be a bug. Which means that this:

I've also submitted the issue through FeedbackAssistant (FB9745443) yesterday

is the right next step. Thanks!

As a workaround, you might consider distributing your app on a disk image. It’s a pretty common pattern on macOS and, if you include a symlink to /Applications, it encourages the user to copy the app to the Application folder before running it.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

0

Answer 4

gck OP

Nov ’21

As a workaround, you might consider distributing your app on a disk image. It’s a pretty common pattern on macOS and, if you include a symlink to /Applications, it encourages the user to copy the app to the Application folder before running it.

Thanks, that a good tip, and we've been thinking about it before, but we're in the unfortunate situation that a lot of our users are in corporate environments & agencies, where they are frequently not allowed to write to /Applications themselves, but rely on central management. Since we add new features frequently, most keep an "unofficial" download in places like their desktop, so they can receive automatic updates faster (e.g. through our app, rather than having to wait for a centralized rollout). That's why we're not keen on doing the dmg-with-symlink-to-applications trick, because many of our users would get a permission-denied prompt then and think that there's something wrong with the app or the "installation" process.

We've opted to opening the helpbook in the browser on 12.1 for now, adding a sidebar menu resembling what HelpViewer would provide via JS. We'll wait for 12.1 to see if it fixes our issue, and if not, we'll also add a JS-based search functionality, so that we're less dependent on HelpViewer without losing functionality, and as soon as HelpViewer works for us again, we'll just scope the workaround to 12.0–12.x (or 13.x, but hopefully not! :-D )

0

Answer 5

DTS Engineer OP

Apple

Nov ’21

we're in the unfortunate situation that a lot of our users are in corporate environments & agencies, where they are frequently not allowed to write to /Applications themselves

Oh, that’s an interesting wrinkle. Fun fact: ~/Applications is a great location for per-user applications. While it’s not created by default, apps placed there function as well as they would in /Applications.

most keep an "unofficial" download in places like their desktop

And the Desktop is one of the worst places for this stuff )-: because of the MAC support we added in 10.15.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

0

Answer 6

gck OP

Nov ’21

Oh, that’s an interesting wrinkle. Fun fact: ~/Applications is a great location for per-user applications. While it’s not created by default, apps placed there function as well as they would in /Applications.

I know, it's my preferred place to keep apps too, but yeah, it's a bit of a hidden feature, since that folder doesn't exist by default. It would actually be great to make the user-local applications folder more of "a thing" in the future! As an example, I always found it a bit odd that the App Store would install to /Applications/, when it's easily possible to have multiple accounts on a Mac (say, one used by multiple people for testing/debugging), and each account could have a different App Store login with different purchased apps.

It'd also make it easier for our particular scenario, where users usually cannot write to /Applications.

most keep an "unofficial" download in places like their desktop

Yeah! I guess it's just a tiny bit better than keeping it in ~/Downloads. You wouldn't believe how often we've met with our corporate customers, only to discover that their people have been running our apps from ~/Downloads for years :-D

1