Restore capability-gated --key signing on thv ai-plugin push

[samuv]

Summary

thv ai-plugin push --key was removed in #6438 because ToolHive could publish a key-signed plugin but could not verify and install it project-scoped. With the install-time public-key verification and lock-file support from #6524 and #6525, publishers can safely use key signing again and consumers can pin the matching public key on first install. This closes #6442.

Restoring the flag also reopens the server-side private-key trust boundary addressed by #6560: the thv serve process resolves and opens the requested key path. A peer-address check is insufficient because a public reverse proxy can make an untrusted request appear to arrive over loopback or IPC. This PR therefore extends #6560's protected discovery capability to plugin pushes rather than treating transport locality as authorization.

This change:

• Restores --key and the Key field across the plugin CLI, API DTO, client, and service, while retaining strict signing-input validation.
• Validates the signing choice (exactly one of key, identity_token, no_sign) in the handler before the capability guard and dispatch, so the endpoint's contract holds independent of which PluginService implementation is wired in. The validator lives in pkg/plugins and the service calls the same function for in-process callers.
• Forwards the key to the signer and keeps staged-then-promoted publication for signed artifacts.
• Requires the owner-protected local discovery capability before the API dispatches a key-bearing plugin push. Loopback or IPC without the capability receives 403.
• Has automatically discovered plugin clients attach the capability only to key-bearing pushes. Environment/manual URLs do not inherit it, and keyless or unsigned requests do not send it.
• Treats the capability as a bearer credential: it is refused over plaintext remote transports and is never followed across redirects.
• Documents that --key requires the locally discovered ToolHive server; remote or manually configured API URLs must use keyless signing.
• Regenerates the CLI and OpenAPI documentation, including the conditional capability header and 403 response.

Fixes #6442

Type of change

• New feature
• Bug fix
• Refactoring (no behavior change)
• Dependency update
• Documentation
• Other (describe):

Test plan

• Unit tests (task test)
• Linting (task lint-fix)
• E2E tests (task test-e2e)
• Manual testing (describe below)
• Generated API and CLI documentation (task docs)

Regression coverage includes:

• Signing-input validation for key, identity-token, unsigned, missing, and conflicting choices, at the route (service never reached) and in the shared validator.
• Key propagation through the CLI, API DTO, HTTP client, service, and signer.
• Capability rejection for loopback and IPC-shaped requests without the protected secret, plus dispatch with a matching capability.
• Client header scoping, discovery-only propagation, plaintext remote transport rejection, and redirect non-forwarding.
• CLI help text for the local-discovery and public-key requirements.

Changes

Area	Change
Plugin CLI and client	Restore --key, load the discovery capability, and protect credential transport
Plugin API	Accept key, validate the signing choice and require the capability before dispatch, and document 403
Plugin service	Validate the key signing arm and forward it to the signer
Trust model	Reuse the public-key verification and lock-file contract delivered by the lower stack
Tests	Cover end-to-end key propagation and the capability security boundary
Docs	Update architecture, CLI help, and generated OpenAPI output

API Compatibility

• This PR does not break the v1beta1 API, OR the api-break-allowed label is applied and the migration guidance is described above.

key and the conditional capability header are additive. Existing keyless and --no-sign callers are unchanged.

Does this introduce a user-facing change?

Yes. thv ai-plugin push --key <cosign.key> works again when the CLI uses automatic local server discovery. Consumers installing the resulting plugin project-scoped must pass thv ai-plugin install --public-key on first use; the key is pinned in toolhive.lock.yaml and reused by sync and upgrade thereafter. Remote and manually configured API URLs must use keyless signing.

Special notes for reviewers

• Originally stacked on Require a discovery capability for key signing #6560 and reusing its key-signing capability and header; rebased onto main after Require a discovery capability for key signing #6560 merged. The rebase also reconciled Document AI plugin support #6627's documentation rewrite, which recorded that plugin push has no --key: the architecture doc, CLI help, and the toolhive-cli-user skill reference now describe the restored flag and its local-discovery requirement.
• pushSkill in pkg/api/v1/skills.go has the same handler-level gap (signing choice enforced only by skillsvc). Left for a separate PR to keep this one scoped to plugins.
• Restoring the push flag must also land after the install-side key verification from Verify key-signed plugin installs against a public key #6524 and Honour a pinned cosign key on plugin sync and upgrade #6525, otherwise it recreates the publish-only dead end from --key push signing has no install-time verification path (plugins) #6442.
• --public-key remains install-only. upgrade and sync reuse the lock-file anchor, and in-place re-anchoring remains out of scope.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 93.87755% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.94%. Comparing base (c25e508) to head (932c1d3).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/plugins/client/client.go	80.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6528      +/-   ##
==========================================
- Coverage   78.94%   78.94%   -0.01%     
==========================================
  Files         781      782       +1     
  Lines       77784    77814      +30     
