# macOS Permissions

## Overview

This documentation addresses macOS permission management through TCC (Transparency, Consent, and Control), explaining why permission grants can be unstable and how to resolve issues.

## Permission Stability Issues

TCC associates a permission grant with the app's code signature, bundle identifier, and on-disk path. Any changes to these elements cause macOS to treat the application as new, potentially removing previously granted permissions.

## Requirements for Reliable Permissions

- Applications must run from a consistent location
- Bundle identifiers should remain unchanged
- Apps must be properly signed (not ad-hoc signed)
- Code signatures must be consistent across rebuilds using real Apple certificates

## Why Ad-Hoc Signing Fails

Ad-hoc signatures create new identities with each build, causing macOS to forget previous permission grants and potentially hiding permission prompts entirely.

## Troubleshooting Steps

The recovery process involves:

1. Quitting the app
2. Removing it from System Settings privacy controls
3. Relaunching it
4. Re-granting permissions

### Using tccutil

Reset specific permission entries by bundle identifier:

```bash
tccutil reset All bot.molt.mac.debug
```

Or reset specific services:

```bash
tccutil reset Accessibility bot.molt.mac.debug
tccutil reset ScreenCapture bot.molt.mac.debug
```

## Testing Recommendation

For permission testing, developers should use real certificates rather than ad-hoc signatures. Ad-hoc builds are acceptable for casual local testing where permissions aren't critical.