---
name: hd-permissions-mac
description: >
  macOS platform companion to hd-permissions — the Apple-specific half of the
  permission story. The generic skill (adom/hd-bootstrap) covers HD's webview
  auto-grant: inside HD a webview app NEVER sees a "site wants to use your
  microphone/camera/clipboard/location" prompt. THIS skill carries only what's
  macOS-specific: the OS-level TCC privacy model (Screen Recording, Accessibility,
  Automation, Camera, Microphone) granted under System Settings → Privacy &
  Security, how HD preflights/requests them (CGPreflightScreenCaptureAccess,
  AXIsProcessTrustedWithOptions), and that some need a relaunch / a stable signing
  identity to stick. Mirror of hd-permissions-windows (UAC, no per-feature gate).
  Trigger words — macos permissions, TCC, screen recording permission, accessibility
  permission, automation permission, privacy and security, AXIsProcessTrusted,
  CGPreflightScreenCaptureAccess, grant accessibility, relaunch to take effect.
---

# hd-permissions (macOS) — the TCC privacy gates

This is the **macOS half** of `hd-permissions`. The cross-platform contract — HD's
**webview auto-grant** (mic/camera/clipboard/geolocation/notifications/sensors all
ALLOW, so no in-page "site wants to use…" prompt) — is identical on every host and
lives in the generic **hd-permissions** skill. Read that first; this skill only covers
the macOS **OS-level** gates that sit *separately* underneath that auto-grant.

## Two different layers — don't conflate them

- **In-webview permissions** (mic/camera/clipboard/etc.): on macOS HD's webview is
  **WKWebView**, which grants in-page media capture with no per-site prompt — same
  user-facing result as the Windows WebView2 `PermissionRequested` auto-grant. This is
  the generic skill's territory.
- **OS-level TCC permissions:** macOS still gates HD's *process* with the system-wide
  TCC (Transparency, Consent & Control) model. These are real system prompts and live
  under **System Settings → Privacy & Security**. The webview auto-grant does NOT bypass
  them — if HD's process is denied Camera/Mic/Screen Recording at the OS, the in-page
  capture still fails (look here, not at a "denied prompt", per the generic skill).

## The TCC gates HD touches (and how it preflights them)

HD requests/preflights these natively (`mac_input.rs`, exposed as Tauri commands in
`lib.rs`):

| TCC permission | What HD uses it for | How HD checks/requests |
|---|---|---|
| **Accessibility** | synthesize keystrokes / `AXPress` into another app (press Return on Safari's claude.ai Authorize page) to auto-approve OAuth | `AXIsProcessTrustedWithOptions` via `accessibility_trusted(prompt)` → `macos_accessibility_status` |
| **Screen Recording** | screenshot the consent window for the OCR-approve flow | `CGPreflightScreenCaptureAccess` (non-prompting) / `CGRequestScreenCaptureAccess` via `screen_capture_trusted(prompt)` → `macos_screen_recording_status` |
| **Automation** ("control System Events") | the AppleScript/System-Events button-press that approves OAuth | `prime_automation` / `prime_browser_automation` → `macos_prime_automation`, `macos_prime_browser_automation` |
| **Camera / Microphone** | the first time HD's process actually uses the device | one-time system TCC prompt; toggles must be ON for **Hydrogen Desktop** under Privacy & Security |

Preflight (`CGPreflight…`, `AXIsProcessTrusted…` with `prompt=false`) is
**non-prompting** — it reports current state. Passing `prompt=true` shows the system
dialog the first time and adds HD to the relevant Privacy & Security list. HD frontloads
Accessibility (and the Automation consent) in the **pre-login gate** rather than
mid-cascade (`setup_steps_macos.rs`), and can deep-link the user to the exact pane via
`open x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility`
(and the Screen Recording / Automation equivalents).

## Gotchas

- **Some grants need a relaunch.** Screen Recording in particular: after the user toggles
  it on, macOS may not honor it for the already-running process — HD's gate has a
  "stale" path that **relaunches Hydrogen Desktop** (`lib.rs` relaunch command) so the
  new grant takes effect.
- **The grant is bound to the app's code signature.** An adhoc / un-notarized rebuild is
  seen as a "new app" and the Accessibility grant is dropped (`mac_input.rs` signing
  note). A stable Developer ID + notarization is needed for the grant to persist across
  builds — relevant when a dev build keeps re-prompting.
- **Graceful degradation:** if Accessibility / Screen Recording are off, HD still opens
  the sign-in page and starts the flow — the user just approves the browser page
  themselves (no auto-press). It does not hard-block on these (`setup_steps_macos.rs`).

## NOT here (lives in the Windows companion)

Windows has no per-feature OS gate equivalent to TCC — the analog is **UAC** (elevation
for the installer / WSL2 setup), and the WebView2 `PermissionRequested` auto-grant
handler. Screen Recording / Accessibility / Automation consent has no Windows
counterpart. See `hd-permissions-windows`.