Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(desktop): add microphone entitlement for TUI-launched tools (#2946)
serafin-garcia151e8606c21e
diff --git a/.changeset/desktop-microphone-entitlement.md b/.changeset/desktop-microphone-entitlement.mdnew file mode 100644index 000000000..580f12cca--- /dev/null+++ b/.changeset/desktop-microphone-entitlement.md@@ -0,0 +1,33 @@+---+'@inkeep/open-knowledge-desktop': patch+'@inkeep/open-knowledge': patch+---++Fix microphone access for CLI tools run in the OpenKnowledge terminal on macOS.++Any tool that asked for the microphone from a shell launched inside the app+failed silently. No permission dialog appeared, OpenKnowledge never showed up+under System Settings → Privacy & Security → Microphone, and from the tool's+side recording simply captured silence with no error — so there was no way to+grant access and no signal that anything was wrong.++macOS attributes a permission request to the *responsible process* — the+top-level app that started the chain — not to the process that actually asked.+A tool running in the terminal therefore requests the microphone as+OpenKnowledge. Under Hardened Runtime the app must carry+`com.apple.security.device.audio-input` to be eligible to prompt at all; the+app was missing it, so macOS denied every request without ever showing a+dialog. The entitlement is now declared on the main app bundle, matching how+VS Code, Zed, Ghostty, and Cursor ship the same capability.++The consent dialog's text is now declared by the app as well. It previously+fell through to Electron's stock string ("This app needs access to the+microphone"), which described the wrong thing — the app records no audio of+its own. It now reads "A program running in OpenKnowledge's terminal wants to+use the microphone," so the permission being granted is accurate at the moment+it is granted. Granting it covers any tool run in the terminal; macOS shows the+recording indicator whenever the microphone is live, and access stays+revocable in System Settings.++The entitlement is deliberately scoped to the main app bundle and not to+helper processes, and the camera equivalent is not included.diff --git a/packages/desktop/build/entitlements.mac.plist b/packages/desktop/build/entitlements.mac.plistindex 300be6f2b..15c0eb410 100644--- a/packages/desktop/build/entitlements.mac.plist+++ b/packages/desktop/build/entitlements.mac.plist@@ -12,6 +12,35 @@<true/><key>com.apple.security.files.bookmarks.app-scope</key><true/>+ <!--+ Microphone. This app never opens an audio device itself — the+ entitlement exists for CLI tools the user runs in the docked+ terminal (agent CLIs with voice input, etc.).++ macOS TCC does not evaluate the process making the request. It walks+ up to the RESPONSIBLE process — the top-level .app bundle — and+ checks that bundle's entitlements and usage description. So a mic+ request from a PTY grandchild is authorized here, on the main+ binary, and nowhere else. The child needs no entitlement of its own.++ Under Hardened Runtime this key is what makes the app eligible to+ prompt at all; without it tccd denies silently, no dialog appears,+ and the app never lists in Privacy & Security > Microphone. It is a+ Hardened Runtime entitlement, not an App Sandbox one — the sandbox+ spelling (`device.microphone`) is only needed alongside it when+ `com.apple.security.app-sandbox` is present, which it is not here.++ Deliberately absent from `entitlements.mac.inherit.plist`: under the+ responsible-process model helpers do not need it, and helper+ over-entitlement has caused an AMFI launch failure here before. The+ allowlist assertion in `tests/unit/entitlements-helper-split.test.ts`+ fails on any helper key not in its required set, so adding it there+ stays a conscious decision. Paired with `NSMicrophoneUsageDescription`+ under `mac.extendInfo` in `electron-builder.yml` — the entitlement+ authorizes the prompt, that string is what the prompt says.+ -->+ <key>com.apple.security.device.audio-input</key>+ <true/><key>com.apple.developer.associated-domains</key><array><string>applinks:openknowledge.ai</string>diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.ymlindex da67c2ed6..3a7b0aa47 100644--- a/packages/desktop/electron-builder.yml+++ b/packages/desktop/electron-builder.yml@@ -288,6 +288,19 @@ mac:extendInfo:NSUserActivityTypes:- NSUserActivityTypeBrowsingWeb+ # The text of the macOS microphone consent dialog. Declared here rather+ # than left to Electron's stock Info.plist, whose default ("This app+ # needs access to the microphone") describes the wrong thing: the app+ # records no audio of its own, and what the user is actually granting is+ # mic access to whatever CLI they run in the docked terminal. The consent+ # dialog is the only place that distinction is ever shown, so the string+ # names it. Pairs with `com.apple.security.device.audio-input` in+ # `build/entitlements.mac.plist`, but the two fail differently: without+ # the entitlement tccd denies silently and no dialog appears at all;+ # without this key the dialog still appears, having fallen back to the+ # stock Electron string, and misdescribes what is being granted.+ NSMicrophoneUsageDescription: >-+ A program running in OpenKnowledge's terminal wants to use the microphone.# Notarization is invoked from `scripts/afterSign.mjs` per spec §8.9 (custom# afterSign pipeline) — NOT electron-builder's built-in notarize. Setting# `mac.notarize: true` would double-notarize. The afterSign script gates ondiff --git a/packages/desktop/tests/unit/entitlements-helper-split.test.ts b/packages/desktop/tests/unit/entitlements-helper-split.test.tsindex 158b89884..10bc41ce3 100644--- a/packages/desktop/tests/unit/entitlements-helper-split.test.ts+++ b/packages/desktop/tests/unit/entitlements-helper-split.test.ts@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, test } from 'vitest';+import { parse as parseYaml } from 'yaml';/*** Helper-process entitlements MUST NOT include restricted entitlements (those@@ -98,6 +99,26 @@ const HELPER_REQUIRED_KEYS = ['com.apple.security.inherit',] as const;+/**+ * Resource-access entitlements the MAIN app must carry on behalf of the+ * processes it is responsible for, distinct from HELPER_FORBIDDEN_KEYS —+ * these are not illegal on a helper, just unnecessary there.+ *+ * `device.audio-input` exists for CLI tools the user runs in the docked+ * terminal, not for the app itself (it opens no audio device). macOS TCC+ * attributes a child's request to the responsible process — the top-level+ * .app — so the entitlement is only load-bearing on the main binary.+ * Dropping it is a SILENT failure: no dialog, no error, and the app never+ * appears in Privacy & Security > Microphone. That silence is why this is+ * pinned rather than left to review.+ *+ * The helper side needs no matching forbidden-key entry: the allowlist+ * assertion below already fails on any helper key outside+ * HELPER_REQUIRED_KEYS, so putting this on a helper stays a conscious+ * decision requiring a test edit.+ */+const MAIN_REQUIRED_RESOURCE_KEYS = ['com.apple.security.device.audio-input'] as const;+function extractKeys(plistContent: string): string[] {// Match `<key>some.key.name</key>` — XML plist canonical form. Tolerates// arbitrary whitespace + indentation. Not a full plist parser; the@@ -209,4 +230,43 @@ describe('macOS helper-process entitlements (Tahoe AMFI compliance)', () => {const unexpected = keys.filter((k) => !allowed.has(k));expect(unexpected, `Unexpected keys in helper plist: ${unexpected.join(', ')}`).toHaveLength(0);});++ test('main-app plist carries the resource-access entitlements brokered for child processes', () => {+ const content = readFileSync(mainPlist, 'utf8');+ const keys = extractKeys(content);+ for (const required of MAIN_REQUIRED_RESOURCE_KEYS) {+ expect(keys, `${required} must appear in main-app entitlements`).toContain(required);+ }+ });++ test('electron-builder.yml declares the microphone usage description under mac.extendInfo', () => {+ // The other half of the pair: the entitlement makes the app eligible to+ // prompt, this string is the prompt's text. It fails differently from a+ // missing entitlement — the dialog still appears, having fallen back to+ // the stock Electron string, and misdescribes the grant — so the+ // entitlement assertion above cannot stand in for this one.+ //+ // Asserted as "declared in this file" rather than "present in the built+ // Info.plist" for that same reason: the stock default means a+ // build-output check would stay green after this key was deleted here.+ //+ // Parsed rather than regex-matched because `mac.extendInfo` is the ONLY+ // block electron-builder merges into the macOS Info.plist. A key that+ // survives a YAML refactor at the wrong nesting depth — de-indented to+ // top level, or landed under `win:`/`linux:` — is inert, and a+ // file-wide text match would stay green while the packaged app silently+ // reverted to the stock string. That is the same invisible-failure class+ // this entitlement exists to fix, so the assertion is structural.+ const config = parseYaml(readFileSync(builderYml, 'utf8')) as {+ mac?: { extendInfo?: Record<string, unknown> };+ };+ const usage = config.mac?.extendInfo?.NSMicrophoneUsageDescription;+ expect(typeof usage, 'NSMicrophoneUsageDescription must be a string under mac.extendInfo').toBe(+ 'string',+ );+ expect(+ (usage as string).trim().length,+ 'NSMicrophoneUsageDescription must not be empty',+ ).toBeGreaterThan(0);+ });});