[abrichr]

Follows #1486 and is stacked on its branch. Retarget to main once #1486 merges.

Problem

After #1486, Run it counts an approval only when a registered approver key signs it. Desktop users had to set that key up at a terminal (jit keygen, then jit register --role approver) before "Approve and save" worked.

Change

On a Mac with a Secure Enclave (Apple silicon or a T2 chip), the key is set up in the app.

Setup is one screen and one prompt. Until the key exists, the approval screen shows Set up your approver key in place of Approve. One click and one Touch ID or login-password prompt do the following:

1. Make a Secure Enclave key (P-256) whose access control asks for user presence on every use.
2. Make the Ed25519 approver key and seal it to the Secure Enclave key (ECIES with AES-GCM).
3. Store the sealed key and the Secure Enclave's handle in the login Keychain.
4. Open the sealed key once, to prove the round trip and that a person is present.
5. Register the public key under approvers with Flow's register_principal, the same function jit register calls.

Every answer prompts. Desktop runs item-approval approve|decline --approver-signer stdio --approver-public-key HEX. This is a new Flow option:

1. Flow writes the exact bytes to sign on stdout.
2. Desktop checks that they are the answer the person chose: the same request, digest and decision, decided_by human, route desktop_run_it, and canonical JSON.
3. Desktop prompts, signs, and writes the signature back.
4. Flow checks the signature against the registered key before it uses it.

Key handling. Flow never receives the key. Desktop holds the unsealed key only for one signature and zeroes the buffers. The key is never written to disk unsealed and never logged. The audit log records a 16-character fingerprint only.

Fail closed. Desktop sends no answer, and the screen says why, in each of these cases:

• no key;
• a cancelled or failed prompt;
• a Keychain or Secure Enclave error;
• bytes that aren't the person's answer;
• a Flow that's too old.

Rotation and removal. Settings > Approver key does both:

• Replace key registers the new key before it retires the old one. If the replacement fails, the old key keeps working.
• Remove key unregisters the key, then deletes it from the Keychain.

Flow's new authority.remove_principal removes a registered key only while it's still the registered one.

Windows, Linux, and Macs without a Secure Enclave keep the terminal path from #1486, and the screen and Settings show those steps. Each would need its own presence-backed key:

• Windows: Windows Hello (KeyCredentialManager, a TPM key that asks for the PIN or face on each use).
• Linux: a Secret Service item plus a separate presence check, because Secret Service has none.

Why the Secure Enclave, not a Keychain access-control flag

The Keychain's kSecAttrAccessControl (.userPresence) returns errSecMissingEntitlement (-34018) for a process without a keychain-access-groups entitlement. That covers both the legacy and the data-protection Keychain, and the engine is a Python sidecar. A non-permanent Secure Enclave key with the same access control needs no entitlement. The Secure Enclave enforces the prompt itself: a caller that can't show a prompt gets LAErrorNotInteractive (-1004).

PyObjC can't wrap a Secure Enclave key reference (its CF type lookup raises during the call), so MacEnclave calls Security.framework through ctypes. This adds no dependencies.

Tests

• Flow (test_human_approval_stdio_signer.py, real subprocess):

  • Desktop-style signing over the pipe is accepted.
  • Each of these records nothing: a cancelled prompt, another key's signature, an unregistered key (never asked to sign), a malformed or unknown response.
  • A removed key no longer signs, and removing an old key leaves its replacement.

• Desktop (tests/test_engine/test_approver_keychain.py, fake Secure Enclave and in-memory keyring, 27 tests):

  • Setup makes exactly one prompt. Only sealed material is stored.
  • Each of these stores and registers nothing: a cancelled setup, a failed Keychain save, a failed registration.
  • Every signature prompts. No key, cancel, or error means no signature.
  • A key stored without presence is refused.
  • Rotation (same name and new name), a failed rotation, and removal.
  • Bridge: Flow gets only --approver-signer stdio and no passphrase. Desktop refuses to sign a different request, decision, decider or route without prompting.
  • Dispatcher: the new commands work. They're served while a run waits and aren't on the agent socket.

• Real Mac (tests/test_approver_keychain_real.py, opt-in, no prompt shown):

  • Full setup, sign, rotate and remove against the real Secure Enclave and login Keychain, with the presence flag off.
  • A presence-flag key refuses a non-interactive unseal.
  • A sealed key opens only with its own Secure Enclave key.

  Run it with:

  cd packages/desktop
  OPENADAPT_REAL_KEYCHAIN_TESTS=1 uv run pytest tests/test_approver_keychain_real.py -v

  Result: 3 passed on an M2 Max. Hosted macOS runners are VMs with no Secure Enclave, so the test skips there.

• End to end, local: real Secure Enclave and Keychain, Desktop's FlowBridge, and this branch's Flow CLI. Flow stored the answer with attestation desktop-approver / desktop_key.

• Suites:

  • Desktop: 1,304 passed, 48 skipped. Ruff clean.
  • Frontend: 383 passed, tsc clean. New tests cover the setup-in-place-of-Approve flow.
  • Flow: approval suites 81 passed. Ruff, ruff format and mypy clean (561 files).

Not checked: a live Touch ID prompt from the packaged app. Automated tests can't touch the sensor.

Before this works in a released Desktop

• Desktop's frozen build pins openadapt-flow==2.1.0, which has neither --approver-signer nor approvers (fix: a person's approval needs a registered approver key's signature #1486 has the same dependency). Until a Flow release carries both and the pin moves, in-app setup refuses with "too old" and nothing is approved.
• desktop release intent will ask for a version bump. A bump publishes Desktop on merge, so as in fix: a person's approval needs a registered approver key's signature #1486 it's left to the release decision.

🤖 Generated with Claude Code

[abrichr]

Folded into #1519 so a single PR carries Desktop 0.24.0. #1519 contains every commit from this branch (through 21fa218), including the security-review fixes. Review and merge there.