From 66fa2d9a06c341ffb8fe95d657d5a5b3ef61ce7c Mon Sep 17 00:00:00 2001 From: wusumac <736139669@qq.com> Date: Fri, 18 Sep 2026 01:45:43 +0800 Subject: [PATCH] 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. --- docs/local-deployment.md | 8 ++++++++ scripts/sign-build.sh | 11 +++++++++++ 2 files changed, 19 insertions(+) diff --git a/docs/local-deployment.md b/docs/local-deployment.md index b62c5c7b..bcf6e3e2 100644 --- a/docs/local-deployment.md +++ b/docs/local-deployment.md @@ -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 diff --git a/scripts/sign-build.sh b/scripts/sign-build.sh index c25527c3..833aec7f 100755 --- a/scripts/sign-build.sh +++ b/scripts/sign-build.sh @@ -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"