Macos privacy permissions workflow

macOS Privacy Permissions Workflow

Purpose

Identify the protected operation, responsible executable, and current public authorization contract before changing code or asking the person to change Privacy & Security settings. Keep project declarations, user consent, managed policy, and runtime success as separate evidence.

When To Use

• Use for macOS privacy authorization failures, permission prompts, Settings entries, tccutil reset, PPPC policy, and responsible-code attribution.
• Use for Accessibility, Automation, Developer Tools, screen/system-audio recording, Input Monitoring, camera, microphone, personal data, Files and Folders, Full Disk Access, App Management, and other current macOS privacy classes.
• Do not use private TCC APIs or database details as an application implementation contract.

Single-Path Workflow

1. Record the exact attempted operation, target resource or process, timestamp, user/session, error domain/code/message, and whether the evidence came from the host, a guest, or a physical Mac.
2. Resolve the responsible code: executable path, bundle identifier, Team ID, designated requirement, signing state, parent/launcher, helper or XPC boundary, and whether the artifact changed. Read references/responsible-code-and-attribution.md.
3. Apply the Apple docs gate through explore-apple-swift-docs. Record the host macOS version/build and selected SDK/Xcode, then verify the current framework API and settings name. Do not promote an internal service string to a public API.
4. Select the class in references/permission-class-matrix.md. Inspect the relevant usage description, entitlement/capability, sandbox state, helper identity, and final signed artifact without treating any declaration as consent.
5. Preflight or read status using the class's documented public API when one exists. Preserve .notDetermined, restricted or managed, denied, limited, and authorized states instead of collapsing them to Boolean access.
6. Request only from the user action that needs access and only when the public API supports requesting. Explain the operation, system UI, denial behavior, later Settings path, and any relaunch/helper restart/logout requirement.
7. For Settings-managed classes such as Full Disk Access, describe the user or MDM decision and the narrow responsible executable. Never invent a self-grant API or grant a broad terminal, IDE, or agent host without explaining its broader authority.
8. Read references/prompting-settings-reset-and-mdm.md before resetting or managing state. Treat tccutil reset as test-state removal, never grant or general status inspection.
9. Reproduce the original operation after the required lifecycle transition. Record the status/preflight result, actual operation result, responsible executable, mutations and approvals, reset/rollback path, and remaining uncertainty.
10. Use the minimum fixture in references/validation-fixtures.md. Obtain explicit approval immediately before any visible prompt, System Settings change, logout, or live-host permission mutation.

Inputs

• attempted operation, target, exact error, and expected user-visible behavior
• app/tool/helper path, bundle identity, signer, launcher, and build transformation history
• macOS build, SDK/Xcode, management state, sandbox state, usage descriptions, and signed entitlements
• current status/preflight output, Settings state, prior prompts/resets, and reproduction environment

Outputs

• responsible-code identity and controlling privacy class
• public status/request contract and required project declarations
• prompt, Settings, MDM, reset, lifecycle, and denial behavior
• reproduced operation result, exact evidence, confidence, and unresolved fidelity gaps

Guards and Stop Conditions

• Do not edit, replace, copy back, or directly query a live TCC database as an app workflow.
• Do not use private TCC.framework APIs or kTCCService* constants in shipping guidance.
• Do not automate System Settings clicks to defeat user choice, repeatedly prompt, or reset a denial without an explicit test reason.
• Do not confuse a usage description, entitlement, sandbox exception, profile payload, or Settings entry with user consent.
• Stop before producing visible permission UI or mutating Gale's active Mac until Gale explicitly approves that exact action.
• Stop when the responsible executable or original protected operation cannot be identified; report the missing evidence instead of guessing a permission.

Fallbacks and Handoffs

• Use macos-sandbox-file-access-workflow when user-selected file access, bookmarks, containers, or App Groups are the actual requirement.
• Use diagnose-apple-entitlements when source, profile, signed entitlement, and runtime state disagree.
• Use apple-developer-provisioning-workflow for account-side capability and profile changes; use Xcode workflows for project edits and builds.
• Use research-macos-security-control for private TCC symbols, database schemas, daemon behavior, or exact-build implementation research.
• Use Cybersecurity Skills for suspicious prompts, unexplained grants, Gatekeeper/XProtect alerts, or host compromise questions.

Customization

Use references/customization-flow.md. The workflow has no runtime knobs; permission behavior must remain tied to the recorded identity, OS build, public API, and user or managed decision.

References

• references/permission-class-matrix.md
• references/responsible-code-and-attribution.md
• references/prompting-settings-reset-and-mdm.md
• references/validation-fixtures.md
• Recommend references/snippets/apple-xcode-project-core.md when the diagnosis leads to an Xcode project change.
• Controlling app access to files in macOS
• Privacy Preferences Policy Control payload