/native

App Sandbox — Entitlements, Powerbox, Bookmarks, TCC

Production reference for scoping App Sandbox entitlements on macOS, resolving file access through Powerbox, managing security-scoped bookmarks across launches, and navigating TCC-protected resources. Companion to reference/distribution.md (hardened runtime is a separate system — see § 6) and reference/xpc-helpers.md (app groups feed shared-container IPC).

Scope: App Sandbox (com.apple.security.* sandbox keys) and TCC (Info.plist usage-description strings + user-approved system settings). Signing/notarization mechanics live in reference/macos-xcrun-cli.md; the ship decision matrix lives in reference/distribution.md.

1. Enabling the Sandbox

• Xcode target → Signing & Capabilities → App Sandbox capability, or hand-edit *.entitlements:

<key>com.apple.security.app-sandbox</key>
<true/>

• com.apple.security.app-sandbox is mandatory for Mac App Store distribution; optional (but recommended) for Developer ID direct distribution.
• Every entitlement below is inert unless app-sandbox is true.

2. File-Access Entitlement Catalog

Rule of thumb: prefer files.user-selected.* + a persisted security-scoped bookmark over any assets.*/files.downloads.* blanket grant — the blanket grants exist for library-management apps (Photos-like, Music-like), not general-purpose apps that merely read a file from those folders occasionally.

3. Network, Device, and Personal-Information Entitlements

4. Temporary Exception Entitlements

Escape hatches for capabilities the standard catalog does not cover. App Review scrutinizes every one of these — justify in App Store Connect notes, and treat as a signal the app may need architectural rework (e.g. an XPC helper outside the sandbox) rather than a permanent fixture.

If a temporary-exception entitlement is doing permanent load-bearing work, that is itself the signal to reconsider architecture — most legitimate uses resolve to a proper XPC service (reference/xpc-helpers.md) or a narrower standard entitlement.

5. Powerbox and Open/Save Panel Behavior

• Under App Sandbox, NSOpenPanel/NSSavePanel are rendered by Powerbox (a separate, non-sandboxed system process), not by the app itself — this is why sandboxed apps can show file pickers rooted anywhere on disk despite the sandbox otherwise blocking that path.
• A user's selection in the panel is what grants the sandbox extension for that path — the grant does not exist before the user picks, and does not persist past the extension's lifetime unless captured as a security-scoped bookmark (§ 6).
• Drag-and-drop of a Finder item into the app grants the same kind of transient sandbox extension as a Powerbox selection — capture it the same way if persistence is needed.
• Panels configured with directoryURL pointing outside any entitled location still work because Powerbox — not the app process — resolves and renders the directory listing.

6. Security-Scoped Bookmarks — Full Lifecycle

Bookmarks are the mechanism for persisting Powerbox-granted file access across app relaunches without re-prompting the user every time.

6.1 Create (at time of Powerbox grant)

func makeBookmark(for url: URL) throws -> Data {
    try url.bookmarkData(
        options: .withSecurityScope,
        includingResourceValuesForKeys: nil,
        relativeTo: nil
    )
}

• Use .withSecurityScope (not the vanilla, non-scoped bookmark option) — the vanilla form does not carry sandbox-extension rights.
• Persist Data in UserDefaults, a plist, or a document's own file format (for document-scoped bookmarks).

6.2 Persist

Store the bookmark Data keyed by a stable identifier (e.g. document ID, or the resolved path as a cache key). Do not store the raw URL.path string as your only record — paths can move; bookmarks track the file through renames/moves within the same volume.

6.3 Resolve + Start Access (on every relaunch, before touching the file)

func resolveAndAccess(_ bookmark: Data) throws -> URL? {
    var isStale = false
    let url = try URL(
        resolvingBookmarkData: bookmark,
        options: .withSecurityScope,
        relativeTo: nil,
        bookmarkDataIsStale: &isStale
    )
    guard url.startAccessingSecurityScopedResource() else {
        return nil  // extension failed to start — treat as access denied, re-prompt via picker
    }
    if isStale {
        // Refresh: re-create the bookmark from `url` and persist it, but the current
        // access grant from startAccessingSecurityScopedResource() above is still valid.
    }
    return url
}

