From 8dc8397e4a78d3b05377b8bed980b0cc9b510e14 Mon Sep 17 00:00:00 2001 From: MufeezQadri Date: Sat, 18 Jul 2026 17:26:23 +0530 Subject: [PATCH] Document local dev-signing fix for Accessibility permission resets Building from source with the default ad-hoc signature causes macOS to invalidate Accessibility/Microphone/Screen Recording grants on every rebuild, since ad-hoc signatures have no stable identity. Add a CONTRIBUTING.md explaining how to create a local self-signed "FreeFlow Dev" code-signing certificate so rebuilds keep a stable identity and permission grants persist. Co-Authored-By: Claude Sonnet 5 --- CONTRIBUTING.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..80f0f886 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,23 @@ +# Contributing to FreeFlow + +## Building and running locally + +```bash +make run +``` + +This compiles the app and code-signs it with the identity named in `CODESIGN_IDENTITY` (`FreeFlow Dev` by default). + +### Accessibility (or Microphone/Screen Recording) permission keeps disappearing after every rebuild + +If you build from source without a matching signing identity in your keychain, `make` falls back to an ad-hoc signature. Ad-hoc signatures have no stable subject, so macOS treats every rebuild as a new, different app — any Accessibility/Microphone/Screen Recording grant you gave the previous build silently stops applying, even though System Settings may still show an old, now-stale entry. + +**Fix: create a local self-signed code-signing certificate named `FreeFlow Dev`** so every rebuild shares the same signing identity, and macOS remembers your permission grants across rebuilds: + +1. Open **Keychain Access** → menu bar **Keychain Access → Certificate Assistant → Create a Certificate…** +2. Name: `FreeFlow Dev`. Identity Type: **Self Signed Root**. Certificate Type: **Code Signing**. +3. Leave the rest at their defaults and click **Create**. +4. Run `make clean && make` — the build log should now say `build/FreeFlow Dev.app: replacing existing signature` and `codesign -dv "build/FreeFlow Dev.app"` should show `Authority=FreeFlow Dev` instead of an `adhoc` flag. +5. Launch the app and grant Accessibility/Microphone/Screen Recording once more. Future rebuilds will keep this same identity, so you should not need to re-grant them again. + +If you ever see a stale, disabled entry for FreeFlow (or FreeFlow Dev) in System Settings → Privacy & Security, remove it with the **−** button rather than just toggling it — a leftover ad-hoc entry can conflict with the newly-signed build.