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.tsapps/bellona/remote-host/src/identity-store.tsapps/bellona/remote-host/src/macos-packaging-plan.tslibs/bellona/editor-productization/src/plugin-distribution.tslibs/bellona/unreal/plugin/BellonaUnrealEditor/BellonaUnrealEditor.uplugindocs/domains/bellona/extras/remote-control/external-implementation-research-2026-04-21.mddocs/domains/bellona/extras/remote-control/hardware-rig-inventory.md
Apple references checked for this item:
- Creating distribution-signed code for macOS: https://developer.apple.com/documentation/xcode/creating-distribution-signed-code-for-the-mac
- Packaging Mac software for distribution: https://developer.apple.com/documentation/xcode/packaging-mac-software-for-distribution
- Notarizing macOS software before distribution: https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution
- Customizing the notarization workflow: https://developer.apple.com/documentation/security/customizing-the-notarization-workflow
- Resolving common notarization issues: https://developer.apple.com/documentation/security/resolving-common-notarization-issues
Required Signing Environment#
The release job must fail before packaging if any of these are missing:
BELLONA_DEVELOPER_ID_APPLICATIONBELLONA_DEVELOPER_ID_INSTALLERBELLONA_NOTARYTOOL_PROFILEBELLONA_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:
- Helper executables and any nested dylibs/frameworks.
- Unreal plugin Mach-O binaries, if present.
- Remote Host app bundle.
- Component package from
pkgbuild. - Product package from
productbuild. - Submit the final product package to notary service.
- 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:
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 -vcodesign --verify --deep --strict --verbose=4for the app bundlepkgutil --check-signaturefor the installer packagespctl --assess --type executefor the app bundlespctl --assess --type installfor the installer packagexcrun notarytool logfor the accepted submission idxcrun stapler validatefor 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.