# MDM-Friendly and Offline / Private-Studio Install & Update (180.C.26.13)

Status: `180.C.26.13` implementation.

This document specifies two deployment paths for the Bellona Remote Host that do
**not** assume a public app store or a cloud update endpoint:

1. **MDM-managed install** — pre-grant the macOS TCC permissions via a Privacy
   Preferences Policy Control (PPPC) **configuration profile**, and
   pre-configure the gateway connection via a managed defaults profile, so a
   fleet of studio Macs onboards with zero per-machine clicking.
2. **Offline / private-studio install + no-cloud updates** — install from a
   locally-hosted signed package and update from a **local update repository**
   using the existing signed update-manifest contract, with no call to any
   Bellona or third-party cloud service.

It builds on:

- [`macos-hardened-runtime.md`](./macos-hardened-runtime.md) — the entitlements,
  not-sandboxed rationale, and the TCC services the PPPC profile pre-grants.
- [`macos-packaging-and-notarization-plan.md`](./macos-packaging-and-notarization-plan.md)
  — the signed `BellonaRemoteHost.pkg` the MDM/offline install deploys.
- The signed update-manifest contract in
  `apps/bellona/remote-host/src/update-manifest.ts`
  (`RemoteHostSignedUpdateManifest`, `verifyRemoteHostSignedUpdateManifest`,
  `RemoteHostTrustedUpdateSigningKey`, 180.C.16.03 / 26.07).
- The Tailscale/WireGuard private-network mode in
  [`tailscale-wireguard-private-network.md`](./tailscale-wireguard-private-network.md)
  for the LAN/VPN the offline gateway lives on.

The host runtime identifiers these profiles target are the real ones:
bundle id **`com.oshun.bellona.remote-host`**, LaunchAgent label
**`com.oshun.bellona.remote-host`** (`apps/bellona/remote-host/src/macos-packaging-plan.ts`),
and the config env keys parsed in `apps/bellona/remote-host/src/config.ts`
(`BELLONA_REMOTE_HOST_GATEWAY_URL`, `BELLONA_REMOTE_HOST_HEALTH_HOST/PORT`,
`BELLONA_REMOTE_HOST_IDENTITY_FILE`).

## 1. Why MDM (and why not the App Store)

The host ships **not sandboxed** (see `macos-hardened-runtime.md` §3), which makes
it ineligible for the Mac App Store and means TCC grants would otherwise require
a human to click through every prompt on every machine. In a studio with many
identical Macs, that is both error-prone and unauditable. MDM solves both:

- A **PPPC configuration profile** delivered by MDM can pre-grant the
  Accessibility and Apple Events (Automation) TCC services for a known,
  code-signed app — no per-machine clicking, and the grant is centrally
  auditable.
- **Screen Recording is the deliberate exception.** Apple does **not** allow MDM
  to silently pre-grant `kTCCServiceScreenCapture`; a PPPC profile can only set
  it to `Allow Standard User to Set System Service` (the user still confirms once).
  The host's first-run flow (`diagnoseMissingPermissions`, 180.C.26.03) surfaces
  exactly that one remaining grant with its precise remediation string, so the
  managed-but-one-click reality is honest, not hidden.

## 2. PPPC configuration profile (TCC pre-grant)

A configuration profile is a `.mobileconfig` plist containing one or more
**payloads**. For TCC pre-grant we use a `com.apple.TCC.configuration-profile-policy`
payload. The app is identified by its **code requirement** (a `designated
requirement` string), which binds the grant to Bellona's exact signing identity
and bundle id — a different binary cannot inherit the grant.

Generate the code requirement from the **signed** app on a build machine:

```bash
codesign --display --requirements - \
  "/Applications/Bellona Remote Host.app" 2>&1 | sed -n 's/^designated => //p'
# => identifier "com.oshun.bellona.remote-host" and anchor apple generic and
#    certificate leaf[subject.OU] = "<BELLONA_TEAM_ID>"
```

Then author the profile (real, valid PPPC structure):

