Eve library

macOS Hardened Runtime, Entitlements, and Notarization Recovery (180.C.26.11)

Guide

Revision 1

On this page

Status: 180.C.26.11 implementation.

This document specifies the macOS hardened runtime posture for the Bellona Remote Host: the entitlements it must (and must not) carry, the deliberate decision to ship not sandboxed, the NSScreenRecordingUsageDescription / Accessibility usage rationale tied to the host's real capture/automation code, and the step-by-step notarization-failure recovery runbook.

It complements — and does not replace — the packaging/signing plan in macos-packaging-and-notarization-plan.md (the artifact list, signing order, and notarytool commands) and the cross-platform permission model in host-permission-abstraction.md.

1. What the host actually does (the capability basis)#

Every entitlement and usage-description below is justified by real host code, not boilerplate. The relevant capabilities and where they live:

Capability Host code macOS authority
Screen capture apps/bellona/remote-host/src/host-runtime-bridge.ts → macHostScreenCaptureCapability() (backend: 'screencapturekit', gatingPermission: 'screen-recording') TCC Screen Recording
Screen-recording grant probe apps/bellona/remote-host/src/macos-permissions.ts → screenRecordingSwiftProbe calling CGPreflightScreenCaptureAccess() TCC Screen Recording
Synthetic input desktop input commands (desktop-click.ts, desktop-type.ts) routed through the host runtime TCC Accessibility
Accessibility grant probe apps/bellona/remote-host/src/macos-permissions.ts → accessibilitySwiftProbe calling AXIsProcessTrusted() TCC Accessibility
Launch / automate DCC apps apps/bellona/remote-host/src/host-runtime-bridge.ts → createMacHostProcessLauncher() (open / open -a) TCC Automation (per-app)
File read/write for assets apps/bellona/remote-host/src/file-adapter.ts TCC Files & Folders / Full Disk Access
Loopback gateway/bridge transport gateway-connection.ts, the Blender/Unreal bridges on 127.0.0.1 none (loopback)

The first-run onboarding flow that walks an operator through granting these is apps/bellona/remote-host/src/first-run-onboarding.ts (planFirstRunOnboarding / diagnoseMissingPermissions, 180.C.26.03), driven by the platform matrix PLATFORM_PERMISSION_MATRIX in libs/bellona/host-runtime/src/host-platform.ts.

2. Hardened runtime#

All distributed Bellona Mach-O code — the Bellona Remote Host.app bundle, the native helper executables (bellona-desktop-helper, the stream helper), and any nested dylibs — is signed with the hardened runtime enabled (codesign --options runtime). This is mandatory: Apple's notary service rejects software that is not hardened-runtime-signed. The exact codesign invocations are in macos-packaging-and-notarization-plan.md §Command Skeleton.

Hardened runtime turns on a set of protections by default (library validation, hardened memory, no DYLD environment injection, no unsigned executable memory). The host does not need to disable any of them, so it ships with no hardened-runtime exceptions — there is no com.apple.security.cs.* opt-out in its entitlements. That is a deliberate security property: a remote-control host that an operator drives is exactly the kind of process that must keep library validation on.

2.1 Entitlements the host carries#

The signing entitlements file (packaging/macos/entitlements/bellona-remote-host.entitlements, referenced by the packaging plan) is intentionally minimal:

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTD/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <!-- App Sandbox is intentionally NOT enabled (see §3). -->
  <key>com.apple.security.app-sandbox</key>
  <false/>

  <!-- The host opens a loopback TCP connection to the gateway and to the
       Blender/Unreal localhost bridges; outgoing client networking. -->
  <key>com.apple.security.network.client</key>
  <true/>

  <!-- The host accepts loopback connections from the in-process bridges and the
       local Control Room; incoming server networking. -->
  <key>com.apple.security.network.server</key>
  <true/>

  <!-- NO hardened-runtime exceptions:
       no com.apple.security.cs.disable-library-validation
       no com.apple.security.cs.allow-dyld-environment-variables
       no com.apple.security.cs.allow-unsigned-executable-memory
       no com.apple.security.cs.allow-jit
       The host neither loads third-party plug-in bundles into its own process
       nor JITs code, so none of these are warranted. -->
</dict>
</plist>

The native helpers use a sibling file (packaging/macos/entitlements/bellona-desktop-helper.entitlements) with the same posture: hardened runtime on, no exceptions. Screen capture and synthetic input are not entitlements — they are TCC runtime grants (§4), so they never appear here.

