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 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-eventsblanket grant. Automation is a per-application TCC prompt (createMacHostProcessLaunchershellsopen), 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:
- 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. - Synthetic input into other applications.
AXIsProcessTrusted()/ Accessibility-driven input (thedesktop-*commands) targets other apps' UI — categorically outside a sandbox's process boundary. - Launching and automating arbitrary DCC apps.
open/open -a(createMacHostProcessLauncher) starts Blender/Unreal anywhere on disk; the sandbox forbids launching arbitrary executables. - 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, inhostPermissionReportToRemotePermissions(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#
# 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:
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:
- Wait a few minutes — the ticket can lag the
Acceptedstatus, then retryxcrun stapler staple. - Confirm the artifact's
cdhashmatches the accepted submission (re-runcodesign -dvvvand compare to the notary log); a re-built artifact will not match a prior ticket. - 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:
- Run the host once;
createRemoteHostMacPermissionDetector().detect()(surfaced bydiagnoseMissingPermissions, 180.C.26.03) reports the now-deniedgrant with the exact remediation string. - Have the operator re-toggle the grant in System Settings ▸ Privacy & Security ▸ Screen Recording / Accessibility, then quit and relaunch.
- 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.