```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>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadIdentifier</key>
  <string>com.oshun.bellona.remote-host.pppc</string>
  <key>PayloadUUID</key>
  <string>0F1E2D3C-4B5A-6978-8796-A5B4C3D2E1F0</string>
  <key>PayloadDisplayName</key>
  <string>Bellona Remote Host — Privacy Preferences</string>
  <key>PayloadScope</key>
  <string>System</string>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>com.apple.TCC.configuration-profile-policy</string>
      <key>PayloadIdentifier</key>
      <string>com.oshun.bellona.remote-host.pppc.policy</string>
      <key>PayloadUUID</key>
      <string>1A2B3C4D-5E6F-7081-9203-B4C5D6E7F809</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>Services</key>
      <dict>
        <!-- Accessibility: pre-granted (synthetic input via AXIsProcessTrusted). -->
        <key>Accessibility</key>
        <array>
          <dict>
            <key>Identifier</key>
            <string>com.oshun.bellona.remote-host</string>
            <key>IdentifierType</key>
            <string>bundleID</string>
            <key>CodeRequirement</key>
            <string>identifier "com.oshun.bellona.remote-host" and anchor apple generic and certificate leaf[subject.OU] = "BELLONA_TEAM_ID"</string>
            <key>Allowed</key>
            <true/>
          </dict>
        </array>
        <!-- Apple Events: pre-grant the host -> Blender/Unreal automation pairs.
             AEReceiverIdentifier names the controlled app. -->
        <key>AppleEvents</key>
        <array>
          <dict>
            <key>Identifier</key>
            <string>com.oshun.bellona.remote-host</string>
            <key>IdentifierType</key>
            <string>bundleID</string>
            <key>CodeRequirement</key>
            <string>identifier "com.oshun.bellona.remote-host" and anchor apple generic and certificate leaf[subject.OU] = "BELLONA_TEAM_ID"</string>
            <key>AEReceiverIdentifier</key>
            <string>org.blenderfoundation.blender</string>
            <key>AEReceiverIdentifierType</key>
            <string>bundleID</string>
            <key>AEReceiverCodeRequirement</key>
            <string>identifier "org.blenderfoundation.blender" and anchor apple generic</string>
            <key>Allowed</key>
            <true/>
          </dict>
        </array>
        <!-- Screen Recording CANNOT be silently pre-granted by MDM. The most a
             profile may do is permit a standard user to enable it themselves;
             the user confirms once and the 26.03 onboarding flow surfaces it. -->
        <key>ScreenCapture</key>
        <array>
          <dict>
            <key>Identifier</key>
            <string>com.oshun.bellona.remote-host</string>
            <key>IdentifierType</key>
            <string>bundleID</string>
            <key>CodeRequirement</key>
            <string>identifier "com.oshun.bellona.remote-host" and anchor apple generic and certificate leaf[subject.OU] = "BELLONA_TEAM_ID"</string>
            <key>Authorization</key>
            <string>AllowStandardUserToSetSystemService</string>
          </dict>
        </array>
      </dict>
    </dict>
  </array>
</dict>
</plist>
```

Notes:

- Replace `BELLONA_TEAM_ID` with the real Apple Team ID; the literal must match
  the `codesign --display --requirements` output for the distributed app.
- TCC profiles are only honored when delivered by an **MDM-supervised** device
  (user-approved MDM enrollment). A manually-installed PPPC profile is ignored by
  macOS — this is an Apple constraint, not a Bellona one.
- Add an `AppleEvents` entry per controlled DCC (Unreal: `com.epicgames.UnrealEditor`).

## 3. Pre-configuring the gateway (managed defaults)

The host reads its gateway URL and ports from the environment / config
(`loadRemoteHostConfig`, `apps/bellona/remote-host/src/config.ts`). For a
LaunchAgent-run host, the durable way to set those on managed machines is a
**managed app-defaults** profile (`com.apple.ManagedClient.preferences`) writing
the host's preference domain (`com.oshun.bellona.remote-host`), which the
LaunchAgent surfaces to the process environment at launch:

```xml
<dict>
  <key>PayloadType</key>
  <string>com.apple.ManagedClient.preferences</string>
  <key>PayloadIdentifier</key>
  <string>com.oshun.bellona.remote-host.managed-prefs</string>
  <key>PayloadUUID</key>
  <string>2B3C4D5E-6F70-8192-A3B4-C5D6E7F80912</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  <key>PayloadContent</key>
  <dict>
    <key>com.oshun.bellona.remote-host</key>
    <dict>
      <key>Forced</key>
      <array>
        <dict>
          <key>mcx_preference_settings</key>
          <dict>
            <!-- The private-studio gateway on the LAN / Tailscale tailnet. -->
            <key>BELLONA_REMOTE_HOST_GATEWAY_URL</key>
            <string>wss://gateway.studio.lan:4070/v1/hosts/connect</string>
            <key>BELLONA_REMOTE_HOST_HEALTH_HOST</key>
            <string>127.0.0.1</string>
            <key>BELLONA_REMOTE_HOST_HEALTH_PORT</key>
            <integer>4071</integer>
          </dict>
        </dict>
      </array>
    </dict>
  </dict>
</dict>
```

The LaunchAgent plist
(`packaging/macos/launch-agents/com.oshun.bellona.remote-host.plist`) reads these
managed values into `EnvironmentVariables` (or the host reads the managed domain
directly) so a managed Mac connects to the studio gateway with no local edits.
The gateway's TLS pin is handled by `gateway-pinning.ts`
(`apps/bellona/remote-host/src/gateway-pinning.ts`); for a self-signed studio CA,
ship the CA via a separate `com.apple.security.root` certificate payload in the
same profile.

## 4. Offline / private-studio install path

For an air-gapped or no-internet studio:

1. **Stage the signed package once, online.** On a build machine with internet,
   build, sign, notarize, and **staple** `BellonaRemoteHost.pkg` (see the
   packaging plan). Stapling is what lets the package install on offline machines
   — Gatekeeper validates the stapled ticket without contacting Apple. An
   un-stapled package will fail Gatekeeper on a machine that cannot reach Apple.
