Eve library

Bellona macOS Packaging And Notarization Plan

Guide

Revision 1

On this page

Status: 180.C.16.02 initial implementation plan.

Implementation date: 2026-04-23.

This plan defines the first signed and notarized distribution path for the Bellona Remote Host, LaunchAgent, helper tools, Blender add-on, and Unreal plugin. It is intentionally a packaging gate, not a claim that the later installer, updater, uninstall, entitlement, TCC onboarding, or production hardware evidence stages are complete.

Sources Reviewed#

Local implementation references:

  • apps/bellona/remote-host/src/config.ts
  • apps/bellona/remote-host/src/identity-store.ts
  • apps/bellona/remote-host/src/macos-packaging-plan.ts
  • libs/bellona/editor-productization/src/plugin-distribution.ts
  • libs/bellona/unreal/plugin/BellonaUnrealEditor/BellonaUnrealEditor.uplugin
  • docs/domains/bellona/extras/remote-control/external-implementation-research-2026-04-21.md
  • docs/domains/bellona/extras/remote-control/hardware-rig-inventory.md

Apple references checked for this item:

Required Signing Environment#

The release job must fail before packaging if any of these are missing:

  • BELLONA_DEVELOPER_ID_APPLICATION
  • BELLONA_DEVELOPER_ID_INSTALLER
  • BELLONA_NOTARYTOOL_PROFILE
  • BELLONA_TEAM_ID

The notary profile must be created outside the repo with Apple tooling and stored in the local CI/build machine Keychain. Apple account secrets must never be checked into the repository, .env files, package scripts, LaunchAgent plists, or generated installer payloads.

Artifact Plan#

Artifact Payload Signing Notarization role Notes
Remote Host app bundle dist/apps/bellona/remote-host/macos/Bellona Remote Host.app Developer ID Application, timestamp, hardened runtime Nested payload in final pkg Owns Node host runtime, Keychain identity storage, config, logs, gateway connection
LaunchAgent plist packaging/macos/launch-agents/com.oshun.bellona.remote-host.plist Covered by signed installer package Nested payload in final pkg Installs to ~/Library/LaunchAgents; final registration/repair/uninstall is 180.C.26.02
Helper tools dist/apps/bellona/remote-host/macos/helpers/* Developer ID Application, timestamp, hardened runtime Nested payload in final pkg Screen capture/input helpers require later entitlement and TCC evidence; no unsigned helper is allowed
Blender add-on dist/libs/bellona/blender/bellona-blender-addon.zip Signed manifest plus checksum ledger Nested payload or separate signed release artifact Python/data add-on package; no arbitrary unsigned executable helper may be hidden in the archive
Unreal plugin dist/libs/bellona/unreal/plugin/BellonaUnrealEditor.zip Developer ID Application for Mach-O plugin binaries plus signed manifest Nested payload or separate signed release artifact Sign nested dylibs/executables before zipping; engine-version matrix remains later Unreal production work
Installer package dist/apps/bellona/remote-host/macos/BellonaRemoteHost.pkg Developer ID Installer Primary notarization submission The exact distributed pkg is submitted with xcrun notarytool, stapled, and Gatekeeper-assessed

Signing Order#

The packaging implementation must sign from the inside out:

  1. Helper executables and any nested dylibs/frameworks.
  2. Unreal plugin Mach-O binaries, if present.
  3. Remote Host app bundle.
  4. Component package from pkgbuild.
  5. Product package from productbuild.
  6. Submit the final product package to notary service.
  7. Staple and validate the exact package that will be distributed.

Ad hoc signatures, self-signed identities, unsigned helpers, unsigned update manifests, 0.0.0.0 helper control ports, and xcrun altool notarization are blocked for release artifacts.

Command Skeleton#

The typed plan in apps/bellona/remote-host/src/macos-packaging-plan.ts exposes the command skeleton. The release job should generate or consume that plan and execute this shape after the final packaging scripts exist:

bash
pnpm nx build @bellona/remote-host --skip-nx-cache --verbose
pnpm nx build @bellona/unreal --skip-nx-cache --verbose

codesign --force --timestamp --options runtime \
  --entitlements packaging/macos/entitlements/bellona-desktop-helper.entitlements \
  --sign "$BELLONA_DEVELOPER_ID_APPLICATION" \
  dist/apps/bellona/remote-host/macos/helpers/bellona-desktop-helper

codesign --force --timestamp --options runtime \
  --entitlements packaging/macos/entitlements/bellona-remote-host.entitlements \
  --sign "$BELLONA_DEVELOPER_ID_APPLICATION" \
  "dist/apps/bellona/remote-host/macos/Bellona Remote Host.app"

pkgbuild --root dist/apps/bellona/remote-host/macos/pkgroot \
  --identifier com.oshun.bellona.remote-host \
  --version "$BELLONA_REMOTE_HOST_VERSION" \
  --install-location /Applications \
  --sign "$BELLONA_DEVELOPER_ID_INSTALLER" \
  dist/apps/bellona/remote-host/macos/BellonaRemoteHost.component.pkg

productbuild \
  --package dist/apps/bellona/remote-host/macos/BellonaRemoteHost.component.pkg \
  --sign "$BELLONA_DEVELOPER_ID_INSTALLER" \
  dist/apps/bellona/remote-host/macos/BellonaRemoteHost.pkg

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

Release Gate#

Before a macOS artifact can become MVP alpha release evidence, the build must record:

  • security find-identity -p codesigning -v
  • codesign --verify --deep --strict --verbose=4 for the app bundle
  • pkgutil --check-signature for the installer package
  • spctl --assess --type execute for the app bundle
  • spctl --assess --type install for the installer package
  • xcrun notarytool log for the accepted submission id
  • xcrun stapler validate for the distributed installer package

This item records the plan and typed release contract only. Live signed and notarized package evidence remains blocked until Developer ID certificates, final app bundle layout, LaunchAgent install/uninstall, helper entitlements, Sparkle-compatible update delivery, rollback drills, and package build scripts are implemented in later Stage 16 and Stage 26 work. 180.C.16.03 adds the initial signed update-manifest contract.