oci/plugins: Phase 1 OCI artifact package for plugins (THV-0077) (#136)

* oci/plugins: add Phase 1 OCI artifact package for plugins

Add the `oci/plugins` package mirroring `oci/skills` file-for-file,
built on the shared `oci/artifact` primitives from Phase 0. It packages
a Claude Code plugin directory (`.claude-plugin/plugin.json` bundling
commands, agents, skills, hooks, MCP/LSP server configs) into a
reproducible, content-addressable multi-platform OCI artifact, and
provides ORAS push/pull and a local store rooted at `toolhive/plugins`.

- mediatypes.go: ArtifactTypePlugin "dev.toolhive.plugins.v1";
  dev.toolhive.plugins.* labels/annotations including the plugin-specific
  .components inventory and .requires; PluginConfig +
  PluginConfigFromImageConfig.
- interfaces.go: RegistryClient (Push/Pull), PluginPackager.
- packager.go: index -> per-platform manifest -> config + single
  plugin.tar.gz layer, SOURCE_DATE_EPOCH-aware for reproducible digests.
- registry.go: ORAS push/pull + Docker credential auth.
- store.go: local OCI store under xdg.DataHome.
- mocks/ via go:generate mockgen.

Tests cover the exit gates (packager determinism, config round-trip,
store put/get) plus end-to-end package -> push -> pull -> extract
integration tests. Coverage 73.6%.

Part of stacklok/toolhive#5525
Closes #131

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* oci/plugins,skills: address review feedback (security + determinism)

Addresses jhrozek's review on PR #136.

Blockers (plugins):
- B1: validate digest before deriving blob path in Store.deleteBlob, plus a
  store-root prefix guard, preventing path traversal / arbitrary file deletion.
- B2: Lstat + size-check the plugin manifest before reading it, rejecting a
  symlinked manifest (TOCTOU) and avoiding oversized allocation.
- B3: Pull tags the local store under the full OCI reference instead of the
  bare tag, preventing cross-plugin tag collisions in the shared store.

Other findings (plugins):
- validatePluginDir: absolute-path guard (the post-Clean ".." check was inert).
- fetchContent: bound local reads with io.LimitReader(MaxBlobSize).
- gzip member header now honours opts.Epoch.
- normalize zero-value PackageOptions.Epoch so config/tar/gzip agree.
- maxPluginTotalSize lowered to 95 MB so tar overhead can't exceed the
  extraction-time MaxDecompressedSize limit.
- preserve file modes through packaging (executable scripts stay executable).
- retry.DefaultClient for transient registry errors.
- DeleteBuild/DeleteTag/Tag serialized under a mutex.
- json.Marshal of OCI labels/annotations now panics on the (invariant) error.

Tests (plugins): ported TestStore_DeleteBuild, added an index-branch case,
a deleteBlob invalid-digest guard, and a file-mode preservation test.
Coverage 73.6% -> 81.7%.

Parity fixes applied to oci/skills for findings marked "same in skills":
B1, B3, fetchContent bound, gzip epoch, total-size limit, retry client.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: JAORMX

CLAUDE.md

@@ -74,6 +74,7 @@ task license-fix   # Add missing license headers
 | `logging` | Pre-configured `*slog.Logger` factory with consistent ToolHive defaults (Alpha) |
 | `oci/artifact` | Artifact-agnostic OCI tar/gzip/extraction/platform primitives shared by oci/skills and oci/plugins (Alpha) |
 | `oci/skills` | OCI artifact types, media types, and registry operations for ToolHive skills (Alpha) |
+| `oci/plugins` | OCI artifact types, media types, and registry operations for ToolHive plugins (Alpha) |
 | `postgres` | PostgreSQL connection pool with optional AWS RDS IAM dynamic auth (Alpha) |
 | `recovery` | HTTP panic recovery middleware (Beta) |
 | `validation/http` | RFC 7230/8707 compliant HTTP header and URI validation |

README.md

@@ -27,6 +27,7 @@ The ToolHive ecosystem spans multiple Go repositories, and several of these proj
 | `httperr` | Stable | Wrap errors with HTTP status codes |
 | `logging` | Alpha | Pre-configured `*slog.Logger` factory with consistent ToolHive defaults |
 | `oci/skills` | Alpha | OCI artifact types, media types, and registry operations for skills |
+| `oci/plugins` | Alpha | OCI artifact types, media types, and registry operations for plugins |
 | `postgres` | Alpha | PostgreSQL connection pool with optional AWS RDS IAM dynamic auth |
 | `recovery` | Beta | HTTP panic recovery middleware |
 | `validation/http` | Stable | RFC 7230/8707 compliant HTTP header and URI validation |

oci/plugins/doc.go

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+Package plugins provides OCI artifact types, media types, local storage, and
+remote registry operations for ToolHive plugin packages.
+
+A plugin is an OCI artifact containing a .claude-plugin/plugin.json manifest and
+its component directories. This package defines the constants, data structures,
+storage layer, packager, and registry client that the rest of the ToolHive
+ecosystem uses to package, push, pull, and cache plugins as OCI images.
+
+# Media Types and Constants
+
+Standard OCI media types and ToolHive-specific annotation/label keys:
+
+	// Artifact type identifies a plugin manifest
+	plugins.ArtifactTypePlugin // "dev.toolhive.plugins.v1"
+
+	// Annotations carry metadata in manifests
+	plugins.AnnotationPluginName
+	plugins.AnnotationPluginVersion
+	plugins.AnnotationPluginComponents
+
+	// Labels carry metadata in OCI image configs
+	plugins.LabelPluginName
+	plugins.LabelPluginFiles
+
+# Registry Client
+
+The [Registry] type implements [RegistryClient] for pushing and pulling plugin
+artifacts to/from OCI-compliant registries (GHCR, ECR, Docker Hub, etc.). It
+uses ORAS for registry operations and the Docker credential store for
+authentication by default:
+
+	reg, err := plugins.NewRegistry()
+	// Push an artifact
+	err = reg.Push(ctx, store, indexDigest, "ghcr.io/myorg/my-plugin:v1.0.0")
+	// Pull an artifact
+	digest, err := reg.Pull(ctx, store, "ghcr.io/myorg/my-plugin:v1.0.0")
+
+Use functional options to customise behaviour:
+
+	reg, err := plugins.NewRegistry(
+	    plugins.WithPlainHTTP(true),           // for local dev registries
+	    plugins.WithCredentialStore(myStore),  // custom auth
+	)
+
+# Stability
+
+This package is Alpha. Breaking changes are possible between minor versions.
+*/
+package plugins

oci/plugins/errors.go

@@ -0,0 +1,36 @@
+// SPDX-FileCopyrightText: Copyright 2026 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package plugins
+
+import "errors"
+
+// Sentinel errors returned (wrapped) by the packager so callers can classify
+// failures with errors.Is instead of matching error message strings. The
+// underlying error message is preserved at each call site via fmt.Errorf
+// with %w; only the classification is added.
+var (
+	// ErrInvalidPluginDir indicates the plugin directory is missing, not a
+	// directory, or otherwise unsafe to read (e.g. contains path traversal).
+	ErrInvalidPluginDir = errors.New("invalid plugin directory")
+
+	// ErrPluginManifestMissing indicates .claude-plugin/plugin.json is not
+	// present in the plugin directory.
+	ErrPluginManifestMissing = errors.New(".claude-plugin/plugin.json missing")
+
+	// ErrInvalidPluginManifest indicates the plugin manifest is malformed,
+	// oversized, or missing required fields such as the plugin name.
+	ErrInvalidPluginManifest = errors.New("invalid plugin manifest")
+
+	// ErrTooManyFiles indicates the plugin directory exceeds the maximum
+	// allowed number of files.
+	ErrTooManyFiles = errors.New("too many files in plugin directory")
+
+	// ErrPluginTooLarge indicates the plugin directory exceeds the maximum
+	// allowed total size.
+	ErrPluginTooLarge = errors.New("plugin directory too large")
+
+	// ErrInvalidPluginFile indicates a per-file issue inside the plugin
+	// directory: a symlink, a non-regular file, or an unreadable entry.
+	ErrInvalidPluginFile = errors.New("invalid plugin file")
+)