---
name: macos-sandbox-file-access-workflow
description: Design and diagnose macOS file access. Use for App Sandbox, App Groups, user selection, security-scoped bookmarks across relaunches, helpers or extensions, stale access, TCC overlap, POSIX or ACL, Data Vault, and SIP denials.
---

# macOS Sandbox File Access Workflow

## Purpose

Preserve user intent and access lifetime while selecting the smallest supported file-access mechanism. Treat a URL or path as resource identity, not durable authorization, and keep App Sandbox, TCC, POSIX, and mandatory controls distinct.

## When To Use

- Use when a sandboxed Mac app must open, save, import, export, drag, share, or persist access to files or directories.
- Use when access succeeds during selection but fails after relaunch, in a helper, or after a move/rename.
- Use to identify whether a remaining denial is sandbox, TCC, filesystem, volume, coordination, Data Vault, or SIP policy.

## Single-Path Workflow

1. Record the data owner, exact operation, resource type, read/write/execute need, persistence duration, process boundary, distribution channel, macOS build, and exact error.
2. Read `references/sandbox-and-filesystem-control-map.md` and identify every applicable control layer before choosing a capability.
3. Use the app container or a standard supported container-relative directory when it satisfies the feature. Use an App Group only for a real same-team shared-container requirement.
4. Prefer direct user selection through the appropriate open/save panel, document URL, drag/drop, or Photos/File Provider selection surface for external data.
5. Request only the user-selected read-only, read-write, or executable entitlement that the feature actually needs. Do not replace a narrow selection with Full Disk Access.
6. Create a security-scoped bookmark only when access must survive the current interaction or process lifetime. Follow every step in `references/security-scoped-bookmark-lifecycle.md`.
7. For helpers, XPC services, app extensions, or shared containers, use `references/helpers-groups-and-process-boundaries.md`; verify which process resolves and consumes authorization rather than passing a path and assuming authority follows.
8. Perform the narrow operation and balance every successful `startAccessingSecurityScopedResource()` with `stopAccessingSecurityScopedResource()`. Do not retain access indefinitely for convenience.
9. If access still fails, classify the exact denying layer: path resolution/symlink, ownership/mode/ACL, sandbox, TCC Files and Folders/Full Disk Access, mount/volume state, coordination, Data Vault, SIP, or service policy.
10. Validate relaunch, moved/renamed/removed resources, read-only enforcement, helper/extension behavior, revoked/inaccessible access, stale and malformed bookmark recovery, and privacy-safe logging using `references/validation-fixtures.md`.

## Inputs

- resource owner, selection path, operation, persistence need, and distribution channel
- app/helper/extension identities, sandbox entitlements, App Group, and signed artifacts
- bookmark creation/storage/resolution code and exact errors
- macOS build, volume/mount, POSIX/ACL, TCC, Data Vault, and SIP context

## Outputs

- selected access mechanism and least-privilege entitlement set
- bookmark ownership, storage, resolution, lifetime, and repair contract
- process-boundary authorization design
- exact denying layer, reproduced result, privacy-safe evidence, and unresolved gaps

## Guards and Stop Conditions

- Do not treat a path, URL, alias, file ID, or remote identifier as a durable authorization token.
- Do not store only a security-scoped URL or retain access indefinitely.
- Do not claim a bookmark bypasses TCC, Full Disk Access, Data Vaults, SIP, POSIX permissions, ACLs, mounts, or service policy.
- Do not log bookmark bytes or sensitive full paths without a specific privacy-reviewed diagnostic need.
- Do not use Finder Sync as a synchronization engine or access-grant mechanism.
- Stop when the resource owner, operation, persistence duration, or consuming process is unknown.

## Fallbacks and Handoffs

- Use `macos-privacy-permissions-workflow` for Files and Folders, Full Disk Access, or another TCC decision.
- Use `diagnose-apple-entitlements` when source, profile, or final signed sandbox/App Group entitlements disagree.
- Use `file-provider-and-finder-sync-workflow` for remote storage, File Provider domains, or Finder UI decoration.
- Use `app-extension-architecture-workflow` for extension lifecycle/IPC design and Xcode workflows for project edits.
- Use `research-macos-security-control` for private sandbox profiles, extensions, or exact-build Seatbelt behavior.

## Customization

Use `references/customization-flow.md`. The workflow has no runtime knobs; access scope must follow the recorded feature, process, resource, and lifetime.

## References

- `references/sandbox-and-filesystem-control-map.md`
- `references/security-scoped-bookmark-lifecycle.md`
- `references/helpers-groups-and-process-boundaries.md`
- `references/validation-fixtures.md`
- Recommend `references/snippets/apple-xcode-project-core.md` when implementing target entitlements or helper membership.
- [Protecting user data with App Sandbox](https://developer.apple.com/documentation/security/protecting-user-data-with-app-sandbox)
- [Accessing files from the macOS App Sandbox](https://developer.apple.com/documentation/security/accessing-files-from-the-macos-app-sandbox)