6.4 Stop Access

defer { url.stopAccessingSecurityScopedResource() }

• The access-count pitfall: startAccessingSecurityScopedResource()/stopAccessingSecurityScopedResource() calls are reference-counted per URL instance, not globally per path. Calling start twice on two separate URL instances resolved from the same bookmark, then stop once, leaves one grant open — but calling stop without a matching start on the same instance is a silent no-op, not an error. Always pair start/stop 1:1 on the exact URL value in scope, and prefer a defer immediately after a successful start so the pairing cannot be skipped by an early return.
• Do not call start/stop around every file operation in a tight loop — resolve once, hold the access for the duration of the logical operation (e.g. the whole document session), then stop.

6.5 Staleness Handling

• bookmarkDataIsStale becomes true when the underlying file moved/renamed since the bookmark was created but the system could still relocate it (rename-tracking succeeded, the recorded path is now out of date).
• On isStale == true: re-create the bookmark from the resolved url and overwrite the persisted Data — the resolve+access call that produced the stale flag still succeeded, so this is a background refresh, not a failure path.
• Resolution failure (thrown error, not just isStale) means the file was deleted, is on unmounted external/network media, or the bookmark is fundamentally invalid — fall back to re-prompting via NSOpenPanel.

7. App Group Containers + Shared UserDefaults

• Entitlement: com.apple.security.application-groups (array of group identifiers, e.g. group.com.example.myapp).
• Grants a shared container directory (FileManager.default.containerURL(forSecurityApplicationGroupIdentifier:)) reachable by every sandboxed process (main app, XPC services, extensions) in the same group — the standard channel for sharing files or a SQLite store between an app and its helper.
• Shared preferences: UserDefaults(suiteName: "group.com.example.myapp") reads/writes a preferences domain scoped to the group rather than the individual bundle ID — use this instead of com.apple.security.temporary-exception.shared-preference.read-write when both processes are yours.
• App groups are the standard IPC substrate feeding XPC services and SMAppService helpers — see reference/xpc-helpers.md § app-group-backed communication.

8. TCC-Protected Resources and Purpose Strings

TCC (Transparency, Consent, and Control) prompts are a layer on top of sandbox entitlements — an entitlement grants the sandbox extension category; the Info.plist usage-description string is what triggers and populates the user-facing consent dialog. Both are required together for camera/microphone/contacts/calendar/location.

8.1 Mac-Specific TCC Categories with NO Programmatic Prompt

These cannot be requested via an Info.plist key or an API call that raises a system dialog. The app can only detect status and direct the user to System Settings → Privacy & Security to grant manually:

Design implication: any feature depending on these four must ship a clear in-app explanation before deep-linking to System Settings — there is no way to fold the ask into a native consent sheet.

9. Hardened Runtime vs. App Sandbox — Distinct Systems

These are two independent Apple security systems that both live in the same .entitlements file and get confused constantly:

A com.apple.security.cs.* key with app-sandbox absent or false is completely valid and common for Developer ID-only apps that skip the sandbox but still need notarization's hardened-runtime prerequisite.

10. Sandbox-Incompatible Features

Sources

• App Sandbox | Apple Developer Documentation (accessed 2026-07)
• Security entitlements | Apple Developer Documentation (accessed 2026-07)
• Enabling App Sandbox — Entitlement Key Reference (archive)
• App Sandbox Temporary Exception Entitlements (archive)
• NSCalendarsFullAccessUsageDescription | Apple Developer Documentation
• NSCalendarsWriteOnlyAccessUsageDescription | Apple Developer Documentation
• Hardened Runtime | Apple Developer Documentation (accessed 2026-07)
• Configuring the hardened runtime | Apple Developer Documentation
• WWDC — "What's new in privacy" / "Explore App Sandbox and TCC" sessions (Apple Developer video library, cross-reference current-year session for macOS 14+ Calendar/Reminders split)
• Cross-reference: reference/distribution.md (hardened runtime + notarization flow), reference/macos-xcrun-cli.md (codesign --entitlements inspection), reference/xpc-helpers.md (app-group-backed IPC)