==========================================
+ Hits        61410    61431      +21     
- Misses      16369    16378       +9     
  Partials        5        5              

☔ 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.

[JAORMX]

Reviewed 55be810 against its exact stacked base abda3b6. This direct range consistently restores --key through CLI, client/DTO, API, validation, and signer options; the CLI correctly states that the signing host (thv serve) must access an encrypted key/password. No blocking findings in the PR-owned changes. This approval does not waive the separately requested changes on stacked #6525. Current CI includes an author-owned failing lifecycle job and remaining in-progress checks; it is not part of this review decision.

[JAORMX]

Fresh review of exact head ea4f6bb against exact stacked base #6560 at 11c47dd. This review attributes only the PR-owned range.\n\nThe prior private-key signing-oracle blocker is resolved by the inherited protected discovery capability and this PR's pre-dispatch plugin-route integration (pkg/api/v1/plugins.go:342-355; pkg/api/server.go:461-465). The capability is sourced only through protected local discovery, sent only for --key pushes, and protected from plaintext remote transport and redirects (pkg/plugins/client/client.go:301-324). The direct range correctly carries --key through CLI, client/DTO, API, service, and signer; exactly-one signing-mode validation and stage → sign → promote remain intact.\n\nNo merge-blocking findings in the direct range. The CLI help accurately states that COSIGN_PASSWORD is read by thv serve; the generated API schema's shorter description is non-blocking.\n\nCI is separate from this decision: all checks are successful except Helm Charts / Lint and Test Helm Charts, which is author-owned and does not establish a reviewed-code defect.

[JAORMX]

Follow-up panel review of the direct range 9d5248151d36df661b923b5b63caf82e92ce9b27...a58c2442925ecfacff028f80b1430a0a269e3950.

Blocking — direct API requests can bypass signing-mode validation

pushPlugin only validates reference before it dispatches to PluginService (pkg/api/v1/plugins.go:335-354), though the endpoint's documented contract requires exactly one of key, identity_token, or no_sign (pkg/api/v1/plugins_types.go:81-105). A request containing only reference therefore succeeds with a service implementation that does not repeat the concrete pluginsvc validation; the route test explicitly expects that invalid request to return 204 (pkg/api/v1/plugins_test.go:466-474). This makes the API contract dependent on a particular service implementation and permits generated/direct clients to issue a request that the real service rejects.

Validate the signing choice at the HTTP trust boundary before dispatch, and change the route test to expect 400. The capability guard can remain scoped to the key arm after that validation.

The previous signing-oracle finding is addressed by the inherited discovery capability plus this PR's route/client wiring. Exact-head CI is green; this correctness issue is independently blocking.

[samuv]

Addressed in 5c7a52a. Verified the finding first: pushPlugin checked only reference before dispatch, and the push plugin success route test pinned the reference-only 204.

• validateSigningInputs is lifted from pluginsvc to plugins.ValidatePushSigning (pkg/plugins/options.go). pushPlugin runs it right after the reference check, before requireKeySigningCapability and dispatch, so a reference-only request is a 400 from the endpoint itself. The capability guard stays scoped to the key arm. The service keeps calling the same function for in-process callers, so there is one copy of the contract rather than two.
• Route tests: the reference-only case now expects 400 signing credential required with no service expectation set; added a conflicting-choice case (no_sign + identity_token, 400, service never reached); push plugin service error now sends no_sign: true. TestValidatePushSigning in pkg/plugins covers all seven input shapes and asserts the 400 code on each rejection.

Also rebased onto main now that #6560 has merged. The four existing commits are unchanged apart from reconciling #6627's documentation rewrite, which had recorded that plugin push has no --key (architecture doc, CLI Long text and regenerated CLI doc, and the toolhive-cli-user skill reference).

One thing outside this PR's scope: pushSkill in pkg/api/v1/skills.go has the identical gap, with the choice enforced only by skillsvc. Candidate for a separate PR rather than widening this one.