feat(registry/types): add signer-identity provenance to Skill

[samuv]

What

Adds an optional Provenance field to registry.Skill, so a skills catalog can declare who is expected to sign a skill.

// Provenance is the expected signer identity for this skill, checked on
// first install instead of trust-on-first-use. Absent means unconstrained
// — most catalog entries won't have this for a while, and that must not
// break installs; it's an opt-in tightening per entry, not a requirement.
Provenance *Provenance `json:"provenance,omitempty" yaml:"provenance,omitempty"`

This is the prerequisite for stacklok/toolhive#6310 ("Catalog-supplied expected identity, so first install is not trust-on-first-use").

This PR is toolhive-core only. It does not wire anything up in toolhive — that's a follow-up PR there, once this ships in a release and toolhive's go.mod bumps to it. Same pattern as #234/#235 → toolhive's skills-keyless/01-core-signer (stacklok/toolhive#6383).

Design notes

Reuses the existing registry.Provenance (registry/types/registry_types.go) rather than defining a parallel struct for skills. It already carries the same six semantic fields skills need, including RepositoryRef and RunnerEnvironment — the two that toolhive's lockfile.Provenance added for skills in its stacklok/toolhive#6309 follow-up. Two parallel structs for the same concept just drift.

Added directly to Skill, mirroring ImageMetadata.Provenance. Servers keep provenance indirect for MCP-registry-format reasons (raw upstream ServerJSON nests it in a _meta publisher-extension blob, converted by ServerJSONToImageMetadata), but Skill has no such raw/converted split — it is the format toolhive-catalog serializes as skill.json, field-for-field.

container/verifier.Sigstore.VerifyServer is untouched. It's already generic over an OCI image ref and a *Provenance — nothing in its body or in compareBaseProperties is server-specific — so it should work for skills unmodified. A rename to something generic (Verify, with VerifyServer as a deprecated alias) is tempting now that it's about to gain a non-server caller, but CLAUDE.md's "never change exported interface signatures without discussion" applies. Happy to open that as a separate issue if people want it; blast radius is small (3 non-test call sites).

One deliberate divergence from the server schema

The skill schema's provenance $def mirrors the server one in publisher-provided.schema.json — same fields, descriptions, and examples — but omits its format keywords (uri on repository_uri/cert_issuer, hostname on sigstore_url).

Provenance's five core fields have no omitempty, so a partially populated provenance marshals "repository_uri": "". gojsonschema rejects that:

valid=false errs=[u: Does not match format 'uri' h: Does not match format 'hostname']

Keeping the formats would mean setting only signer_identity — the realistic catalog case, and exactly the opt-in shape this field is for — fails Validate(). The reason is recorded in the $def's own description, and there are regression tests pinning it (only signer identity, empty provenance object).

The alternative, adding omitempty to Provenance's json tags, would change serialization for MCP servers too, so I left it alone.

A local $defs/provenance is used rather than a cross-file $ref, because publisher-provided.schema.json isn't in schema_validation.go's referencedSchemas preload list and the ref wouldn't resolve offline.

Tests

New registry/types/skills_types_test.go, all table-driven:

• JSON round-trip — nil Provenance omitted (asserted on the raw map, not just the decoded value), full / partial / with-attestation preserved.
• YAML round-trip — same omitempty and round-trip behavior.
• Validate() with provenance — absent, full, signer-identity-only, empty object, with attestation. None may fail.
• ValidateSkillBytes — raw JSON shapes the Go struct can't express (provenance not an object, signer_identity not a string, attestation not an object) correctly rejected.

Verification

• task — green, 0 lint issues, all packages pass.
• task license-check — passes.
• registry/types coverage: 81.1% (repo requires ≥70%).
• Existing TestSkill_Validate passes unmodified — this change is purely additive.

No live Sigstore/network verification here; actually using VerifyServer against a real signed skill happens in the follow-up toolhive PR.

Out of scope

• toolhive — the pkg/skills/verifier/skillsvc wiring that passes a catalog-supplied Provenance instead of nil. That's Catalog-supplied expected identity, so first install is not trust-on-first-use toolhive#6310's remaining work, blocked on this merging + releasing + a go.mod bump.
• toolhive-catalog — populating provenance for real entries (e.g. dockyard's /.github/workflows/build-skills.yml). Separate repo, only possible once this exists in a released version.
• dockyard — doesn't consume this verification path at all; signs independently with stock cosign.

🤖 Generated with Claude Code