Audit notes from a v1.0.0 install — happy to share privately if useful

[whybepaul]

Hi! Cloned the repo today and read through the build pipeline, install/uninstall scripts, packaging, and the bundled .app. I have a set of detailed notes — roughly 7–10 items spanning the build scripts, doc/code mismatches, version drift across files, an uninstall step that I believe is silently blocked by SIP on modern macOS, and a couple of small cosmetic things.

Before adding anything to your tracker, I figured it would be more useful to ask how you'd prefer to receive feedback:

• I can paste the full notes here as a single comment.
• I can email them privately — happy to send to whatever address works (GitHub-noreply, the maintainer email in repository.yaml, or any other).
• I can split them into individual issues if that's how you prefer to triage.

Some items may already be on your radar, and a few might be intentional design choices I'm reading wrong — that's part of why I'd rather check first than dump a wall of issues on a hobby-scope project.

For what it's worth: the venv-at-/opt + LaunchDaemon + dedicated _homeassistant user architecture is a reasonable choice, and the goal — a one-double-click HA install on macOS without Docker/VM overhead — is a real gap. Notes are constructive.

Let me know which format works best.

[Bwillou1]

Salut ! Merci énormément pour ton message et d'avoir pris le temps de fouiller mon code de cette façon. Ça me fait vraiment plaisir, surtout que l'architecture (/opt + launchd) est quelque chose sur lequel j'ai passé beaucoup de temps pour que ce soit propre.

En tant que jeune développeur de 14 ans, avoir le retour détaillé d'un dev expérimenté comme toi est une opportunité incroyable pour moi d'apprendre et de rendre l'outil encore plus solide.

