Ergonomics: provisioning a headless signing agent is a ~9-step ceremony — make it one command #382

Activity

1. bordumb

   added

   enhancementNew feature or requestNew feature or request

   on Jul 18, 2026
2. bordumb commented on Jul 18, 2026

   

   bordumb

   on Jul 18, 2026

   ContributorAuthor

   More actions

   Field report: drove two full releases headlessly with a provisioned agent

   Since filing this, I actually provisioned the claude-release agent and used it to run two complete auths releases (v0.1.7, v0.1.8) with zero fingerprints — bump commit + release tag signed by the agent (sign_release scope), and CI's verify-commits accepted the agent-signed commits against the pinned root. So the north star ("one command → releases with no fingerprint") is real and proven, not aspirational. That said, daily use surfaced friction beyond the provisioning ceremony that auths agent provision (or adjacent fixes) should absorb:

   New pain points, from actually signing with the agent

   1. auths sign ignores its own signer selection — every sign needs a GIT_CONFIG hack. auths sign <ref> --scope … amends the commit, and the amend reads the repo's user.signingkey, not a flag/env. Without an override it fails [AUTHS-E5909] keychain unavailable: Key not found. Every single sign in the release flow needed:

      GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=user.signingkey GIT_CONFIG_VALUE_0=auths:claude-release auths sign HEAD --scope sign_release

      This is item B above, now with a concrete, repeated failure mode. auths sign --signer auths:<alias> (or AUTHS_SIGNING_KEY) must drive the amend directly.

   2. The commit-trailers file is a static cache, not live resolution. Signing stamps Auths-Id/Auths-Device from the literal $AUTHS_HOME/commit-trailers file. Switching between root-signing and agent-signing (or a stale agent registry) silently stamps the wrong device, and the commit then fails verify with SignerKeyMismatch. Provisioning writes this once; nothing keeps it correct as you switch identities. (This also caused a separate human-facing bug — see identity: signer resolution must not stamp a delegated device it can't sign as #383.)

   3. Dual-registry AUTHS_HOME juggling. To sign as the agent you must point AUTHS_HOME/AUTHS_REPO at the agent's delegate-machine registry (so the resolver finds the agent as signer), but to verify you must env -u AUTHS_HOME -u AUTHS_REPO back to the default. Getting this wrong yields confusing verdicts. provision's env.sh should encapsulate it, and auths verify shouldn't need the unset dance.

   4. .auths/ci-bundle.json must be regenerated after every new delegation — and committed. CI verifies agent-signed commits against the committed bundle; a bundle predating the delegation fails Root never anchored this device's delegated inception. For a release repo this is a required, easy-to-forget step provision should perform (and re-run on re-delegation).

   Blocker status update

   • keychain: Secure Enclave custody fixes — delegation works on SE roots, software keys are never silently discarded #381 (Secure Enclave custody) — MERGED. Delegation now works on SE roots (the Unknown encryption tag crash + the store_key-discards-material bug are fixed). SE provisioning is unblocked.
   • identity: signer resolution must not stamp a delegated device it can't sign as #383 (signer resolution) — MERGED. A provisioned agent no longer hijacks the human operator's interactive signing identity (the resolver only adopts a delegated device whose key is local and non-agent: role). This is a hard requirement for provision: creating a signing agent must never break the human's own auths verify. Worth stating explicitly in the acceptance criteria.

   One addition to the plan

   auths agent provision should mark the delegation agent-role and rely on #383's rule, so the human's identity is never affected — and it should own the ci-bundle.json refresh (point 4) and emit the env.sh that hides the dual-registry env (point 3). Combined with fix B (point 1), signing collapses to source env.sh && auths sign <ref>.

   🤖 Generated with Claude Code
3. bordumb commented on Jul 20, 2026

   

   bordumb

   on Jul 20, 2026

   ContributorAuthor

   More actions

   Field report #2: v0.1.13 release — the signing gap is now tags, not just commits

   Drove another full headless release (v0.1.13) with the provisioned claude-release agent. The commit half is solid — but the release surfaced a gap this issue doesn't cover yet, plus a concrete re-confirmation of item B.

   New: agent-signed tags have no path — and "signed releases" needs them

   The release commit signs fine via the documented dance. The tag does not. git tag -a (what 1_github.py --push and any annotated tag runs) routes through tag.forceSignAnnotated=true → gpg.ssh.program=…/auths-sign (the SE wrapper) → dies headless:

   error: [ERROR] [AUTHS-E5910] key decryption failed: Signing failed: Secure Enclave key operation failed
   error: unable to sign the tag
   ERROR: git tag failed (exit 128)
   

   There is no auths-native way to agent-sign a tag: auths sign --scope is "Commit-only" (per --help), and artifact signing (--key/--device-key → .auths.json) has no scope and isn't a git object. So the only headless path is to create an unsigned tag and lean on the signed commit for provenance:

   git -c tag.forceSignAnnotated=false tag -a vX.Y.Z -m "release: release for X.Y.Z"

   If the product promise is signed releases, item B (signer selection) should extend to tags — e.g. auths sign refs/tags/vX.Y.Z --scope sign_release, or auths agent provision should emit an env that makes git tag -s resolve to the agent key headlessly. Right now a released tag carries no agent signature.

   The release scripts aren't agent-aware either

   A provisioned --profile ci/assistant agent still can't use the repo's own release tooling: just release runs cargo + assumes the SE fingerprint prompt, and 1_github.py --push hits the tag-signing trap above and only pushes the tag (never main). I had to bypass both and hand-roll the tag + main push. Whatever provision ships, --profile ci should also make scripts/releases/* work under the agent — otherwise the "one command → headless releases" story stops one step short of the actual release command. (I rewrote scripts/releases/README.md into a working headless runbook in the meantime, but that's a patch over the tooling gap.)

   Item B, re-confirmed live in v0.1.13

   Every auths sign in the release still needed the GIT_CONFIG hack; without it, [AUTHS-E5909] keychain unavailable: Key not found. auths sign has no --signer flag yet (--help shows only --key/--device-key/--scope/--note), so the amend still falls back to the repo's user.signingkey:

   GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=user.signingkey GIT_CONFIG_VALUE_0=auths:claude-release \
     auths sign HEAD --scope sign_release

   Net: the provisioning ceremony is the headline, but releasing with the provisioned agent still needs (1) a tag-signing story, (2) headless-aware release scripts, and (3) B's --signer. Suggest folding (1) and (2) into this issue's scope, since a "headless signing agent" that can't sign the release tag or run the release script isn't done.

   🤖 Field report from a Claude Code session that cut v0.1.13.
4. bordumb

   added

   good first issueGood for newcomersGood for newcomers

   on Jul 20, 2026
5. bordumb

   closed this as completedin #409on Jul 24, 2026