Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.md
new file mode 100644
index 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.plist
index 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.yml
index 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 on
diff --git a/packages/desktop/tests/unit/entitlements-helper-split.test.ts b/packages/desktop/tests/unit/entitlements-helper-split.test.ts
index 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);
+ });
});