D5 — Package and sign macOS/Windows artifacts in the release workflow

[eaitbrahim]

PRD §4/§5. Do not start this before D1–D4. Packaged today, it would ship a signed app that launches a terminal into /, cannot write its database, cannot run its console on Windows, and refuses every safety-critical action.

Approach

PyInstaller --onedir — not --onefile: faster TUI start (no self-extraction), simpler per-binary signing for notarisation, lower AV/SmartScreen false-positive rate.

• macOS — signed + notarised + stapled .dmg. If D2 lands, the app starts the local server and opens a browser; without D2 it needs a launcher that open -a Terminals the binary, because a Finder-launched app has no controlling terminal at all (the packaging research rates this the single biggest technical risk, above signing and above Python 3.14).
• Windows — console-subsystem exe wrapped by Inno Setup into one signed setup.exe, installing per-user to %LOCALAPPDATA%\Programs\keel (no admin prompt). Windows auto-allocates a console on double-click, so no wrapper is needed there.

Workflow integration

New job after uv build --all-packages (.github/workflows/release.yml:85-88), consuming the same four wheels PRODUCTION_WHEEL_PREFIXES already encodes (keel/commands/update.py:82-88) plus config.yaml. Matrix: macos-14 (arm64), macos-15-intel (x86_64), windows-latest — the release job runs ubuntu-latest only today.

Ship two macOS DMGs, not universal2 — lipo-merging bundled-CPython-plus-native-extension trees is fragile in practice. Note macos-15-intel is scheduled to sunset around Aug 2027.

Signing

Apple	$99/yr. Developer ID Application cert (+ Installer cert for .pkg), codesign --options runtime, notarytool submit --wait, stapler staple. App Store Connect API key for CI.
Windows	OV cert ~$70–500/yr, or Azure Trusted Signing at $9.99/mo.

EV certificates no longer bypass SmartScreen — Microsoft ended that in 2024; OV and EV are now equivalent for reputation, which accrues from download volume over time. EV remains required only for kernel-mode drivers. Azure Trusted Signing may be limited to US/Canada signing identities — verify before budgeting.

Run signing behind a protected GitHub Environment requiring manual approval, never on PR builds from forks. Import certs into an ephemeral keychain per job and delete it after; prefer OIDC federation over a stored Azure client secret.

Why signing is a precondition, not polish

An unsigned binary that then asks for exchange API keys is the shape of malware distribution — research turned up a live example while surveying this space. For a project whose proposition is auditability, shipping that silhouette without OS-level verification would be worse than shipping no installer.

Also

Reconcile .github/workflows/release.yml:93-96, which claims the wheel carries Requires-Python: >=3.14.4 while every pyproject.toml declares >=3.11 (pinned by tests/test_python_floor.py:46-59). Harmless today; misleading to anyone building a packaging job on top of it.

Verify first

PyInstaller's Python 3.14 support against the pinned release, with a smoke build including cryptography/cffi — genuinely native and production-required via coinbase-advanced-py.

[eaitbrahim]

Requirement added: install location, and what happens when keel is already there

Requested directly. Specified here rather than built, because D5 is still gated on D1–D4.

There are two locations, and conflating them is the trap