2.2 Entitlements the host deliberately does NOT carry#

  • No com.apple.security.cs.disable-library-validation. The host loads no third-party bundles into its own address space; the DCC adapters talk to Blender/Unreal over a socket, not by injecting code.
  • No com.apple.security.automation.apple-events blanket grant. Automation is a per-application TCC prompt (createMacHostProcessLauncher shells open), not a process-wide entitlement, so the host stays least-privilege.
  • No com.apple.security.cs.allow-jit / …allow-unsigned-executable-memory. The Node host runtime does not require JIT entitlements for its workload.

3. Sandbox vs. not-sandboxed — the rationale#

The Bellona Remote Host ships NOT sandboxed. This is a considered decision, required by what the product is, and is recorded here so it is auditable.

The App Sandbox is fundamentally incompatible with a general-purpose remote-control host:

  1. Screen capture of arbitrary applications. A sandboxed app can capture only within the sandbox's mediated entitlements; the host must capture the whole desktop and any DCC window via ScreenCaptureKit (macHostScreenCaptureCapability), which requires the TCC Screen Recording grant that a sandboxed app cannot use the same way.
  2. Synthetic input into other applications. AXIsProcessTrusted() / Accessibility-driven input (the desktop-* commands) targets other apps' UI — categorically outside a sandbox's process boundary.
  3. Launching and automating arbitrary DCC apps. open / open -a (createMacHostProcessLauncher) starts Blender/Unreal anywhere on disk; the sandbox forbids launching arbitrary executables.
  4. Reading/writing project files anywhere the operator chooses. The file adapter operates on user-selected project trees, not a sandbox container.

A sandboxed build would therefore be a different, lesser product that cannot perform its core function. Instead of the sandbox, the host relies on:

  • TCC for the high-risk capabilities (Screen Recording, Accessibility, Automation, Files & Folders) — the OS still gates each, the user still explicitly grants each, and the host detects and surfaces the grant state (createRemoteHostMacPermissionDetector).
  • Hardened runtime with no exceptions (§2) for binary integrity.
  • Per-command approval inside Bellona — note that even a granted TCC capability maps to requires-approval, never an auto-allow, in hostPermissionReportToRemotePermissions (libs/bellona/host-runtime/src/permission-provider.ts). The OS grant is necessary but not sufficient; Bellona's own approval gate is the second lock.

Not-sandboxed software is fully notarizable; the sandbox is not a notarization requirement. The trade-off (more host capability, no container isolation) is mitigated by TCC + hardened runtime + Bellona's approval gate.

4. Usage-description (purpose string) rationale#

macOS shows the app's purpose strings in the TCC consent prompts. Because the host is not sandboxed, the grants are TCC runtime grants rather than entitlements, but the Info.plist usage descriptions are still required — TCC refuses to prompt (and recent macOS will terminate the process) for a capability with no purpose string. Each string below is written to match the host's real behavior:

Info.plist key Value (purpose string) Justified by
NSScreenRecordingUsageDescription "Bellona Remote Host captures this Mac's screen so an approved remote operator can see the desktop and the creative application being controlled. Capture is gated by macOS Screen Recording and by Bellona's per-command approval." macHostScreenCaptureCapability() / CGPreflightScreenCaptureAccess()
NSAccessibilityUsageDescription (plus the AX trust prompt) "Bellona Remote Host sends keyboard and mouse input to perform the remote actions you approve. Synthetic input is gated by macOS Accessibility and by Bellona's per-command approval." AXIsProcessTrusted() + desktop-click.ts / desktop-type.ts
NSAppleEventsUsageDescription "Bellona Remote Host launches and controls Blender and Unreal on your behalf. Each application is authorized through the per-app macOS Automation prompt." createMacHostProcessLauncher() (open / Apple Events)
NSDesktopFolderUsageDescription, NSDocumentsFolderUsageDescription, NSDownloadsFolderUsageDescription "Bellona Remote Host reads and writes the project files for assets you ask it to open, render, or export." file-adapter.ts
NSLocalNetworkUsageDescription "Bellona Remote Host discovers and peers with other Bellona endpoints on your local network." LAN discovery / pairing (host-discovery.ts)

These strings are user-facing security copy: they name the gating mechanism (the TCC grant) and Bellona's own approval gate, so the consent prompt is honest about the two-lock model.

5. Notarization-failure recovery#

When xcrun notarytool submit … --wait returns Invalid (or stapling/Gatekeeper assessment later fails), follow this runbook. The packaging plan's release gate (security find-identity, codesign --verify, spctl --assess, notarytool log, stapler validate) is the evidence trail; this section is how to act on a failure.

