Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

build(mac): sign + notarize the macOS app so folder access is granted once

Chaitanya Giri9f098187f744
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2180d2e8..26b335c2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -56,6 +56,17 @@ jobs:
run: npx electron-builder ${{ matrix.args }} --publish never
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ # macOS code signing + notarization. ALL OPTIONAL: if these secrets are
+ # unset (forks, contributors), electron-builder falls back to an unsigned
+ # build and build/notarize.cjs no-ops — CI still succeeds. CSC_* drive the
+ # Developer ID signature; APPLE_* drive notarytool (see build/notarize.cjs).
+ # CSC_LINK = base64 of the "Developer ID Application" .p12
+ # CSC_KEY_PASSWORD = that .p12's export password
+ CSC_LINK: ${{ secrets.APPLE_CERTIFICATE_P12 }}
+ CSC_KEY_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+ APPLE_ID: ${{ secrets.APPLE_ID }}
+ APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+ APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
- name: Generate checksums
shell: bash
diff --git a/.gitignore b/.gitignore
index 2b849c7b..20f5a1db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,15 @@ dist/
.vite/
.env
.env.local
+.env.signing
.gstack/
+# signing / notarization secrets — NEVER commit these
+*.p8
+*.p12
+*.cer
+*.mobileprovision
+build/AuthKey_*.p8
+
# heavy hero source — only the compressed hero.mp4/.webm are deployed
docs/media/*.mov
diff --git a/RELEASE.md b/RELEASE.md
index 4bd9258a..1c8053d6 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -48,6 +48,21 @@ These builds are **not code-signed yet**, so your OS may warn on first open.
- **Windows** — SmartScreen may show "Windows protected your PC" → **More info** → **Run anyway**.
- **Linux** — make the AppImage executable: `chmod +x Munder-Difflin-*.AppImage`, then run it.
+### macOS keeps asking to access your Documents folder?
+
+Because the build is unsigned, macOS can't durably remember the folder-access grant
+(and **App Translocation** runs an un-de-quarantined app from a random path each
+launch), so the privacy prompt can reappear on every agent action. Two fixes:
+
+1. **Stop translocation first:** move the app into **/Applications**, then run
+ `xattr -dr com.apple.quarantine "/Applications/Munder Difflin.app"` and relaunch.
+2. **Grant access once:** open **System Settings → Privacy & Security → Full Disk
+ Access**, click **+**, add **Munder Difflin**, and toggle it on (this covers the
+ `claude` agents it spawns). Alternatively grant **Files and Folders → Documents**.
+
+Once the app is signed + notarized (see the signing note in `electron-builder.yml`),
+this becomes a single one-time prompt with no extra steps.
+
---
## Requirements
diff --git a/build/SIGNING.md b/build/SIGNING.md
new file mode 100644
index 00000000..0363db91
--- /dev/null
+++ b/build/SIGNING.md
@@ -0,0 +1,65 @@
+# macOS code signing & notarization (maintainer runbook)
+
+Signing binds the app's TCC grants (Documents/Desktop/Downloads access) to a
+**stable code signature**, so users are prompted for folder access **once**
+instead of on every agent action. Notarization clears Gatekeeper so the app
+opens without the "unidentified developer" warning.
+
+The build is wired so this is **entirely optional**: with no credentials present,
+`npm run dist:mac` and the release CI both produce a working *unsigned* build
+(`build/notarize.cjs` no-ops, electron-builder falls back to no identity). You
+only need the steps below to ship a *signed* release.
+
+## One-time Apple setup
+
+1. Enrol in the Apple Developer Program ($99/yr) and note your **Team ID**
+ (Apple Developer → Membership).
+2. Create a **Developer ID Application** certificate (Apple Developer →
+ Certificates → +), download it, and double-click to import into your login
+ keychain.
+3. Create an **app-specific password** for notarization at
+ <https://appleid.apple.com> → Sign-In and Security → App-Specific Passwords.
+
+## Local signed build
+
+```sh
+# Export the cert from Keychain Access → My Certificates → "Developer ID
+# Application: …" → right-click → Export → .p12 (set an export password).
+export CSC_LINK="$(base64 -i DeveloperIDApplication.p12)" # or a file path
+export CSC_KEY_PASSWORD="<the .p12 export password>"
+export APPLE_ID="[email protected]"
+export APPLE_APP_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
+export APPLE_TEAM_ID="XXXXXXXXXX"
+npm run dist:mac
+```
+
+Keep these out of git — `.env.signing`, `*.p12`, and `*.p8` are gitignored.
+Source them from a local `.env.signing` if you like.
+
+## CI (tagged release) setup
+
+`.github/workflows/release.yml` reads the secrets below and passes them to
+electron-builder on the macOS runner. Add them under **Settings → Secrets and
+variables → Actions** (all optional; omit them to keep releases unsigned):
+
+| GitHub secret | Value |
+| ------------------------------ | -------------------------------------------------- |
+| `APPLE_CERTIFICATE_P12` | `base64 -i DeveloperIDApplication.p12` (one line) |
+| `APPLE_CERTIFICATE_PASSWORD` | the .p12 export password |
+| `APPLE_ID` | your Apple ID email |
+| `APPLE_APP_SPECIFIC_PASSWORD` | the app-specific password from above |
+| `APPLE_TEAM_ID` | your 10-char Team ID |
+
+Then push a `v*` tag as usual; the produced `.dmg` will be signed, notarized,
+and stapled.
+
+## Verify a build is properly signed
+
+```sh
+codesign --verify --deep --strict --verbose=2 "dist/mac-universal/Munder Difflin.app"
+spctl --assess --type execute --verbose "dist/mac-universal/Munder Difflin.app" # → "accepted, source=Notarized Developer ID"
+xcrun stapler validate "dist/mac-universal/Munder Difflin.app"
+```
+
+See `electron-builder.yml` (the `mac:` block) and `build/notarize.cjs` for how
+these credentials are consumed.
diff --git a/build/entitlements.mac.plist b/build/entitlements.mac.plist
new file mode 100644
index 00000000..79a88e1e
--- /dev/null
+++ b/build/entitlements.mac.plist
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <!-- Munder Difflin is NOT App-Sandboxed: it spawns `claude` agents and other
+ child processes that must read/write the user's own project folders.
+ These hardened-runtime entitlements let Electron + node-pty run and let
+ the spawned agents inherit this app's TCC responsibility, so the user is
+ prompted for folder access ONCE (bound to this app), not per agent. -->
+ <key>com.apple.security.cs.allow-jit</key>
+ <true/>
+ <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+ <true/>
+ <key>com.apple.security.cs.allow-dyld-environment-variables</key>
+ <true/>
+ <!-- Required so the app can load the native node-pty module and spawn the
+ `claude` CLI (signed by a different team) without library-validation
+ killing the child — also keeps the app as the responsible process. -->
+ <key>com.apple.security.cs.disable-library-validation</key>
+ <true/>
+ <!-- Persist user-granted file access (the "Documents folder" grant). -->
+ <key>com.apple.security.files.user-selected.read-write</key>
+ <true/>
+ <!-- Child processes inherit the parent's sandbox/TCC context (no-op outside
+ the sandbox, harmless to include for inherited child entitlements). -->
+ <key>com.apple.security.inherit</key>
+ <true/>
+</dict>
+</plist>
diff --git a/build/notarize.cjs b/build/notarize.cjs
new file mode 100644
index 00000000..45eafc7a
--- /dev/null
+++ b/build/notarize.cjs
@@ -0,0 +1,52 @@
+// electron-builder `afterSign` hook — notarize + staple the macOS app.
+//
+// It runs ONLY when notarization credentials are present in the environment, so
+// contributors without an Apple account can still `npm run dist:mac` and get a
+// working (unsigned) build — this just no-ops. With a Developer ID cert in the
+// keychain + the env vars below, the produced .app/.dmg is signed, notarized,
+// and stapled, so end users get a single one-time macOS access prompt.
+//
+// Credentials (set whichever pair you use):
+// App-specific password: APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID
+// App Store Connect key: APPLE_API_KEY (path to .p8), APPLE_API_KEY_ID, APPLE_API_ISSUER
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+
+exports.default = async function notarizing(context) {
+ const { electronPlatformName, appOutDir } = context;
+ if (electronPlatformName !== 'darwin') return; // mac only
+
+ const {
+ APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID,
+ APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER
+ } = process.env;
+
+ const hasPassword = !!(APPLE_ID && APPLE_APP_SPECIFIC_PASSWORD && APPLE_TEAM_ID);
+ const hasApiKey = !!(APPLE_API_KEY && APPLE_API_KEY_ID && APPLE_API_ISSUER);
+ if (!hasPassword && !hasApiKey) {
+ console.log('[notarize] no APPLE_* credentials in env — skipping notarization (build stays unsigned).');
+ return;
+ }
+
+ let notarize;
+ try {
+ ({ notarize } = require('@electron/notarize'));
+ } catch {
+ console.warn('[notarize] @electron/notarize not installed — run `npm install`. Skipping.');
+ return;
+ }
+
+ const appName = context.packager.appInfo.productFilename;
+ const appPath = path.join(appOutDir, `${appName}.app`);
+
+ const creds = hasApiKey
+ ? { appleApiKey: APPLE_API_KEY, appleApiKeyId: APPLE_API_KEY_ID, appleApiIssuer: APPLE_API_ISSUER }
+ : { appleId: APPLE_ID, appleIdPassword: APPLE_APP_SPECIFIC_PASSWORD, teamId: APPLE_TEAM_ID };
+
+ console.log(`[notarize] submitting ${appName}.app to Apple via notarytool (this can take a few minutes)…`);
+ await notarize({ tool: 'notarytool', appPath, ...creds });
+
+ console.log('[notarize] stapling ticket to the app…');
+ execFileSync('xcrun', ['stapler', 'staple', appPath], { stdio: 'inherit' });
+ console.log('[notarize] done — app is signed, notarized, and stapled.');
+};
diff --git a/electron-builder.yml b/electron-builder.yml
index eece3bb1..96184df0 100644
--- a/electron-builder.yml
+++ b/electron-builder.yml
@@ -2,6 +2,10 @@ appId: in.munderdiffl.app
productName: Munder Difflin
copyright: Copyright © 2026 Chaitanya Giri
+# Notarize + staple after signing, but only when APPLE_* creds are in the env
+# (the hook no-ops otherwise, so contributor builds still work). Root-level hook.
+afterSign: build/notarize.cjs
+
# electron-vite emits the app into out/; package exactly that plus what the
# runtime needs. node-pty is native, so keep it out of the asar.
directories:
@@ -24,8 +28,29 @@ npmRebuild: true
mac:
category: public.app-category.developer-tools
icon: build/icon.icns
- # Unsigned for now (no Developer ID). Gatekeeper note is in RELEASE.md.
- identity: null
+ # Declare WHY the app touches the user's folders. macOS shows these strings in
+ # the privacy prompt and, for a signed app, remembers the grant — so the user
+ # is asked ONCE instead of on every agent action.
+ extendInfo:
+ NSDocumentsFolderUsageDescription: "Munder Difflin runs your Claude Code agents, which read and write files in the project folders you point them at."
+ NSDesktopFolderUsageDescription: "Munder Difflin's agents may work on projects located on your Desktop."
+ NSDownloadsFolderUsageDescription: "Munder Difflin's agents may work on projects located in your Downloads."
+ NSRemovableVolumesUsageDescription: "Munder Difflin's agents may work on projects located on external volumes."
+ NSNetworkVolumesUsageDescription: "Munder Difflin's agents may work on projects located on network volumes."
+ # Hardened runtime + entitlements so the spawned `claude` agents inherit this
+ # app's TCC responsibility (one grant covers them all) and node-pty can load.
+ hardenedRuntime: true
+ entitlements: build/entitlements.mac.plist
+ entitlementsInherit: build/entitlements.mac.plist
+ gatekeeperAssess: false
+ # Signing: TCC binds a remembered grant to a STABLE code signature, so a signed
+ # build is asked for folder access ONCE. The "Developer ID Application" cert is
+ # auto-discovered from the login keychain (CSC_IDENTITY_AUTO_DISCOVERY). If no
+ # cert is found, electron-builder warns and produces an unsigned build, so
+ # contributors without an Apple account can still build.
+ # To sign: install your "Developer ID Application" cert into the keychain.
+ # (Override with CSC_LINK=<path-to.p12> + CSC_KEY_PASSWORD for CI.)
+ # Notarization happens in the root-level `afterSign` hook (top of this file).
target:
- target: dmg
arch: [universal]
diff --git a/package-lock.json b/package-lock.json
index 32b7f31c..25e94d50 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "munder-difflin",
- "version": "0.1.2",
+ "version": "0.1.3",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "munder-difflin",
- "version": "0.1.2",
+ "version": "0.1.3",
"hasInstallScript": true,
"dependencies": {
"@codemirror/lang-css": "^6.3.1",
@@ -31,6 +31,7 @@
"zustand": "^4.5.5"
},
"devDependencies": {
+ "@electron/notarize": "^2.5.0",
"@electron/rebuild": "^3.7.0",
"@types/node": "^22.7.5",
"@types/react": "^18.3.11",
diff --git a/package.json b/package.json
index 432df400..8bc88f83 100644
--- a/package.json
+++ b/package.json
@@ -46,6 +46,7 @@
"zustand": "^4.5.5"
},
"devDependencies": {
+ "@electron/notarize": "^2.5.0",
"@electron/rebuild": "^3.7.0",
"@types/node": "^22.7.5",
"@types/react": "^18.3.11",