D1 (#434, merged) already separates them, and the installer must keep them separate:

	what it holds	replaced on upgrade?
program	the frozen binary and its bundled runtime	yes, wholesale
deployment	config.yaml, keel*.db, .env, logs/	never

The installer's "where do you want this?" is about the program. The deployment is chosen separately, defaults to the OS app-data directory keel_core.paths.app_data_dir() already returns, and is discovered at runtime by the precedence rule D1 established: KEEL_HOME → a deployment-looking cwd → app-data.

Proposed defaults, all per-user so no elevation prompt appears:

	program	deployment (default)
Windows	%LOCALAPPDATA%\Programs\keel	%LOCALAPPDATA%\keel
macOS	/Applications/keel.app, offering ~/Applications when /Applications is not writable	~/Library/Application Support/keel

Both must be overridable in the installer UI. A chosen non-default deployment path is persisted as KEEL_HOME for the launcher, which is the seam D1 built for exactly this.

When the chosen path already contains keel

1. Read the installed version from the on-disk artifact's metadata — do not execute it. Running an old binary to decide whether to replace it is fragile, and it is precisely the case keel versions exists to catch: a partially-upgraded tree reports the new number from --version while running old libraries.

2. Newer incoming than installed → update. Replace the program directory wholesale. Do not touch the deployment. Then let the app run migrate on first start, which is idempotent and already how upgrades self-heal.

3. Same version → confirm before overwriting. Reinstalling the same build is almost always a repair, so offer it, but do not do it silently.

4. Older incoming than installed → confirm, with a specific warning, and never silently. This is the case worth calling out, and it is why "if the versions differ, just update" cannot be the whole rule:

   keel/data/db.py:499 migrates with if current < target. There are no down-migrations. A database already at schema N installed under a build that expects N−2 does not fail loudly — migrate finds nothing to apply and returns. The old code then runs against columns and tables it was never written against.

   So a downgrade must warn in those terms, and the safe recovery is to restore a database backup taken before the original upgrade — not to run the older build against the newer schema.

What must never happen

• config.yaml is never overwritten by an installer, on any path. An operator's allowlist, caps and auto_trade.mode are hand-edited and irreplaceable. keel.commands.setup.create_config already has this property — an existing config is left untouched and there is deliberately no force a caller can pass — and the installer must match it.
• No database is ever replaced, moved, or migrated by the installer. Migration happens when the app starts, through the one code path that already does it.
• Nothing is written to the deployment folder before the user has confirmed the location, so that cancelling the installer leaves nothing behind.

Acceptance

• The installer proposes an OS-appropriate default for both locations and accepts an override for each.
• Installing over an existing keel reports both versions and the action it is about to take, before taking it.
• A same-version and a downgrade install both require explicit confirmation; a downgrade additionally warns that migrations do not reverse.
• After any update, the pre-existing config.yaml, .env and every keel*.db are byte-identical.
• Cancelling at the path prompt leaves the filesystem unchanged.

[eaitbrahim]

Decision: no Apple code signing. Provenance instead.

keel is open source on a small budget, and Apple signing is not being paid for.

There is no cheaper version of it. Notarisation requires a Developer ID certificate, which requires the $99/yr Developer Program. A free Apple account signs only for local development. A self-signed certificate buys nothing — Gatekeeper trusts Apple-issued Developer IDs and nothing else. So the choice was pay or ship unsigned; the choice is ship unsigned.

What that costs, stated rather than hidden

A .dmg downloaded from the internet carries a quarantine flag, so macOS refuses the first open. The user must go to System Settings → Privacy & Security → Open Anyway, once. Windows SmartScreen shows "Windows protected your PC" → More info → Run anyway.

That is friction this milestone set out to remove, and it is worth being clear that it is not removed. It also teaches a user to click past a security warning while holding exchange API keys, which is the part I would least like to leave unanswered.

What answers it instead, at zero cost

Every artifact now carries a GitHub build attestation binding it to this repository, this workflow and this commit:

gh attestation verify <file> --repo CodeGateSoftware/keel

plus a SHA256SUMS.txt attached to the same release.

That does not move Gatekeeper — nothing free does. But it answers "did this binary come from that source, built by that pipeline", which is the question a code-signing certificate answers too, and arguably the one an auditable project should care about most. A user told to bypass a warning now has something to check first.

The release notes carry all of this, so it reaches the person downloading rather than only the person reading the repo.

Guardrails, since "unsigned" is now a supported path

• The workflow option is spelled publish-unsigned. publish would have been a value you could pick without thinking; this one cannot be chosen without reading the word.
• The default stays build, which attaches nothing to a release.
• Attestation is produced before anything is attached, so a failed attestation cannot leave behind a published artifact nobody can verify.
• All three are pinned by tests/test_desktop_packaging.py.

Windows signing is a separate decision, still open

Azure Trusted Signing is $10/mo ($120/yr), so it is not obviously cheaper than Apple's $99/yr. And EV certificates no longer bypass SmartScreen — Microsoft ended that in 2024, and reputation now accrues from download volume over time regardless of certificate class. So a new OV cert would not remove the warning immediately either. Unless there is a reason to treat Windows differently, the coherent position is to leave both unsigned and rely on provenance.

If this is revisited

Everything needed is in place: the packaging scripts produce the artifacts, and signing steps drop into the desktop job behind a protected environment. Reversing this is adding steps, not undoing work.