---
name: hydrogen-permissions-mac
description: >
  macOS platform companion to hydrogen-permissions — the Apple-specific half of the
  permission story. The generic skill (adom/hd-bootstrap) covers Hydrogen's webview
  auto-grant: inside Hydrogen 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 Hydrogen preflights/requests them (CGPreflightScreenCaptureAccess,
  AXIsProcessTrustedWithOptions), and that some need a relaunch / a stable signing
  identity to stick.
  Trigger words — macos permissions, TCC, screen recording permission, accessibility
  permission, automation permission, privacy and security, AXIsProcessTrusted,
  CGPreflightScreenCaptureAccess, grant accessibility, relaunch to take effect.
---

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

This is the **macOS half** of `hydrogen-permissions`. The cross-platform contract — Hydrogen'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 **hydrogen-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 Hydrogen's webview is
  **WKWebView**, which grants in-page media capture with no per-site prompt — the
  auto-grant behavior described in the generic skill. This is the generic skill's
  territory.
- **OS-level TCC permissions:** macOS still gates Hydrogen'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 Hydrogen'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 Hydrogen touches (and how it preflights them)

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

| TCC permission | What Hydrogen uses it for | How Hydrogen 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 Hydrogen's process actually uses the device | one-time system TCC prompt; toggles must be ON for **Adom Hydrogen** 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 Hydrogen to the relevant Privacy & Security list. Hydrogen 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 — Hydrogen's gate has a
  "stale" path that **relaunches Adom Hydrogen** (`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, Hydrogen 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`).