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
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
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.ymlindex 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 neverenv: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 checksumsshell: bashdiff --git a/.gitignore b/.gitignoreindex 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 deployeddocs/media/*.movdiff --git a/RELEASE.md b/RELEASE.mdindex 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.+---## Requirementsdiff --git a/build/SIGNING.md b/build/SIGNING.mdnew file mode 100644index 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.plistnew file mode 100644index 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.cjsnew file mode 100644index 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.ymlindex eece3bb1..96184df0 100644--- a/electron-builder.yml+++ b/electron-builder.yml@@ -2,6 +2,10 @@ appId: in.munderdiffl.appproductName: Munder Difflincopyright: 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: truemac:category: public.app-category.developer-toolsicon: 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: dmgarch: [universal]diff --git a/package-lock.json b/package-lock.jsonindex 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.jsonindex 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",