Orrery and copal-tm as Mac Applications: Bundles, Icons and Ad-hoc Signatures

Abstract

orrery and copal-tm were installed on the Mac that coordinates the fleet as command-line programs. Each was started from a terminal, and orrery with a command line five options long. Both are now also Mac applications in ~/Applications, opened from Finder, Launchpad, Spotlight and the Dock.

Each bundle has:

• a copy of its program;
• a small launcher script;
• an Info.plist;
• an icon drawn by a short Python program in the project's own colours;
• an ad-hoc code signature.

Neither project gained a dependency: the tools used are sips, iconutil, codesign and Python's zlib, all part of macOS.

Two faults were found and fixed on the way:

• on a Mac's case-insensitive disk, a launcher named Orrery overwrote the binary orrery;
• macOS refuses an unprivileged reader most of root's processes (in the macOS back end).

The signatures are ad hoc: they satisfy Apple silicon's rule that all code is signed, and they let the bundles open on this Mac. Gatekeeper's own assessment (spctl -a) rejects both, as it rejects every bundle without a Developer ID. The bundles are signed applications for this Mac. They are not yet ones to hand to another person's Mac (§VII).

I. Objective

Paul's prompts:

after make install. how do I get an application launcher like in Applications folder. Can I also get this install for Orrery.

write a lab report about making orrery and copal-tm into a mac signed applications. Place documentation in both projects.

1. After make install, copal-tm should also be an application in the Applications folder.
2. The same for orrery, which has no Makefile.
3. Sign both, and record how, in both projects.

II. Materials

III. Why these choices

IV. The bundles

Orrery.app/Contents/
  Info.plist            org.copal.orrery, CFBundleExecutable = launch
  MacOS/launch          PATH, the log, then exec orrery --gui OPTIONS
  MacOS/orrery          the release binary
  Resources/orrery.icns 486,037 bytes
  _CodeSignature/

Copal TM.app/Contents/
  Info.plist            org.copal.copal-tm, CFBundleExecutable = launch, LSUIElement
  MacOS/launch          exec open -a Terminal "$(dirname "$0")/copal-tm"
  MacOS/copal-tm        the release binary
  Resources/copal-tm.icns 178,554 bytes
  _CodeSignature/

The launchers, as written:

#!/bin/sh
# Orrery.app's launcher, written by /Users/user/code/orrery/tools/mac-app.sh.
export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
mkdir -p "$HOME/Library/Logs"
exec "$(dirname "$0")/orrery" --gui '--operator' 'paul' '--fleet' 'grove' '--fleet-cmd' '/Users/user/.local/bin/copal fleet' '--queue' '/Users/user/code/treadcore/build/queue/grove' >>"$HOME/Library/Logs/orrery.log" 2>&1

#!/bin/sh
# Copal TM.app's launcher, written by copal-tm's tools/mac-app.sh.
exec open -a Terminal "$(dirname "$0")/copal-tm"

V. Method, to repeat

orrery (no Makefile; the script builds, installs and bundles):

cd ~/code/orrery
tools/mac-app.sh --operator paul --fleet grove \
    --fleet-cmd "$HOME/.local/bin/copal fleet" \
    --queue "$HOME/code/treadcore/build/queue/grove"
# also: tools/mac-app.sh            (the fleet alone, --gui added)
#       APPDIR=/Applications tools/mac-app.sh ...
#       tools/mac-app.sh --uninstall

It runs cargo build --release and installs ~/.local/bin/orrery. It writes the bundle, draws the icon, signs the binary and then the bundle, swaps the bundle in, and registers it with Launch Services. It ends by printing the command line the app will run.

copal-tm:

cd ~/code/copal-tm
make install            # ~/.local/bin/copal-tm and ~/Applications/Copal TM.app
make install APP=0      # the binary only
make uninstall          # both

Checking a bundle:

codesign -v --deep ~/Applications/Orrery.app      # silent and 0: sealed
codesign -dv ~/Applications/Orrery.app            # Signature=adhoc
spctl -a -vv ~/Applications/Orrery.app            # Gatekeeper's verdict
open ~/Applications/Orrery.app; tail ~/Library/Logs/orrery.log

VI. Results

The faults, in the order found:

1. The launcher overwrote the binary. The first Orrery.app named its launcher Orrery and its binary orrery, in the same folder. On a case-insensitive disk those are one file: writing the launcher replaced the binary. codesign then refused the bundle ("code object is not signed at all … Contents/MacOS/orrery"). That message read at first like a missing signature, and the script's comment said so. Listing the folder showed a single 409-byte file; the error was the collision. Both launchers are now named launch, and the comment is corrected.
2. An unprivileged user cannot read root's processes on macOS (found the same day while writing copal-tm's macOS back end, LR in copal-tm §X-B):
   • proc_pidinfo(PROC_PIDTBSDINFO) refused 221 of 558 processes;
   • sysctl KERN_PROC_ALL lists them all, as ps reads them;
   • their CPU and memory stay unreadable (/bin/ps is setuid root to get

   them), and Copal TM draws a dash there, not a zero.

Errors and limits. The Gatekeeper verdict and the launches were checked on this one Mac. Nothing was tried on a second Mac, so §VII's account of one is Apple's documented behaviour, not a measurement.

VII. Discussion: what "signed" means here

macOS has three levels, and these bundles are on the first:

A bundle that is downloaded, mailed or AirDropped arrives quarantined. Gatekeeper refuses an ad-hoc one: the person must Control-click, choose Open, and confirm, or remove the flag (xattr -dr com.apple.quarantine). For the fleet's console on its own Mac, ad hoc is what is wanted: nothing to renew and nothing to pay. For handing orrery or Copal TM to another person, the next step is a Developer ID. The scripts' two codesign lines take an identity in place of - and are otherwise ready for it. That is Paul's decision, and it costs a membership.

Two smaller points remain open:

• Copal TM uses Terminal. A person who lives in iTerm or Ghostty would want the launcher to name that program instead.
• Orrery's options are fixed when the app is made. A second fleet would want a second app, or a choice in the window.