5.1 Always pull the notary log first#

bash
# Get the submission id from the submit output or the history.
xcrun notarytool history --keychain-profile "$BELLONA_NOTARYTOOL_PROFILE"
xcrun notarytool log <submission-id> \
  --keychain-profile "$BELLONA_NOTARYTOOL_PROFILE" notary-log.json

The log's issues[] array names the exact file and reason. Do not guess — fix what the log reports.

5.2 Failure → cause → fix table#

Notary issue Root cause Fix
The executable does not have the hardened runtime enabled. A binary was signed without --options runtime. Re-sign that binary with codesign --options runtime (§2); re-run the inside-out signing order.
The signature does not include a secure timestamp. codesign ran without --timestamp (or offline). Re-sign with --timestamp while online; Apple's timestamp server must be reachable.
The binary is not signed with a valid Developer ID certificate. Signed with an ad-hoc/self-signed identity, or the wrong identity. Re-sign with $BELLONA_DEVELOPER_ID_APPLICATION (app/helpers) / $BELLONA_DEVELOPER_ID_INSTALLER (pkg). Confirm with security find-identity -p codesigning -v.
The executable requests the com.apple.security.get-task-allow entitlement. A debug/get-task-allow build was submitted. Re-build for release (strip get-task-allow); never notarize a debug build.
The signature of the binary is invalid. / nested code unsigned A nested dylib/helper inside the bundle was missed. Re-run signing inside-out (helpers → nested dylibs → Unreal Mach-O → app → component pkg → product pkg) per the packaging plan; verify with codesign --verify --deep --strict --verbose=4.
Disallowed entitlement … cs.disable-library-validation An unnecessary hardened-runtime exception was added. Remove the exception (§2.2) and re-sign; the host needs none.

5.3 Re-submit, staple, and re-validate the EXACT artifact#

After fixing and re-signing, re-submit and staple the same package that will be distributed — never staple a different build:

bash
xcrun notarytool submit dist/apps/bellona/remote-host/macos/BellonaRemoteHost.pkg \
  --keychain-profile "$BELLONA_NOTARYTOOL_PROFILE" --team-id "$BELLONA_TEAM_ID" --wait

xcrun stapler staple dist/apps/bellona/remote-host/macos/BellonaRemoteHost.pkg
xcrun stapler validate dist/apps/bellona/remote-host/macos/BellonaRemoteHost.pkg
spctl --assess --type install -vvv dist/apps/bellona/remote-host/macos/BellonaRemoteHost.pkg

5.4 If stapling fails after an accepted notarization#

stapler needs network access to fetch the ticket the first time. If Accepted but stapler staple reports Error 65 / could not find ticket:

  1. Wait a few minutes — the ticket can lag the Accepted status, then retry xcrun stapler staple.
  2. Confirm the artifact's cdhash matches the accepted submission (re-run codesign -dvvv and compare to the notary log); a re-built artifact will not match a prior ticket.
  3. As a fallback for an offline machine, Gatekeeper can verify online without a stapled ticket, but release artifacts must be stapled so they pass on offline / private-studio machines (see mdm-offline-install.md).

5.5 If a TCC grant silently stops working after an update#

A notarized, correctly-signed app can still lose its Screen Recording / Accessibility grant if its code signature identity changes (TCC keys grants to the signing identity + bundle id). Recovery:

  1. Run the host once; createRemoteHostMacPermissionDetector().detect() (surfaced by diagnoseMissingPermissions, 180.C.26.03) reports the now-denied grant with the exact remediation string.
  2. Have the operator re-toggle the grant in System Settings ▸ Privacy & Security ▸ Screen Recording / Accessibility, then quit and relaunch.
  3. Keep the bundle id (com.oshun.bellona.remote-host) and Team ID stable across updates so TCC grants survive; the update-manifest signing keys (RemoteHostTrustedUpdateSigningKey, apps/bellona/remote-host/src/update-manifest.ts) are independent of the macOS code-signing identity and must not be conflated with it.

6. Two-logical-units note (180.C.26.17)#

For future refactors, Stage 26 splits into two units (see stage-26-logical-units.md): the hardened-runtime entitlements + TCC usage rationale here belong to 26.A (app-shell / permissions / discovery / adapters); the signing/notarization delivery mechanics belong to 26.B (signing / updates / SBOM / integrity). This document spans the seam because the entitlements are authored in 26.A but consumed by the 26.B signing job.