Repository navigation
feat(packaging): the macOS system install, a package that does the privileged setup - #2977
Draft
bryan-minimal wants to merge 19 commits into
Draft
bryan-minimal wants to merge 19 commits into
bryan-minimal wants to merge 19 commits into
Conversation
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
|
Member
Author
|
Prepush on anvil for abc73fc (job 01829, the CI mirror on the three-PR stack: fmt, clippy, nextest, miri, kani 31m, actionlint, shellcheck): green except cargo-machete, which #2872 clears. Skipped on the box as on PR 1 and PR 2: minimald-root-integration (no sudo), apparmor-profile (no apparmor_parser), and the KVM lane (the mr matrices stand in). |
bryan-minimal
force-pushed
the
pr3/macos-pkg
branch
2 times, most recently
from
November 10, 2026 00:39
78d5ac2 to
8ac3034
Compare
bryan-minimal
force-pushed
the
pr2/shared-box-name-service
branch
from
November 10, 2026 17:06
b685126 to
b3d62a1
Compare
bryan-minimal
force-pushed
the
pr3/macos-pkg
branch
from
November 12, 2026 23:19
86689af to
da50571
Compare
…ivileged setup A component package (pkgbuild, wrapped by productbuild) installs minimal machine-wide under /usr/local from a staged release's components manifest, every file checksum-checked as the installer does; a fleet deploys it by MDM (gominimal/inbox#1179), and the curl installer stays the per-user path. Its postinstall does what `min finalize-install` does for a user, with nobody logged in: the box-name service's bundle under /Library/PrivilegedHelperTools behind the Developer ID check, the resolver file for min.internal, the boot-time loopback-range job, and the service under a role account, `_minimal`, admitting the members of its group (every administrator at the first install; `dseditgroup` adds a user). preinstall stops the services for an upgrade; a postinstall that fails starts the previous ones again. uninstall.sh undoes all of it, account and group included, then removes every file in the receipt and the receipt, leaving /usr/local's standard directories. `build-pkg.sh --with` makes a test build from this tree, ad-hoc signed and named as such. The curl uninstaller leaves a package-installed Mac's DNS setup to the package. Three review rounds and the farm's package journeys and probes are behind this; the open questions are in packaging/macos/pkg/README.md. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…the notarize step Review of the package for an MDM pilot and for the day the Developer ID Installer certificate arrives found three gaps in build-pkg.sh: - No Distribution of its own: productbuild's synthesis said hostArchitectures="x86_64,arm64" for an arm64-only payload, set no minimum macOS, and left the install domain open. The script now synthesizes the Distribution and gives it what the synthesis leaves out: arm64 only, rootVolumeOnly, the local-system domain, a minimum macOS (`--min-os`, default 15.0), a title. - No component plist: pkgbuild's own analysis marks every bundle relocatable, and Installer follows an older copy of the same bundle identifier elsewhere on the disk. The analysis is kept and BundleIsRelocatable set false for each bundle found (the key is absent when true, so it is added). - No notarization: `--notarize PROFILE` submits with notarytool, waits, staples, and runs the Gatekeeper assessment. `--sign` is timestamped and checked back with pkgutil. A test build is refused a signature instead of noted. The postinstall's install.log line for a user with an older curl `min` now says the older uninstaller's root commands about the host DNS setup are not to be run (the farm saw 0.7.2's uninstaller print them beside the package). The README gains "Deploying through an MDM" and "Signing and notarizing", and one more open item (test builds' 0.0.0 bundle versions). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…download page One read-only compressed volume named Minimal with the package alone at its top; --sign-dmg signs it with the Developer ID Application identity and --notarize notarizes and staples it as it does the package. An MDM takes the package, a person the image.
The macOS package places gvproxy-min in /usr/local/bin, since macOS seals /usr/bin, but the resolver probed only the user's bin directory, /usr/bin and /usr/lib/minimal/bin. A Mac installed from the package alone therefore found no switch and minvmd logged "booting without guest egress". The package lookup now takes the first existing of /usr/bin/gvproxy-min and /usr/local/bin/gvproxy-min. Order is unchanged elsewhere: a user-local install still wins, and a Linux package's copy wins where both exist. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…t over unbound When another program holds UDP 127.0.0.1:7656 as the service is loaded, launchd's bind fails and it still starts minzoned with the socket it made: a datagram socket with no address. launchd reuses that socket for every later start, so box names went unanswered after the other program left, until a reboot or a reinstall. The service now checks the listener's own address. With port 0 it binds the hook port itself. While the port is still held the bind fails, the error names the port, and the service exits, so the manager's next start after the port is free answers. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…d stands The name service now exits while another program holds UDP 7656 and answers on its first start after the port is free, so the postinstall's five-second start check failed the whole install in that case. The postinstall now looks for the port's holder: with one, it prints the program and its pid, says box names resolve once it stops, and the install succeeds. With none, the check fails the install as before. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… root alone can change it b1418b5 added /usr/local/bin/gvproxy-min to the lookup with an existence test only, on every platform. On a Mac whose /usr/local/bin belongs to a user (Homebrew's Intel layout), and on Linux hosts where a group can write it, any file there is someone else's to replace, and the daemons of every other user would run it. The path is offered on macOS only, and only when the file and its directory are root's and closed to group and others, and the file is no link. Where that does not hold the lookup goes on as before the earlier change, to the operator's path. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ls, and leaves no resolver file 86689af let an install stand when another program held UDP 7656, because the service takes the port by itself once it is free. But the resolver file was already written, the port is unprivileged, and so the program holding it, run by any local user, answered every user's box names; under MDM the install reported success. The resolver file is now written last, once the service holds the port. When the service is not running after its five seconds, an earlier install's file is removed and the install fails, naming the holder, its pid and its user when there is one. The service stays loaded and takes the port when it is free; installing again writes the file. Still open: every upgrade boots the service out in the preinstall, which frees the port for the length of the payload's extraction. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…t install can be removed Review findings A-1, A-3 and A-6 on the macOS package. The postinstall read what to require of the service program's signature from /usr/local/share/minimal/pkg-info and copied the program from /usr/local/bin/Minimal.app. Where a user owns those directories (Homebrew's Intel layout, Macs migrated from one) that user could change both between the payload and the postinstall, and root's launchd jobs then ran the result. - The payload puts the bundle at /Library/PrivilegedHelperTools/Minimal.app; the postinstall checks it there. The preinstall moves an earlier bundle aside, and a failed postinstall puts it back. - build-pkg.sh writes the signing expectation, the channel and the test-build flag into the postinstall. pkg-info stays for a person to read. - The uninstaller is installed by the postinstall, first, under /Library/Application Support/minimal with the list of the payload's files, and works from that list when there is no receipt. - A first install that fails removes its services, bundle, resolver file and the account it made, and names the uninstaller. The uninstall command changes: sudo "/Library/Application Support/minimal/uninstall.sh" Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… only sudo keeps the caller's PATH on macOS, and /opt/homebrew/bin or a user-owned /usr/local/bin is often first on it: the uninstaller would have run whatever dscl, rm or launchctl it found there, as root. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…installer from /usr/local Installer leaves files a newer package no longer carries, and they are in no receipt afterwards: the farm's upgrade journey found /usr/local/bin/Minimal.app and /usr/local/share/minimal/uninstall.sh still there after an uninstall. The preinstall removes the two, only when the earlier receipt lists them and neither is a link. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… says so, and changes nothing A label an administrator disabled with launchctl stays disabled across an uninstall. launchd then refused the postinstall's bootstrap with "Bootstrap failed: 5: Input/output error": an upgrade had already replaced the payload, and a fresh install was undone, neither saying why (minfarm j-c69494a470346c4c). The preinstall now reads launchd's disabled list first and stops before anything changes, naming the label and `launchctl enable`. The postinstall's own line points at Login Items, the other switch, which the disabled list may not show. README: what a user sees with the service off, measured (minfarm j-40efc69b5367bbcd): a box-name lookup hangs 60 s, other names are unaffected. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The preinstall booted the box-name service out, and until the postinstall loaded it again UDP 7656 was free with the earlier install's resolver file still naming it. The port is unprivileged: a local user's loop took it during an upgrade, answered for *.min.internal in that window, and the upgrade then failed for every user (minfarm j-0a7aeb65f643ca23; review finding A-2's upgrade half). The job now stays loaded. When its definition is unchanged, which is every upgrade so far within this layout, the postinstall restarts the process with `kickstart -k` and launchd never lets go of either socket. When the definition changed, the resolver file goes before the job is loaded anew and is written again once the service holds the port, so the free moment points nowhere. A failed upgrade restarts the earlier program and brings the resolver file back only when that service is seen running on the port. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… when it does not answer On a package install the names item waits on no daemon of the user's: a system service serves the zone. With that service off (an administrator's `launchctl disable`, or Login Items) the item read "waiting on a daemon (no daemon is reachable to report the port its DNS service listens on)", which sends the user to their own daemons (minfarm j-40efc69b5367bbcd). When the installed unit is a shared service's and nothing answers on its port, the cause now names that service, that names do not resolve, and what an administrator runs to see why. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…ile launchd holds its job `min finalize-install --show` took any DNS reply on the hook's port as the installed service answering. launchd makes the shared service's UDP listener and holds it for as long as the job is loaded, so with the job loaded nobody else can have the port (measured in a VM: a user's bind is refused with every reuse option, the program running or stopped). With the job booted out the port is any local program's, and with a stand-in answering there the command said "Every part of the install is finished on this machine" (farm job j-14638d60cf6734de). On a Mac with the package's unit, the names item now also asks launchd whether the job is loaded (`launchctl print`, which a standard user may run). Not loaded: the item is listed under "can't do on this machine", says the answer is not the package's service, and names `lsof` on the port. A launchd that did not say is unconfirmed, never done. Linux is unchanged: systemd holds the port the same way, but that is unmeasured. Review finding F2, second half. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Three review findings in build-pkg.sh, all about what a changed bucket or a passed-on file could do: - The script runs the payload's `min` (for its version and completions) on the machine that holds the signing identity. The download matched the manifest's checksum, but both come from the same bucket. A downloaded `min` now runs only with minimal's Developer ID (team 3G47C5HY64); one given with --with is the builder's own (A-4). - A manifest symlink row's target was taken as written. It must now be a path inside the payload (not absolute, no `..`), and lead to a file the manifest staged (A-5). - An unsigned build of a release was named as the release is. It is now minimal-<version>-unsigned.pkg; only the signed package has the plain name (A-7). Checked: the released unstable min is accepted and the build of it ends in ...-unsigned.pkg; an Apple-signed and an ad-hoc binary are refused by the requirement; `/etc/passwd`, `../x`, `a/../b` and an empty target are refused by the link rule, the two targets the manifests use are not. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… MDM Apple's payload page lists com.apple.servicemanagement as device channel only, requiring user-approved MDM, with no manual install. An admin who tries the profile by hand on one Mac would otherwise read its silence as the rule not matching. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
bryan-minimal
force-pushed
the
pr2/shared-box-name-service
branch
from
November 16, 2026 21:47
4b1222f to
bfd4de9
Compare
bryan-minimal
force-pushed
the
pr3/macos-pkg
branch
from
November 16, 2026 21:47
a710b4d to
a2ebfa6
Compare
… package release.yml gains build-macos-pkg: after stage-installer, on the signing runner, build-pkg.sh packages the staged row with the Developer ID Installer identity, notarizes and staples it, and writes the disk image. The job is skipped until the repository variable MACOS_PKG_INSTALLER_IDENTITY is set, and nothing needs it, so a release is unchanged until the certificate is in the signing keychain. build-pkg.sh gains --notary-keychain: the runner keeps its notarytool profile in the signing keychain, not the default one, and the script's submit could not find it there. Not run: the job needs the signing runner and a certificate it may not hold yet. Checked here: shellcheck, the option's refusals, the workflow parses as YAML. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A macOS package that installs minimal machine-wide and does the privileged setup at install time, so a fleet can push it by MDM with nobody logged in (gominimal/inbox#1179). The curl installer stays the per-user path.
Stacked on #2976 (the shared box-name service). Draft until the release workflow can sign it; see "Not done" below.
What it installs
/usr/local/bin,/usr/local/lib,/usr/local/share/minimalmin, its libraries and the guest images, from a staged release's manifest, each file checksum-checked as the curl installer does/Library/PrivilegedHelperToolsMinimal.app), behind a Developer ID check/Library/LaunchDaemonsdev.gominimal.zone(the name service, as the role account_minimal) anddev.minimal.local-range(the loopback range at boot)/etc/resolver/min.internal/Library/Application Support/minimaluninstall.shand the record it works fromThe postinstall does what
min finalize-installdoes for one user. The first install admits every administrator to the_minimalgroup;dseditgroupadds a user.The rules the scripts keep
/usr/local. Homebrew on older Macs leaves it user-owned, so everything root runs or trusts comes from root-only locations. A journey plants decoys there during the install and checks launchd runs the package's own program.Socketsin the plist). No local program can take UDP 7656 while the job is loaded, through an upgrade included.uninstall.shworks from its own record when there is no receipt.build-pkg.shchecks the Developer ID team on the downloadedmin, refuses symlinks out of the stage, and names an unsigned build-unsigned.pkg.Proof
Every night the farm (gominimal/minfarm) rebases this branch onto main, builds the package, and runs it in fresh macOS VMs. On 2026-11-16, on main
f7b6e364, the build and 16 package journeys passed:vm-pkg-upstream,vm26-pkg-upstream), from a disk image, as a second user, after a reboot, reinstall after uninstall/usr/localwith decoysAlso: minimal's Linux PR gates on this stack in the farm's Linux lane (13 of 13 steps),
scripts/install_test.shwith the darwin+pkg case, shellcheck on the four scripts.Reviewed in the farm over 18 rounds against a local-user threat model (a user in or out of the admitted group, against root and against each other). Every finding is fixed and has a journey, except one noted below. Peers (Docker, OrbStack, Tailscale, Podman, Apple
container, Determinate Nix) and Apple's guidance are compared in the farm'sdocs/research/macos-pkg-peers-and-apple-guidance.md.Not done, and not proven
build-pkg.sh --with). Unverified on a signed, notarized release: the developer name in Login Items, hardened runtime on executables other thanmin, and whether the release runner's package lists AppleDouble._*entries (a build in an operator's session lists 45; none reach the disk).release.ymlsigns binaries on theminimal-signingrunner; it needs a job that runsbuild-pkg.sh --sign --notarize, and a Developer ID Installer certificate there.packaging/macos/pkg/README.md, "Still open": whichminwins beside a curl install, the fleet's admission policy,install.toml method = "pkg"(gominimal/inbox#1168), running sessions across an upgrade, Full Disk Access for removing the role account.Reading order
packaging/macos/pkg/README.md: what an admin is told.scripts/preinstall,scripts/postinstall,scripts/uninstall.sh: what root runs (about 500 lines).build-pkg.sh: what the signing machine runs.crates/switch(where the switch binary may come from),crates/minvmd/src/cmd/answerer.rs(launchd's unbound socket),crates/minimal/src/resolver.rs(who answers on the port).🤖 Generated with Claude Code