Pour le format, tu peux créer une seule Issue générale sur ce GitHub et tout coller dedans. C'est parfait pour que je puisse tout analyser d'un coup et structurer la version 1.1.0 (et j'ai vraiment hâte de lire tes notes sur SIP et le script de désinstallation !

[whybepaul]

Salut William! Merci pour ta réponse rapide et pour l'ouverture à recevoir des notes détaillées. Je vais écrire en anglais parce que les commandes et les références techniques (man pages, Apple docs) sont en anglais de toute façon — mais n'hésite pas à poser des questions en français sur quoi que ce soit qui n'est pas clair.

Below is the full audit — organized by severity, with a deep dive on SIP and the uninstall script at the end since you asked specifically about those. I'd suggest reading the "What you got right" section first because there are several choices in your launchd plist and uninstall design that are genuinely well-done and worth keeping in v1.1.0.

---

What you got right (don't lose these in v1.1.0)

These are choices in your repo that go beyond what most installers do:

LaunchDaemon plist tuning (launchd/org.homeassistant.daemon.plist):

1. LowPriorityIO: true (line 33-34) — tells launchd to deprioritize HA's disk I/O so database writes don't compete with foreground user work. Smart for a Mac that's also being used.
2. ThrottleInterval: 30 (line 27-28) — protects against rapid crash-restart loops. Default is 10s, which is too tight for HA's startup cost.
3. SoftResourceLimits NumberOfFiles: 32768 (lines 53-57) — HA Core opens many concurrent connections (integrations + websockets + database). The default macOS limit (256–1024) is too low. This is a real production-tuning detail most people miss.
4. FFMPEG_HWACCEL: videotoolbox in EnvironmentVariables (lines 49-50) — uses Apple's hardware video decoding for camera streams. Excellent for HA's ffmpeg-based integrations.
5. ProcessType: Background (lines 30-31) — applies background QoS, complements LowPriorityIO. The pair tells launchd "this is not foreground-critical work."
6. Separating StandardOutPath/StandardErrorPath from HA Core's own --log-file — daemon-level launchd output goes to daemon.log/daemon.error.log; HA Core's app-level log goes to home-assistant.log. Most installers conflate these and lose the distinction between "the daemon process crashed before HA started" and "HA started but reported an error."

Architecture:

7. /opt/homeassistant + dedicated _homeassistant system user is the right shape. You said you spent time on this — it shows.
8. UserShell /usr/bin/false, IsHidden 1 on the system user (preinstall lines 35, 40) — correct daemon-user defaults; the user can't interactively log in and doesn't show up at the login window.
9. pkgbuild + productbuild + Distribution.xml is the Apple-native packaging path, not a half-baked .dmg or installer-app hack.

Operational subtleties:

10. launchctl bootout system BEFORE chown'ing the plist in postinstall (lines 85-89). Your own comment says "On fait le bootout AVANT de modifier les permissions pour éviter l'état fantôme (bug 5: Input/output error)." That's a real launchd footgun and you figured it out the hard way — most people hit "Input/output error" on bootstrap and never trace it back to the load-order issue. Worth keeping.
11. make uninstall preserves /Library/Application Support/HomeAssistant/ (the user's config) — only removes /opt/homeassistant, the plist, and the system user. That's the correct design for a tool people will uninstall and reinstall. Don't change this.
12. scripts/uninstall offers an interactive backup prompt before deleting config (lines 53-63). User-respect built in. Keep the backup option in v1.1.0, just consider adding a non-interactive flag path for headless workflows.

OK now the issues, ordered by severity.

---

Critical (these change whether the product works)

C1. The build pipeline has two broken paths

Three files reference scripts/specs that don't exist in the repo:

• package.sh:19 runs python3 -m PyInstaller main.spec — main.spec is not in the repo.
• scripts/build_universal.sh:21 and :28 sed-read homeassistant-macos.spec; lines 22 and 29 then invoke PyInstaller on the sed-generated copies. homeassistant-macos.spec is not in the repo.
• scripts/sign.sh:22 says "first run python3 create_web_pkg.py" — not in the repo.

Only the Makefile works. make all uses python3 -m venv and pip install -r requirements.txt, which is the venv-based path. The PyInstaller path is dead code.

Fix for v1.1.0: delete package.sh, scripts/build_universal.sh, and the PyInstaller reference in scripts/sign.sh. Keep scripts/sign.sh itself (you'll need it — see C3) but rewrite it to run against the Makefile-produced .pkg. One build entry point, not three competing ones.

C2. The bundled .app binary is arm64-only, despite the "Universal 2" claim

$ file HomeAssistant-Desktop.app/Contents/MacOS/homeassistant-macos
HomeAssistant-Desktop.app/Contents/MacOS/homeassistant-macos: Mach-O 64-bit executable arm64

The README advertises Universal 2 support, but the committed binary only works on Apple Silicon. Intel Mac users — exactly the audience you're targeting with the "old Mac mini repurposing" pitch — get a binary that won't run.

Two paths to fix this:

• Build a real Universal 2 binary using lipo:

  # build arm64 and x86_64 venv-bundled Pythons separately, then:
  lipo -create arm64/bin/python3 x86_64/bin/python3 -output universal/bin/python3

• Or: ship two architecture-specific .pkgs and let productbuild --distribution pick at install time.

Either way: don't commit the 56 MB .app binary into git. Add *.app/ to .gitignore and produce the binary in make all.

C3. Signing and notarization aren't wired into make all

You have scripts/sign.sh and scripts/notarize.sh, but make all never calls them. The default build produces an unsigned .pkg. On modern macOS, an unsigned .pkg triggers a Gatekeeper warning that users have to manually bypass.

There are three honest options here:

1. Get an Apple Developer ID ($99/year), wire signing + notarization into make all, and ship a Gatekeeper-clean v1.1.0. This is the smoothest user experience.
2. Ship unsigned and document the bypass in the README (xattr -d com.apple.quarantine HomeAssistant-macOS-1.1.0.pkg before opening it). Honest if you can't or don't want to pay $99/year.
3. Sign but not notarize. Don't do this — it has the cost of signing without the user-experience benefit. Modern macOS still warns on signed-but-not-notarized installers.

Pick (1) or (2). Whichever you pick, be honest about it in the README. Right now the README says "production-ready" while shipping unsigned, which doesn't match.

C4. Version drift across files

File	Version
Makefile line 7	2.0.0
package.sh line 7	1.0.0
scripts/build_universal.sh line 9	1.0.0
repository.yaml line 13	1.0.0
HomeAssistant-Desktop.app/Contents/Info.plist	1.0.0
Latest commit message	"release v2.0.0"

Six different version strings. A user installing your .pkg would see different versions in different places.

Fix: single source of truth. Pick one. I'd recommend a VERSION file at the repo root that the Makefile reads, and that all other scripts/files derive from. Then bump it once per release.

---

Important (these change whether the product is honest or robust)

I1. Three competing READMEs

README.md, README_OFFICIAL.md, README-DEVELOPERS.md. They already disagree (e.g., README-DEVELOPERS.md references src/main.py, which doesn't exist in src/).

Fix: keep one. Delete the others. A single README.md plus, optionally, a CONTRIBUTING.md for dev setup.

I2. PROJECT_SUMMARY.md describes files that don't exist

The summary enumerates src/main.py, src/bonjour_manager.py, src/hooks/macos-hook.py, and homeassistant-macos.spec. None of these exist in the repo. The actual src/ contains three competing launcher files (simple_main.py, ha_launcher.py, ha_launcher_final.py), none of which are referenced by your LaunchDaemon — the plist runs /opt/homeassistant/bin/hass directly (the venv entry point), so those three Python files in src/ are dead code.

Fix: delete PROJECT_SUMMARY.md (or rewrite it against the actual files) and delete the unused src/*.py files.

I3. postinstall:18 silently swallows chown failures that can boot-loop your daemon

In scripts/postinstall:18:

chown -R $USER_NAME:$GROUP_NAME "$HA_CONFIG_DIR" "$HA_LOG_DIR" >/dev/null 2>&1 || true

(And similarly on lines 23 and 77 for /opt/homeassistant and the config file.)

Combined with KeepAlive: true and ThrottleInterval: 30 in your plist, here's the failure mode:

1. chown fails silently (maybe the system is in MDM mode, or a race condition, or the system user creation step in preinstall didn't fully complete).
2. The daemon starts as _homeassistant but can't write to /Library/Logs/HomeAssistant/home-assistant.log because the directory is still owned by root.
3. HA Core's Python logging module raises on the unwritable log path, the daemon exits.
4. launchd restarts it 30 seconds later (per ThrottleInterval).
5. Same thing happens.
6. The user sees a "running" service that's actually in a permanent restart loop, with nothing useful to debug from because the daemon can't write to its own log file.

Fix: make chown failures fatal on critical paths. Remove the || true on lines 18, 23, and 77. If chown fails on the config dir, log dir, or /opt/homeassistant/, the install should abort with a clear error message rather than silently continue into a boot loop.

I4. chmod 644 on configuration.yaml is too permissive

In scripts/postinstall:78. HA's configuration.yaml typically contains API tokens for integrations (Spotify, weather APIs, smart device cloud accounts). World-readable (644) means any local user on the Mac can read those tokens. The macOS daemon convention is 640 (owner read+write, group read, others nothing).

Fix: chmod 640 "$HA_CONFIG_FILE" and ensure ownership is _homeassistant:_homeassistant.

I5. Install isn't idempotent — no VERSION file, no version comparison

If a user runs your .pkg twice (re-install for any reason), preinstall's dscl -read check at line 25 handles the user-creation race, but there's no version comparison anywhere — running an older .pkg over a newer install will downgrade without warning, and running the same version twice rebuilds the venv from scratch unnecessarily.

Fix: add a /opt/homeassistant/VERSION file written by postinstall. In preinstall, read it. If the existing version is newer than the one being installed, exit with "refuse to downgrade." If equal, exit gracefully with "already installed." If older, proceed with upgrade.

I6. LaunchDaemon uses /bin/bash -c when it doesn't need to

In launchd/org.homeassistant.daemon.plist lines 14-19:

<key>ProgramArguments</key>
<array>
    <string>/bin/bash</string>
    <string>-c</string>
    <string>rm -f "...lock" &amp;&amp; exec /opt/homeassistant/bin/hass ...</string>
</array>

The whole point of ProgramArguments is to skip the shell. Calling bash -c adds a parent process, breaks proper signal forwarding (you can no longer cleanly launchctl kill SIGTERM), and exists only to rm a lock file that postinstall already removes on line 81.

Fix: since postinstall already removes the lock file, you can simplify ProgramArguments to a clean argv list pointing directly at /opt/homeassistant/bin/hass with its flags as separate <string> entries. If you still want the rm-at-launch safety, put it in a small wrapper script (/opt/homeassistant/bin/hass-launcher) ending in a proper exec, then point ProgramArguments at that wrapper.

I7. Backgrounded open http://... as root from postinstall

In scripts/postinstall:105-110:

(
    sleep 30
    echo "[INFO] Ouverture automatique..." >&2
    open "http://localhost:8123" 2>/dev/null || true
) &

This spawns a detached subshell running as root that opens a URL 30 seconds later. Works, but it's surprising behavior from an installer and slightly worrying as a pattern — the user might not want their installer launching browsers as root in the background.

Fix: rely on the conclusion.html panel (which you already have via Distribution.xml) to display a clickable http://localhost:8123 link. The Apple Installer GUI will render it and let the user click when ready. Drop the backgrounded open. The osascript notification on line 113 is a nicer touch and can stay.

---

Now the SIP and uninstall deep dives you asked about

Deep dive #1 — SIP and scripts/uninstall:95

This line:

sqlite3 "$TCC_DB" "DELETE FROM access WHERE client = 'org.homeassistant.daemon';" 2>/dev/null || true

What's happening: TCC.db (/Library/Application Support/com.apple.TCC/TCC.db) is macOS's privacy database — it stores which apps have which permissions (Bluetooth, Files & Folders, Camera, Removable Volumes, etc.). Since macOS 10.15 Catalina (October 2019), this database is protected by System Integrity Protection (SIP), which means:

• Even root cannot write to it. SIP doesn't care about UID; it cares about file labels and entitlements.
• The only processes allowed to modify TCC.db are signed Apple binaries with specific entitlements (tccd, tccutil from /usr/bin/).
• Any direct sqlite3 write attempt fails with a "permission denied" error.

Your || true swallows that error, so the script reports success even though nothing was deleted. This means your uninstall script's "TCC cleanup" step cannot ever have worked on any macOS shipped in the last 6 years. The line is harmless (it does nothing) but it's also misleading (it claims to do TCC cleanup, when it doesn't).

Side note: even if SIP didn't block the write, the query uses client = 'org.homeassistant.daemon' (the LaunchDaemon Label), but the .app bundle identifier in Info.plist is org.homeassistant.desktop. TCC entries are keyed on bundle identifier, not LaunchDaemon Label. So the query would also target the wrong client identifier. Both problems compound.

The actually-correct path on modern macOS:

There is no way to programmatically remove TCC entries for an arbitrary app. The supported flow is:

1. The user opens System Settings → Privacy & Security, finds your app in the Bluetooth (or Files & Folders, etc.) list, and toggles it off / removes it.
2. The tccutil reset command can reset entries, but only for specific categories: tccutil reset Bluetooth org.homeassistant.desktop (using the bundle identifier from Info.plist, not the LaunchDaemon Label). This runs as the user, not as root, and resets only the named category.

Fix for v1.1.0: delete the sqlite3 DELETE block entirely (it's pure illusion). Replace it with documentation in your uninstall instructions:

"If you previously granted Home Assistant access to Bluetooth, Files & Folders, or Removable Volumes, those permissions are stored by macOS and not removed by this uninstaller. To remove them: open System Settings → Privacy & Security → [category] and remove Home Assistant from the list. Alternatively, run tccutil reset Bluetooth org.homeassistant.desktop per category (replace Bluetooth with the category you want to reset)."

This is the honest uninstall behavior. The previous version made a claim it couldn't fulfill, which is the worst kind of error mode for a security-adjacent operation — the user thinks the cleanup happened when it didn't.

One thing worth knowing for v2 planning. macOS by design doesn't allow any program — signed, root-owned, anything — to grant TCC permissions to itself or to another program. Only the user can grant them, either through System Settings or by responding to a consent dialog triggered from inside a UI session. Your _homeassistant daemon runs without a UI session, so it can't even trigger the dialog. This is the structural reason your repository.yaml's "Bluetooth and Local Network permissions" line is harder than it sounds — those permissions exist as a relationship between an app and the user's TCC database, and the user is the only party who can establish that relationship. If v2 wants to remove the "open System Settings and click these things" onboarding step, the architectural path is a small UI helper .app bundled alongside the daemon that runs once in the user's session at first install and triggers the consent dialogs there. Not blocking for v1.1.0 cleanup — just worth knowing as the underlying constraint, because it shapes any future "set-and-forget" claim for USB/Bluetooth integrations.

Deep dive #2 — /etc/pf.conf editing

Same file, lines 99-108:

if [ -f "/etc/pf.conf" ]; then
    sed -i '' '/homeassistant/d' /etc/pf.conf 2>/dev/null || true
    pfctl -f /etc/pf.conf 2>/dev/null || true
    log_info "Règles firewall supprimées"
fi

What's happening: /etc/pf.conf is macOS's main packet-filter (firewall) configuration file. It's system-managed — Apple's intent is that users don't hand-edit it. The standard pattern for third-party software is to install rules in a separate anchor file under /etc/pf.anchors/ and reference that anchor from pf.conf (or load it via pfctl -a anchor-name).

Direct sed editing of pf.conf works (root can write to it) but it's brittle:

1. The next macOS update may rewrite /etc/pf.conf, undoing your changes (and possibly replacing them with new Apple defaults you didn't expect).
2. If you ever add rules with edge cases (multi-line, conditional), sed-by-line matching is fragile.
3. Any reload of pf re-runs your edits against whatever the current /etc/pf.conf looks like, which may not be what you tested against.

I notice line 88 already removes /etc/pf.anchors/homeassistant — so you already know about the anchor pattern. The pf.conf sed is a separate inconsistency.

Fix for v1.1.0:

• Don't edit /etc/pf.conf directly.
• Install your anchor file at /etc/pf.anchors/io.homeassistant.daemon (you already remove this on line 88 — good).
• Add a single reference line to /etc/pf.conf (via templated install) like anchor "io.homeassistant.daemon".
• On uninstall, remove your anchor file and that single reference line. Cleaner and survives macOS updates.

Honest question worth asking before doing this work: do you actually need pf rules? If HA is binding to :8123 on localhost, no firewall rule is needed for local access. If you want LAN access for the iPhone companion app, the app's listener on 0.0.0.0:8123 plus the user's system firewall settings should cover it. You may be able to remove the pf logic entirely and reduce uninstall complexity significantly. The PROJECT_SUMMARY.md mentions "Firewall pfctl : Règles mDNS pour Bonjour (port 5353 UDP)" but I don't see those rules being added anywhere in the current postinstall — only removed in uninstall. If the rules are never added, the cleanup is removing nothing.

One leftover from the old code path — preinstall:48

pkill -f "/usr/local/bin/homeassistant-macos" >/dev/null 2>&1 || true
pkill -f "/opt/homeassistant/bin/hass" >/dev/null 2>&1 || true

Line 48 references /usr/local/bin/homeassistant-macos — that's the path the old PyInstaller approach (package.sh) would have installed to. Your current Makefile installs to /opt/homeassistant, so line 48 never matches anything. Line 49 correctly pkills the current path and is fine.

Fix: delete line 48. Keep line 49.

Suggestion for headless/non-interactive uninstall

Your scripts/uninstall is great for users running it directly — the backup prompt is genuinely user-respecting. But it uses read -p which makes it interactive, so sudo bash uninstall < /dev/null over SSH will hang or skip prompts inconsistently.

For v1.1.0 or later, consider adding flags:

• --remove-config — skip the backup prompt, just remove config
• --keep-config — skip the prompt, preserve config (matches make uninstall default)
• --non-interactive — error out if any prompt is needed, for CI/headless contexts

Default behavior (no flags, interactive TTY) stays the same.

---

Other items (cosmetic but worth fixing)

• pkg/# Home Assistant Apple Platforms — a file whose name starts with # and a space, containing promotional copy about the iOS app. Looks like a copy-paste accident. Delete it.
• homebrew-tap/ is empty — if you advertise a brew tap, the directory needs a Cask file in it. Either populate the tap with a real Cask formula pointing at your GitHub release .pkg, or remove the brew advertising until it's ready.
• repository.yaml points to https://github.com/williamguindon/MacOS_HA (not your actual repo URL) and has a placeholder email william.guindon@example.com. Update both.
• requirements.txt doesn't pin Python version, just homeassistant>=2024.1.0. HA Core pins specific Python minor versions per release. If your build machine has Python 3.13 but HA requires 3.12, the install breaks. Add a python_requires constraint via a pyproject.toml, or at minimum document the supported Python version in the README.
• scripts/postinstall:42-45 writes country: FR, language: fr, time_zone: Europe/Paris as defaults. Reasonable if your primary audience is French/Québécois — but worth mentioning in the README so English-speaking users know where to change it. Or detect the system locale at install time and pick defaults from that.

---

Suggested ordering for v1.1.0

If you want a sensible work order:

Week 1 — clean the foundation:

1. Delete dead code: src/*.py, package.sh, scripts/build_universal.sh, PROJECT_SUMMARY.md, README_OFFICIAL.md, README-DEVELOPERS.md, pkg/# Home Assistant Apple Platforms, and either fill or remove homebrew-tap/.
2. Single VERSION file at repo root; all other files derive from it.
3. Remove the 56 MB committed .app binary; add *.app/ to .gitignore.
4. Update repository.yaml with real URL and email.

Week 2 — fix install correctness:
5. Make chown failures fatal in postinstall (remove || true on lines 18, 23, 77).
6. Add idempotent install + version comparison via /opt/homeassistant/VERSION file.
7. Tighten configuration.yaml permissions to 640.
8. Simplify the LaunchDaemon ProgramArguments to a clean argv list (drop the bash -c wrapper).
9. Drop the backgrounded open http://localhost:8123 from postinstall; rely on conclusion.html.
10. Delete preinstall:48 (the dead PyInstaller-era pkill).

Week 3 — fix uninstall correctness:
11. Delete the sqlite3 DELETE FROM TCC.db block (lines 90-97) entirely. Add documentation about manual TCC cleanup via tccutil reset.
12. Either move pf logic to /etc/pf.anchors/ cleanly, OR remove pf rules entirely if not needed.
13. Add --remove-config / --keep-config / --non-interactive flags to scripts/uninstall for headless workflows. Keep the existing interactive default.

Week 4 — distribution:
14. Decide Apple Developer ID: yes/no.
15. If yes: wire signing + notarization into make all and ship signed.
16. If no: update README to honestly describe the Gatekeeper warning and document the xattr bypass.
17. Build a real Universal 2 binary via lipo, or ship two architecture-specific .pkgs.

Week 5 — verification:
18. Add a CI workflow that runs make all on a macOS runner (GitHub Actions gives you 2000 min/month free, with macOS runners at a 10x minute multiplier — budget accordingly). Even a basic "does it build?" check catches breakage before users do.
19. Test the full install + run + reboot + uninstall flow on a clean macOS VM (UTM is free).

---

Closing

Writing a working .pkg-based macOS installer with thoughtful launchd tuning, a dedicated system user with hidden login, an uninstall script that respects the user's config, and recognition of subtle launchd footguns like the bootout-before-chown ordering is genuinely good engineering. The structural foundation here is solid. Most of the issues above are cleanup + honesty issues, not fundamental architecture problems.

If anything above is unclear or you want me to elaborate on a specific item, just ask in this thread. Et n'hésite pas en français si c'est plus facile.

Good luck with v1.1.0.