Skip to content

0031: macOS: a Secure Enclave key for the OS keychain tier, a helper app for dialogs, cgo isolated

  • Status: accepted
  • Date: 2026-10-03

Context

ADR 0009's tier 2 is a software X25519 identity whose private half is sealed under a key the OS keeps behind biometrics. The add-agent-daemon design planned this on macOS as a data-protection keychain item with a user-presence access control, created and read by a signed helper app bundle, because such an item needs a keychain access group, which needs an entitlement, which needs a provisioning profile, which only a bundle signed with a Developer ID can carry. The project has no Developer ID yet (it waits on a D-U-N-S number), so that design could be neither built nor tested. Group 6 of the change ran a spike first; this record states what replaced the plan and why.

Decision

  • The os-keychain tier is a Secure Enclave key, used by the daemon itself. The spike showed that an ad hoc signed program (no team id, no entitlements, no provisioning profile) can create a non-permanent P-256 key in the Secure Enclave (SecKeyCreateRandomKey with kSecAttrTokenIDSecureEnclave and kSecAttrIsPermanent false), read its opaque device-bound handle, and that a later process can reload the key from that handle and run ECDH with it, which the Secure Enclave refuses without user presence. No keychain item is written, so no entitlement and no team id are needed.
  • Wrapping scheme. Creating an identity asks the enclave for a key whose access control is private-key usage plus user presence (kSecAttrAccessibleWhenUnlockedThisDeviceOnly: any enrolled fingerprint or the login password, so adding a fingerprint does not lose the key). An ephemeral software P-256 key does ECDH with the enclave key's public key in software, so creation never prompts, and HKDF-SHA-256 (no salt, info vaultfold/os-keychain/secure-enclave/v1 followed by the ephemeral and the enclave public keys) gives the 32-byte wrapping key that seals the identity file. Unlocking repeats the ECDH inside the enclave, which raises the Touch ID or password prompt naming the identity. The identity file records se1: and the handle with both public keys, so it needs no store lookup; the handle is not secret (the enclave encrypts it to this device).
  • Reliance on an undocumented attribute. Reloading the key needs the handle passed as the toid attribute (kSecAttrTokenOID), which CryptoKit uses for dataRepresentation but the C headers do not document. SecKeyCreateWithData without it silently returns a new, unrelated enclave key whose ECDH is self-consistent, so every agreement compares the loaded key's public key with the one recorded at creation and a mismatch is "no such item", never a wrong wrapping key. The same check catches a handle copied from another Mac or invalidated by a Secure Enclave reset. If Apple changes or removes the attribute, the check fails closed and identities of this tier stop unlocking; the recovery is vaultfold key rotate from a passphrase identity or another device, and the keychain-item design above once a Developer ID exists.
  • The machine key (which seals the local cache, the caller allowlist and the audit MAC key) is sealed the same way under an enclave key with no user presence (kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, so it works with the screen locked and never prompts) into <Data>/machine.key.sealed. An existing data/machine.key is migrated on first use: sealed, published, read back and compared, then renamed aside, zeroed and removed, so an interrupted migration never leaves a half-zeroed key.
  • The helper app keeps what a bundle does better. Vaultfold Unlock.app (bundle id app.vaultfold.unlock, module cmd/vaultfold-authhelper, no entitlements) shows the named, iconed approval dialog (Allow once, Allow for this session, Deny, with Deny the default button), the OK-only rate-limit notice, and a fresh Touch ID or password presence check (LAContext with reuse disabled) for touch re-prompts. It is a confirmation gate over an already unlocked identity, never key protection. The daemon execs the bundle's executable directly for each prompt with one end of a socket pair as file descriptor 3, and kills it when the prompt's context ends. The helper checks that its peer is its parent, and when it is itself signed with an Apple-anchored team id, that the parent carries the same team id; the daemon resolves the helper with its caller verification and, when the daemon is itself project-signed, refuses any helper that is not. Dialog text is cut per field and stripped of control, separator and format characters, so a caller path cannot forge a line or reorder the text.
  • Where the helper is found: beside the executable (after resolving symlinks, then as invoked), in ../libexec/vaultfold/ relative to it, or in the desktop app's Contents/Helpers/ under /Applications or ~/Applications. Without it, os-keychain identities still unlock through the enclave; approval dialogs and Touch ID touch re-prompts are unavailable, approvals then go through vaultfold agent approve, requests on a touch-always collection (prod) are refused (touch-cancelled, since nothing can confirm presence), and doctor warns with the cask and pkg remedy.
  • cgo is isolated. It is used only on darwin, in build-tagged files of three packages (callerid for code signature validation against the audit token, lockwatch for the screen-lock notification and HID idle time, keychain for the Secure Enclave) and in the helper module, whose non-darwin build is a stub. Everything else is pure Go on every OS, so make crossbuild (CGO-free) still builds and vets every module. A CGO-free darwin build is supported and degraded, never broken: no Secure Enclave (os-keychain identities answer backend-unavailable with a remedy), caller identity by cdhash only with no signer trust, and no screen-lock or idle trigger (sleep is still caught by clock divergence).

Consequences

  • Packaging: darwin release binaries are built on a macOS host with cgo, so a bare binary (npm, install script, an archive) has the os-keychain tier and lacks only the helper's dialogs and Touch ID re-prompts. The Homebrew cask and the pkg install the helper. This corrects the earlier assumption, still written in add-distribution's design.md, that a bare binary has no os-keychain tier; that change carries a note to reconcile it.
  • No Developer ID, notarisation or Apple account is needed to build and test the tier. The helper's release-signing paths (a project-signed daemon accepting only a project-signed helper, and the helper verifying its parent's team id) cannot be exercised until one exists.
  • The key never leaves the Secure Enclave and is bound to this Mac: a backup restored to another Mac, or an enclave reset, cannot unlock the identity. Keep a second device or a passphrase identity as a member of every vault.
  • The ephemeral software key used at creation cannot be zeroed (Go's crypto/ecdh keeps it opaque); it is dropped. The enclave's shared secret is copied out and zeroed on both sides.
  • Touch ID unlock, the helper dialog, and screen-lock locking on a real screen lock are manual checks that need a human; they are listed in the group 6 PR (#112).

Alternatives considered

  • Data-protection keychain item through the helper (the original design). Deferred: needs a Developer ID to build or test at all.
  • A login keychain item without user presence. Rejected: any process of the user can read it without a prompt, which is no better than a file.
  • Host the code-signature checks in the helper so the CLI can be CGO-free. Deferred (design.md Open Question 3): the cgo files are small and isolated.
  • open -g -n to launch the helper. Rejected: the daemon could not bind the helper to a pipe it created or verify the process it talks to.