docs(deploy): warn when codesign runs outside a GUI session

codesign reads the private key from the login keychain, and only the Aqua
session can reach it: agents/daemons run in launchd's Background domain,
where codesign fails with errSecInternalComponent even while Keychain
Access shows the keychain unlocked. sign-build.sh now warns with the fix
(run from a Terminal window, or `security unlock-keychain` first), and
docs/local-deployment.md records the rule.
This commit is contained in:
2026-09-18 01:45:43 +08:00
parent 28f409f2ca
commit 66fa2d9a06
2 changed files with 19 additions and 0 deletions
+8
View File
@@ -101,6 +101,14 @@ permission:
- with no Apple Development identity the scripts fall back to ad-hoc; that
still runs, but expect TCC prompts to reappear after every deploy
Deploys must run in a GUI session (a Terminal window on the machine): codesign
reads the private key from the login keychain, and only the Aqua session can
reach it. Agents/daemons run in launchd's Background domain, where codesign
fails with `errSecInternalComponent` even while Keychain Access shows the
keychain unlocked (`launchctl managername` reports `Background` vs `Aqua`).
`sign-build.sh` warns about this before failing; running the same script from
Terminal (or `security unlock-keychain` first) fixes it.
Agent sessions should also avoid recursive `$HOME` sweeps (`find ~`,
`du -sh ~`, ...) unless they prune TCC-protected folders (`~/Music`,
`~/Pictures`, `~/Movies`, `~/Library`): a walk into
+11
View File
@@ -39,6 +39,17 @@ if [ -z "$identity" ]; then
fi
echo "signing identity: $identity"
# codesign reads the private key from the login keychain, and only a GUI
# (Aqua) session can reach it: processes started by launchd/agents live in
# the Background domain and fail with errSecInternalComponent even while
# Keychain Access shows the keychain unlocked. Warn early with the fix
# instead of surfacing a bare codesign error. Ad-hoc signing needs no key.
if [ "$identity" != "-" ] && [ "$(launchctl managername 2>/dev/null || true)" != "Aqua" ]; then
echo "warning: not running in a GUI (Aqua) session; codesign cannot reach the login keychain." >&2
echo "warning: run the deploy from a Terminal window on this machine," >&2
echo "warning: or run 'security unlock-keychain' first. (errSecInternalComponent)" >&2
fi
# Bun's linker signature is not suitable after installation; re-sign once.
codesign --remove-signature "$build" 2>/dev/null || true
codesign --force --sign "$identity" --identifier run.hapi.cli "$build"