Eve library

Stage 26 — Two Logical Units (180.C.26.17 planning note)

Guide

Revision 1

On this page

Status: 180.C.26.17 planning note.

Stage 180.C.26 (the macOS Remote Host app shell, permissions, discovery, packaging, signing, updates, SBOM, and integrity) has grown large enough that future work should treat it as two logical units rather than one monolithic stage. This note records that split so later refactors, ownership boundaries, and release gates line up with it. It is a planning artifact — it does not move or rename existing 180.C.26.* items in TODOS/phase-180.md; it groups them.

The split#

Unit Theme Owns
26.A App shell / permissions / discovery / adapters What the host is and can do on the machine: the app/process shell, the permission model + onboarding, app/adapter discovery, and the adapter lifecycle.
26.B Signing / updates / SBOM / integrity How the host is built, trusted, delivered, and kept honest: code signing + notarization, the signed update channel, the SBOM + license/scan release evidence, and runtime tamper/integrity verification.

The seam between them is "runtime capability" vs. "supply-chain / delivery trust." 26.A is what an operator interacts with; 26.B is what a release engineer and a security reviewer interact with. They share a few artifacts (e.g. entitlements are authored in 26.A but consumed by the 26.B signing job), and those shared seams are called out below.

Mapping the existing 26.* items#

This reflects the implemented/landed items at the time of writing; it is the intended grouping, not a claim of completion.

26.A — app shell / permissions / discovery / adapters#

  • 180.C.26.02 — LaunchAgent install / repair / uninstall (the app shell on the machine).
  • 180.C.26.03 — first-run permission onboarding + exact missing-permission diagnostics (apps/bellona/remote-host/src/first-run-onboarding.ts: planFirstRunOnboarding, diagnoseMissingPermissions).
  • 180.C.26.04 / 180.C.26.05 — host app + adapter discovery and install/repair/uninstall action model (apps/bellona/remote-host/src/host-app-discovery.ts).
  • 180.C.26.16 — the cross-platform host permission/process/screen-capture abstraction (libs/bellona/host-runtime: HostPermissionProvider, PLATFORM_PERMISSION_MATRIX, resolveHostPermissionRequirements) — the model 26.A's onboarding and adapters are built on.
  • The macOS TCC usage-description rationale and the not-sandboxed decision from 180.C.26.11 (the authoring of the entitlements/purpose strings, as a capability concern) — see macos-hardened-runtime.md.
  • The gateway pre-configuration and first-run grant surfacing parts of 180.C.26.13 — see mdm-offline-install.md.

26.B — signing / updates / SBOM / integrity#

  • 180.C.26.07 — signed update manifest + emergency revocation (apps/bellona/remote-host/src/update-manifest.ts: verifyRemoteHostSignedUpdateManifest, RemoteHostTrustedUpdateSigningKey, isUpdateRevoked).
  • 180.C.26.08 — diagnostic bundle (apps/bellona/remote-host/src/diagnostic-bundle.ts).
  • 180.C.26.10 — SBOM generation, license-policy compliance, vuln/malware scan expectations, and release evidence for the seven components (libs/bellona/release-evidence: generateSbom, checkLicenses, summarizeReleaseEvidence).
  • The hardened-runtime / notarization delivery mechanics of 180.C.26.11 (the signing job + notarization-failure recovery) — see macos-hardened-runtime.md.
  • The signed-update delivery (local repo + verification) and package distribution parts of 180.C.26.13 — see mdm-offline-install.md.
  • 180.C.26.12 / 180.C.26.15 / 180.C.27.18 — host binary + DCC plugin tamper detection and the continuous integrity monitor (libs/bellona/host-runtime/src/integrity.ts, dcc-plugin-integrity.ts, continuous-integrity-monitor.ts).

Shared seams (items that span 26.A and 26.B)#

These deliberately cross the line; a refactor should keep the authoring side in 26.A and the consuming side in 26.B:

  • Entitlements & TCC purpose strings — authored as a 26.A capability concern, consumed by the 26.B codesign/notarization job (180.C.26.11).
  • MDM / offline install — configures the 26.A app shell (gateway, grants) and delivers the 26.B signed artifacts + signed updates (180.C.26.13).
  • Discovery ↔ update compatibility — 26.A discovery (host-app-discovery.ts) reports installed adapter versions that the 26.B update-manifest adapterCompatibility gate consumes (RemoteHostAdapterCompatibilityRequirement).

Why split now (for future work)#

  • Ownership. 26.A is product/runtime engineering; 26.B is release/security engineering. Distinct review checklists.
  • Release gating. A 26.B release-evidence gate (SBOM + license + scan + integrity) can be evaluated independently of whether a 26.A capability (e.g. a new adapter) is finished, and vice-versa.
  • Cross-platform reuse. 26.A's capability model is already platform-neutral (@bellona/host-runtime, reused by the Windows 180.C.36 and Linux 180.C.37 hosts), while 26.B's signing/notarization is macOS-specific and the SBOM/integrity logic is platform-neutral. The split keeps the platform-specific and platform-neutral concerns from tangling.

This note is the reference the macos-hardened-runtime.md (§6) and mdm-offline-install.md (§6) docs point at for the 26.A/26.B classification.