Problem
docs/arch/12-skills-system.md and docs/arch/14-plugins-system.md explain the mechanics of --key / --public-key signing well: the key must arrive out of band, dispatch is lock-first, --allow-unsigned and --allow-signer-change do not substitute, re-anchoring means uninstall and reinstall. What neither document says is that a publisher choosing --key over keyless is choosing a lower assurance level, or why.
The fact that shaped the whole #6442 design is only recorded in an issue comment there:
Key signing writes no Rekor entry. toolhive-core/container/signer/signer.go: "FulcioURL and RekorURL apply to keyless signing only and are ignored for the key-pair flow." A --key bundle is a bare detached signature: no certificate, no transparency log, therefore no signing time and no revocation.
Consequences that follow, none of which the docs state
- A key-pinned entry has no signing timestamp, so there is no replay window to reason about and nothing a future transparency-log check could tighten.
- There is no revocation: a leaked key cannot be invalidated anywhere the verifier looks; the only remedy is every consumer re-anchoring (which today is uninstall + reinstall, see the re-anchor follow-up issue).
- A key-pinned entry cannot participate in catalog-declared provenance (
regtypes.Provenance is certificate-shaped) or in identity-based signer-change detection — the verifier can only answer "does this key verify this signature", never "who signed this" (keySignedPublicKeyHint = "cosign-keypair" is a fixed placeholder).
- "Wrong key" and "damaged signature" are indistinguishable, which is why
classifyKeyVerifyError says so rather than picking one.
Proposed change
Docs-only. Add a short "Trust tiers" paragraph to the key-signing section of 12-skills-system.md stating the above plainly, and a one-sentence pointer from 14-plugins-system.md#trust-model. Consider a matching sentence in the --key flag help on thv skill push and thv ai-plugin push ("Key-pair signing records no certificate or transparency-log entry; prefer keyless signing where an OIDC identity is available"), regenerating docs/cli with task docs.
Related
Problem
docs/arch/12-skills-system.mdanddocs/arch/14-plugins-system.mdexplain the mechanics of--key/--public-keysigning well: the key must arrive out of band, dispatch is lock-first,--allow-unsignedand--allow-signer-changedo not substitute, re-anchoring means uninstall and reinstall. What neither document says is that a publisher choosing--keyover keyless is choosing a lower assurance level, or why.The fact that shaped the whole #6442 design is only recorded in an issue comment there:
Consequences that follow, none of which the docs state
regtypes.Provenanceis certificate-shaped) or in identity-based signer-change detection — the verifier can only answer "does this key verify this signature", never "who signed this" (keySignedPublicKeyHint = "cosign-keypair"is a fixed placeholder).classifyKeyVerifyErrorsays so rather than picking one.Proposed change
Docs-only. Add a short "Trust tiers" paragraph to the key-signing section of
12-skills-system.mdstating the above plainly, and a one-sentence pointer from14-plugins-system.md#trust-model. Consider a matching sentence in the--keyflag help onthv skill pushandthv ai-plugin push("Key-pair signing records no certificate or transparency-log entry; prefer keyless signing where an OIDC identity is available"), regeneratingdocs/cliwithtask docs.Related
--keypush signing has no install-time verification path (plugins) #6442 (design comment "Five facts that shaped it", fact 1)