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

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`](./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`](./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](./macos-packaging-and-notarization-plan.md).

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`](./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`](./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.