2. **Distribute over the LAN.** Host the stapled `.pkg` (and the profiles above)
   on an internal share / MDM distribution point. There is no Bellona cloud in
   this path.
3. **Install.** MDM `InstallApplication`, or `installer -pkg BellonaRemoteHost.pkg
   -target /`, or a Munki/Jamf repo. The LaunchAgent registers the host
   (`macos-packaging-plan.ts`).
4. **Verify locally.** Run the host once; `createRemoteHostMacPermissionDetector().detect()`
   + `diagnoseMissingPermissions` (180.C.26.03) reports any remaining grant (the
   one Screen Recording confirmation §1) with an exact remediation string.

The host's transport is loopback + the studio gateway only; with the managed
gateway URL pointing at a LAN/Tailscale address, the host never needs egress to
the public internet to operate.

## 5. No-cloud update option

Updates use the **same signed update-manifest contract** as the cloud path — only
the *source* changes from a cloud URL to a **local update repository**. There is
no separate, weaker offline code path; the Ed25519 signature, channel,
compatibility, and revocation gates in
`verifyRemoteHostSignedUpdateManifest` (`apps/bellona/remote-host/src/update-manifest.ts`)
all still apply.

### 5.1 Stand up a local update repository

A local update repo is a directory served over HTTPS on the LAN (or a Tailscale
host) containing:

- `manifest.json` — a `RemoteHostSignedUpdateManifest` (payload + Ed25519
  signature), produced by the release job exactly as for the cloud channel.
- the artifacts referenced by `manifest.payload.artifacts[].url`, each with its
  `sha256` recorded in the manifest.

Point the artifact URLs at the local repo. Because each
`RemoteHostUpdateArtifact` carries its own `url` + `sha256`, the URL can be a LAN
HTTPS path (or a `file://` path for a mounted share) without changing
verification — the integrity check is the hash + signature, not the origin:

```jsonc
// manifest.json (RemoteHostSignedUpdateManifest), local-repo flavour
{
  "payload": {
    "schemaVersion": 1,
    "channel": "internal",
    "version": "0.2.0",
    "artifacts": [
      {
        "artifactId": "remote-host-installer-pkg",
        "kind": "remote-host-installer-pkg",
        "platform": "macos",
        "arch": "universal",
        "url": "https://updates.studio.lan/bellona/0.2.0/BellonaRemoteHost.pkg",
        "sha256": "<sha256-of-the-stapled-pkg>",
        "sizeBytes": 0,
        "signing": ["developer-id-installer", "notarized", "stapled"]
      }
    ]
    /* ...rollback, adapterCompatibility, releaseGate per the payload type... */
  },
  "signature": {
    "algorithm": "ed25519",
    "keyId": "bellona-internal-2026",
    "canonicalization": "json-stable-v1",
    "signatureBase64": "<base64-ed25519-signature>"
  }
}
```

### 5.2 The host verifies the local manifest exactly like a cloud one

The studio configures the host's trusted signing keys
(`RemoteHostTrustedUpdateSigningKey[]`) and the local repo URL, then verification
is the unchanged call:

```ts
import {
  verifyRemoteHostSignedUpdateManifest,
  type RemoteHostSignedUpdateManifest,
  type RemoteHostTrustedUpdateSigningKey,
  type RemoteHostUpdateVerificationState,
} from '@bellona/remote-host'; // apps/bellona/remote-host/src/update-manifest.ts

const result = verifyRemoteHostSignedUpdateManifest(
  manifestFetchedFromLocalRepo, // RemoteHostSignedUpdateManifest
  trustedKeys,                  // the studio's pinned internal signing keys
  verificationState,            // current version/channel/adapters/now/revocations
);
// result.ok === false unless the Ed25519 signature, channel eligibility,
// minimum-version, adapter compatibility, AND revocation checks all pass —
// identical guarantees to the cloud channel.
```

Because the manifest is signed by a studio-held internal key and the host pins
that key, a malicious file dropped on the LAN repo cannot pass verification, and
a revoked-but-signed build is still refused (`isUpdateRevoked` /
`RemoteHostUpdateVerificationState.revocations`).

### 5.3 No-cloud guarantees

- **No telemetry or update call leaves the studio network.** The manifest and
  artifacts are fetched from the LAN repo; verification is purely local.
- **Integrity is origin-independent.** The hash + Ed25519 signature gate the
  install, so a LAN/`file://`/mounted-share source is as safe as a cloud CDN.
- **Rollback works offline.** The manifest's `rollback`
  (`RemoteHostUpdateRollbackPlan`) and the previous staged artifact stay in the
  local repo, so `action: 'rollback'` needs no internet either.

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

Per [`stage-26-logical-units.md`](./stage-26-logical-units.md): the gateway
pre-configuration and the first-run grant surfacing in this doc belong to
**26.A**; the signed-update delivery (local repo + `verifyRemoteHostSignedUpdateManifest`)
and the package distribution belong to **26.B**. MDM/offline install spans both —
it configures the 26.A app shell and delivers the 26.B signed artifacts.
