Sign pushes by default and remove the lock feature gate

[samuv]

Note

Stack 2 of RFC THV-0080 — final PR (stack #6128, on top of #6137). Closes #5899 when it lands.

Summary

The last piece: signing on publish, and the feature gate comes out.

• thv skill push signs by default: --key signs the pushed artifact with a cosign private key (the signature manifest is attached at the .sig tag, so project-scoped installs verify it; the flow the signer/verifier PRs round-trip in tests). Pushing unsigned requires an explicit --no-sign, and a failed signing fails the push — an artifact is never silently published unsigned. Threaded through CLI, client, and API.
• TOOLHIVE_SKILLS_LOCK_ENABLED is removed: with verification on consume (installs, sync, upgrade) and signing on publish both in place, the lock file graduates from experimental. The gate, its env var, the "(experimental)" command markers, and every gated test-server setup are gone; the lock file, toolhive.requires materialization, sync, upgrade, and signature verification are now standard behavior for project-scoped skills. This is THE user-facing change of the stack.
• Trust-model docs rewritten (docs/arch/12-skills-system.md): the "drift detection over a repository-editable file" honesty note graduates to the verified model — TOFU semantics with the identity displayed, --allow-unsigned / --allow-signer-change escape hatches, the provisional: git marker, and an explicit list of what deliberately remains trusted on faith (unsigned exceptions, the lock file as reviewable policy, the first-use anchor).

Type of change

• New feature (non-breaking change which adds functionality)

Test plan

• Unit tests pass locally (task test, full suite with -race)
• Linting passes (task lint-fix, 0 issues)
• New unit tests: push requires an explicit signing decision (400 before anything is pushed); push signs with the provided key pinned to the pushed digest; signing failure fails the push. Gate-dependent tests updated: the gated-server E2E blocks merge into the standard suites; the legacy-unmanaged adopt fixture now constructs pre-lock state directly instead of toggling the gate.
• task docs regenerated.

Does this introduce a user-facing change?

Yes. The skills lock file feature is no longer gated: project-scoped installs write toolhive.lock.yaml, verify signatures (unsigned installs need --allow-unsigned), and thv skill sync/upgrade work without TOOLHIVE_SKILLS_LOCK_ENABLED. thv skill push now requires --key or an explicit --no-sign.

Special notes for reviewers

• The signed round-trip interop check (cosign verify --key accepts our attached signature) is covered by the signer package's unit tests plus toolhive-core's key-signed retrieval tests; a manual cosign-CLI check against a real registry is worth doing once before release.
• Follow-ups tracked on Track: Skills lock file + Sigstore signing (RFC THV-0080) #5899 at close: Rekor proof validation for git (removes provisional:), keyless/OIDC signing, catalog-supplied expected identity, and moving pkg/skills/signer to toolhive-core.

Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.23404% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.82%. Comparing base (b391771) to head (1c8d470).

Files with missing lines	Patch %	Lines
pkg/skills/signer/key.go	77.27%	3 Missing and 2 partials ⚠️
pkg/skills/skillsvc/build.go	93.33%	1 Missing ⚠️

Additional details and impacted files

@@                        Coverage Diff                         @@
##           skills-sig/13b-provenance-display    #6139   +/-   ##
==================================================================
  Coverage                              72.81%   72.82%           
==================================================================
  Files                                    743      742    -1     
  Lines                                  77674    77708   +34     
==================================================================
+ Hits                                   56558    56589   +31     
- Misses                                 17146    17150    +4     
+ Partials                                3970     3969    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[samuv]

Rebased onto the updated #6137 branch and marked ready. The gate removal verifies clean: pkg/skills/feature_gate.go is gone, no LockFileFeatureEnabled / TOOLHIVE_SKILLS_LOCK_ENABLED / errExperimentalLockFeature references remain outside tests, and both (experimental) CLI markers are gone.

A shipping blocker this PR had

The plan for this stack promised one manual check that was never run: "signing round-trip interop — cosign verify --key accepts our attached signature". I ran it. It failed:

$ cosign generate-key-pair
$ thv skill push 127.0.0.1:15000/interop/demo:v1 --key cosign.key
Error: failed to push skill: signing pushed artifact: decoding signing key:
  asn1: structure error: tags don't match (16 vs {class:1 tag:27 ...}) pkcs8 @2

--key could not read any key produced by cosign generate-key-pair — the only realistic way a user obtains one. Since this PR makes signing the default on push, that would have shipped as a broken flag.

The cause is a collision of formats behind one label. cosign seals the PKCS#8 key with scrypt + nacl/secretbox (go-securesystemslib/encrypted); cryptoutils.MarshalPrivateKeyToEncryptedDER writes PKCS#8 standard encryption. Both land in a PEM block labelled ENCRYPTED SIGSTORE PRIVATE KEY, and loadKeypair only understood the second.

The tests missed it because the fixtures were built with cryptoutils — and TestSignOCIEncryptedKey even asserted in a comment that its fixture was "what cosign generate-key-pair produces". It wasn't. That comment is now corrected.

Fixed by decrypting the cosign sealing when the label indicates it, falling back to the PKCS#8 form so both keep working, and reporting a wrong password as a password problem instead of an ASN.1 parse failure.

Interop now proven

$ thv skill push 127.0.0.1:15000/interop/final:v1 --key cosign2.key
$ cosign verify --key cosign2.pub --insecure-ignore-tlog=true 127.0.0.1:15000/interop/final:v1

Verification for 127.0.0.1:15000/interop/final:v1 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key

Verified with both an empty-password key and a password-protected one, against a real registry, using the stock cosign CLI.

New regression tests build fixtures with encrypted.Encrypt — the same call cosign makes — so they fail without the fix. I confirmed that by reverting the change and watching them go red, rather than assuming.

One behaviour worth documenting, not fixing

COSIGN_PASSWORD has to be set on the thv serve process, not the shell running the CLI, because signing happens server-side. A password-protected key fails with the password in your shell and succeeds with it in the server's environment. I have documented it in the flag help and the Options.Key doc comment rather than changing the design — forwarding the passphrase over the API would mean putting a secret in a request body.

task test, task lint-fix, and task docs green at the branch tip.

Related: stacklok/toolhive-core#230 carries the same fix, since that PR moves this package into core.