0025 - Windows and macOS apply
Status: Implemented (2026-11-17; Windows MSI/NSIS execution and macOS .app.zip replacement;
.dmg, notarization and package elevation are separate; macOS .pkg apply is spec 0031, Linux package elevation is spec 0029; restart handoff is spec 0026)
Spec 0013 stops at a verified staged artifact. Spec 0014 adds the Linux AppImage apply path. This
spec adds the next two platform paths: run a Windows MSI/NSIS installer, and replace a macOS .app
bundle from a staged .zip. Both consume a [StagedUpdate], so the manifest signature, artifact
size and SHA-256 were checked before any platform action.
Scope
auro-update::WindowsInstaller: detect.msi/.exe, run the installer silently, and classify exit codes0,3010and1641.InstallerRunner: the command boundary, injectable for tests; no shell.auro-update::MacAppInstaller: extract a.zipcontaining exactly one top-level.app, swap it over an existing bundle, and return a rollback receipt.MacAppReceipt: report the installed bundle and backup, roll back, or discard.- Facade re-exports behind the
updaterfeature, gated by the host OS.
Out of scope
- Elevation, UAC,
sudo, admin prompts or a privileged helper process. - Waiting for the running app to exit, relaunching it, or a restart protocol; the journal/restart handoff is spec 0026.
- Windows rollback. The MSI/NSIS installer owns its install transaction.
- macOS
.dmgmounting, notarization and Apple package-signature policy;.pkgapply is spec 0031. .deb/.rpmpackage-manager apply.- Preserving extended attributes, ACLs, SELinux labels or ownership beyond what the archive and filesystem copy provide.
- Deltas, staged rollout, update channels and downgrade policy.
Decisions
D1 - Windows runs the OS installer, never a shell
WindowsInstaller inspects the staged artifact extension:
| Format | Program | Arguments |
|---|---|---|
.msi | %SystemRoot%\System32\msiexec.exe | /i <artifact> /qn /norestart |
.exe | <artifact> | /S (assumed NSIS) |
InstallerRunner receives an argument vector and uses std::process::Command directly. MSI uses
%SystemRoot%\System32\msiexec.exe, not a PATH lookup. The service does not build a command string,
so a path cannot inject shell syntax. A missing artifact is StagedArtifactMissing; an unknown
extension is UnsupportedInstaller.
Exit code 0 succeeds. 3010 (reboot required) and 1641 (reboot initiated) succeed with
restart_required: true. Every other code, including a terminated process with no code, is
InstallerFailed. The app decides when to restart; run the installer off the UI thread.
Rejected: a generic "run this command" hook. It moves platform policy into app code and makes
the silent flags, exit-code mapping and test boundary invisible. Rejected: downloading the
installer again here; only the verified StagedUpdate is accepted.
D2 - macOS swaps the .app directory from a zip
MacAppInstaller accepts a staged .zip with exactly one top-level .app. It extracts with
zip's enclosed-path extractor and then walks the extracted tree, rejecting any symlink whose
canonical target escapes the extraction directory. Nested symlinks are allowed when they stay
inside the bundle. It renames the old bundle to a hidden backup beside it, renames the new bundle
into place, and returns MacAppReceipt.
The extraction directory is created beside the target, so the final rename stays on one filesystem.
If the new rename fails, the backup is renamed back. The receipt follows the conservative
AppImage rule: dropping it keeps the backup; the app calls discard after verifying the new
version or rollback to restore the old bundle. Rollback removes the installed bundle first because
a directory rename cannot replace a non-empty directory.
Release tooling must preserve executable modes and symlinks in the .app.zip; ditto -c -k on
macOS is the reference packaging command. The zip dependency enables the deflate codec only, so
artifacts using zstd/deflate64 fail with Archive.
Rejected: applying a .dmg by mounting it and copying. That needs hdiutil, mount parsing,
detach handling and a helper/privilege story. A zip is a deterministic file format with a safe
extractor and a straightforward test path. Rejected: replacing files inside the bundle in place;
it cannot be atomic and leaves mixed versions after a crash.
D3 - The command runner is the test seam
InstallerRunner is public and returns the exit code or None. Production uses
SystemInstallerRunner; tests inject a recorder and inspect the exact program and argument vector
without launching an installer. Windows command construction and macOS bundle replacement are
therefore tested on Linux CI, while the host-specific types remain exported only on their host.
Rejected: #[cfg(test)] branches inside the production install function. The runner keeps the
test double explicit and lets an app provide a custom runner if needed.
D4 - The installer does not restart or elevate
A Windows installer may return 3010 or 1641, and a macOS bundle is used on the next launch.
Neither
installer waits for the current process, relaunches the app, or requests elevation. Those are a
separate restart/helper contract; claiming them here would be false.
Interfaces
#![allow(unused)] fn main() { pub trait InstallerRunner { fn run(&self, program: &Path, args: &[OsString]) -> Result<Option<i32>, UpdateError>; } pub struct SystemInstallerRunner; pub enum WindowsInstallerKind { Msi, Nsis } pub struct WindowsInstallOutcome { pub kind: WindowsInstallerKind, pub restart_required: bool, } pub struct WindowsInstaller { /* runner */ } impl WindowsInstaller { pub fn new() -> Self; pub fn with_runner(runner: impl InstallerRunner + 'static) -> Self; pub fn install( &self, staged: &StagedUpdate, ) -> Result<WindowsInstallOutcome, UpdateError>; } pub struct MacAppInstaller { /* target */ } impl MacAppInstaller { pub fn new(target: impl Into<PathBuf>) -> Self; pub fn target(&self) -> &Path; pub fn install(&self, staged: &StagedUpdate) -> Result<MacAppReceipt, UpdateError>; } pub struct MacAppReceipt { /* target, backup */ } impl MacAppReceipt { pub fn target(&self) -> &Path; pub fn backup(&self) -> &Path; pub fn rollback(self) -> Result<(), UpdateError>; pub fn discard(self) -> Result<(), UpdateError>; } }
WindowsInstaller is re-exported on Windows, and MacAppInstaller/MacAppReceipt on macOS. Both
are unit-tested on Linux through cfg(test).
Errors added to UpdateError: InstallTargetNotDirectory, UnsupportedInstaller,
InstallerFailed, AppBundleMissing, AppBundleAmbiguous, Archive, UnsafeArchive,
RestoreFailed and RollbackFailed.
Usage:
let staged = updater.download(&manifest)?;
#[cfg(target_os = "windows")]
let outcome = auro::update::WindowsInstaller::new().install(&staged)?;
#[cfg(target_os = "macos")]
let receipt = auro::update::MacAppInstaller::new("/Applications/Demo.app").install(&staged)?;
The snippet is an intended call shape, not an app that exists yet.
Acceptance
- MSI runs
msiexecwith/i, the staged path,/qnand/norestart(runs_msi_installer_silently). - NSIS runs the staged
.exewith/S(runs_nsis_installer_silently). 3010/1641reportrestart_required; another code isInstallerFailedand keeps the code (maps_reboot_required_and_failure).- An unknown Windows artifact is
UnsupportedInstaller(rejects_unknown_artifacts). - A
.app.zipreplaces the bundle, retains the old bundle in the receipt, and rollback restores the old contents (installs_and_rolls_back_an_app_bundle). discardremoves the backup (discards_the_backup_after_success).- An archive with no
.appfails withAppBundleMissingand leaves the target unchanged (rejects_an_archive_without_an_app_bundle). - A
.dmgstaged artifact is rejected as unsupported (rejects_an_unsupported_archive). - A symlink in the extracted bundle that resolves outside the extraction tree is rejected as
UnsafeArchive(rejects_symlinks_escaping_the_bundle), while an in-bundle symlink is allowed (allows_symlinks_inside_the_bundle). - A zip with two top-level
.appbundles is rejected without touching the target (rejects_an_ambiguous_archive). - Missing/non-directory macOS targets fail with
InstallTargetMissing/InstallTargetNotDirectory, and a corrupt zip fails withArchivebefore touching the target (rejects_missing_or_non_directory_targets,corrupt_archive_leaves_the_target_untouched). - A missing staged artifact is
StagedArtifactMissing(reports_a_missing_staged_artifact, macOSrejects_a_missing_staged_artifact), a terminated Windows installer isInstallerFailed { code: None }(reports_a_terminated_installer), and a macOS rollback with a missing backup reportsRollbackBackupMissing(rollback_reports_a_missing_backup). cargo fmt --all --check,cargo clippy --workspace --all-targets --locked -- -D warnings,cargo test --workspace --locked,cargo test -p auro-update --locked,cargo check -p auro --features updater --locked, andmdbook build docspass.
Open questions
| Question | Where it settles |
|---|---|
| Windows elevation, reboot and installer UI policy | Windows update UX/spec |
macOS .dmg apply | macOS disk-image apply spec |
macOS .pkg apply | macOS package apply |
.deb/.rpm package-manager apply | Linux package apply, elevation |
| Restart/helper protocol and crash-safe apply journal | Update journal and restart helper |
| macOS code-signing preservation and notarization checks | macOS notarization |
| Automatic downgrade policy | Linux package rollback |