feat(update): OCI registry distribution for update artifacts

Phase 7 of v0.3. The update agent can now pull update artifacts from any
OCI-compliant registry (ghcr.io, quay.io, harbor, zot, etc.) alongside the
existing HTTP latest.json protocol. Multi-arch artifacts are resolved
through manifest indexes so the same tag (e.g. "stable") yields the
right kernel + initramfs for runtime.GOARCH.

New package update/pkg/oci (~280 LOC, 9 tests):
- Client wraps oras-go/v2's remote.Repository. NewClient parses
  host/path references; WithPlainHTTP toggle for httptest.
- FetchMetadata resolves a tag and returns image.UpdateMetadata from
  manifest annotations (io.kubesolo.os.{version,channel,architecture,
  min_compatible_version,release_notes,release_date}). No blobs fetched.
- Pull resolves the tag, walks index → arch-specific manifest, downloads
  kernel + initramfs layers identified by their custom media types
  (application/vnd.kubesolo.os.kernel.v1+octet-stream and
  application/vnd.kubesolo.os.initramfs.v1+gzip), verifies their digests
  against the manifest, returns the same image.StagedImage shape the
  HTTP client produces.
- Cross-arch single-arch manifests are refused via the AnnotArch check
  (defense in depth on top of the gates in cmd/apply.go).
- Tests use a hand-rolled httptest registry implementing /v2/probe,
  manifest fetch by tag-or-digest, blob fetch by digest. Cover index
  arch-selection, single-arch manifests, missing-arch error, tampered
  blob rejection (digest mismatch), and reference parsing.

Dependencies added: oras.land/oras-go/v2 v2.6.0 plus its transitive
opencontainers/{go-digest,image-spec} and golang.org/x/sync. All small
and well-maintained; total binary size impact is negligible relative to
the existing 6.1 MB update agent.

cmd/apply.go:
- New --registry and --tag flags; mutually exclusive with --server.
- applyMetadataGates extracted as a helper, called from both transports
  so channel/arch/min-version policy is enforced identically regardless
  of how metadata was fetched.
- State transitions identical to the HTTP path: Checking → Downloading
  → Staged, with RecordError on any failure.

cmd/opts.go: --registry, --tag CLI flags. update.conf "server=" already
accepts either an HTTP URL or an OCI ref; the agent distinguishes by
which CLI/conf field carries the value.

build/scripts/push-oci-artifact.sh: new tool that publishes a single-arch
update artifact via the oras CLI with our custom media types and
annotations. After running for each arch, the operator composes the
multi-arch index with `oras manifest index create`. Documented inline.

build/Dockerfile.builder: installs oras 1.2.3 from upstream releases so
the Gitea Actions build container can run the new script.

Signature verification on the OCI path is intentionally deferred — the
artifact format is digest-verified end-to-end via oras-go, and Ed25519
signature consumption via OCI referrers is a follow-up. Plain HTTP
clients keep their existing signature path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

update/pkg/oci/oci.go

@@ -0,0 +1,281 @@
+// Package oci pulls KubeSolo OS update artifacts from an OCI-compliant
+// container registry (e.g. ghcr.io). It is the registry-native alternative
+// to the legacy HTTP `latest.json` protocol implemented in pkg/image.
+//
+// # Artifact layout
+//
+// An update is published as a single OCI artifact under a tag like
+// `stable` or `v0.3.0`. The tag may point at either:
+//
+//   - A manifest index (preferred) containing per-architecture manifests.
+//     The agent picks the one matching runtime.GOARCH.
+//   - A single manifest (used for arch-specific tags such as
+//     `v0.3.0-amd64`). The agent verifies architecture against the
+//     manifest's platform annotation before trusting it.
+//
+// Each per-architecture manifest carries two layers:
+//
+//	application/vnd.kubesolo.os.kernel.v1+octet-stream     // vmlinuz / Image
+//	application/vnd.kubesolo.os.initramfs.v1+gzip          // kubesolo-os.gz
+//
+// And these annotations (read into image.UpdateMetadata):
+//
+//	io.kubesolo.os.version                "v0.3.0"
+//	io.kubesolo.os.channel                "stable"
+//	io.kubesolo.os.min_compatible_version "v0.2.0"
+//	io.kubesolo.os.architecture           "amd64"
+//	io.kubesolo.os.release_notes          (optional, short)
+//	io.kubesolo.os.release_date           (optional, RFC3339)
+//
+// The agent ignores any additional layers, so the same image can also be
+// shaped as a "scratch" container if the build pipeline finds that convenient
+// for ecosystem tooling.
+package oci
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"runtime"
+
+	"github.com/opencontainers/go-digest"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras-go/v2/content"
+	"oras.land/oras-go/v2/registry/remote"
+
+	"github.com/portainer/kubesolo-os/update/pkg/image"
+)
+
+// Media types used on KubeSolo OS update artifacts. Kept here (not in
+// pkg/image) so the OCI protocol surface is fully self-contained.
+const (
+	MediaKernel    = "application/vnd.kubesolo.os.kernel.v1+octet-stream"
+	MediaInitramfs = "application/vnd.kubesolo.os.initramfs.v1+gzip"
+
+	AnnotVersion     = "io.kubesolo.os.version"
+	AnnotChannel     = "io.kubesolo.os.channel"
+	AnnotMinVersion  = "io.kubesolo.os.min_compatible_version"
+	AnnotArch        = "io.kubesolo.os.architecture"
+	AnnotReleaseNote = "io.kubesolo.os.release_notes"
+	AnnotReleaseDate = "io.kubesolo.os.release_date"
+)
+
+// Client pulls artifacts from a single OCI repository (e.g.
+// `ghcr.io/portainer/kubesolo-os`).
+//
+// Anonymous (public-pull) access is supported out of the box. For private
+// repositories, configure auth via the underlying remote.Repository.Client
+// before passing it to Resolve/Pull — that hook isn't surfaced here yet
+// (deferred until we actually need it for a private fleet).
+type Client struct {
+	repo *remote.Repository
+	// Arch is the architecture string we match against manifest indexes.
+	// Defaults to runtime.GOARCH; overridable for testing.
+	Arch string
+}
+
+// NewClient parses a repository reference of the form `host/path` (no tag)
+// and returns a ready-to-use Client.
+func NewClient(repoRef string) (*Client, error) {
+	repo, err := remote.NewRepository(repoRef)
+	if err != nil {
+		return nil, fmt.Errorf("invalid OCI reference %q: %w", repoRef, err)
+	}
+	// remote.NewRepository defaults to HTTPS. PlainHTTP is set per-test
+	// via the WithPlainHTTP option when we hit a httptest.Server.
+	return &Client{repo: repo, Arch: runtime.GOARCH}, nil
+}
+
+// WithPlainHTTP toggles the underlying registry transport to HTTP. Useful for
+// httptest-driven unit tests; do not use against production registries.
+func (c *Client) WithPlainHTTP(plain bool) *Client {
+	c.repo.PlainHTTP = plain
+	return c
+}
+
+// FetchMetadata resolves the tag, walks index → manifest if needed, and
+// returns an image.UpdateMetadata populated from the manifest's annotations.
+// No blobs are downloaded — this is the cheap "what's available" probe.
+func (c *Client) FetchMetadata(ctx context.Context, tag string) (*image.UpdateMetadata, error) {
+	manifest, _, err := c.resolveArchManifest(ctx, tag)
+	if err != nil {
+		return nil, err
+	}
+	return metadataFromAnnotations(manifest.Annotations), nil
+}
+
+// Pull resolves the tag, picks the matching-architecture manifest, downloads
+// the kernel + initramfs layers to `stageDir`, verifies their digests, and
+// returns a StagedImage compatible with the existing pkg/image consumer.
+func (c *Client) Pull(ctx context.Context, tag, stageDir string) (*image.StagedImage, *image.UpdateMetadata, error) {
+	manifest, _, err := c.resolveArchManifest(ctx, tag)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if err := os.MkdirAll(stageDir, 0o755); err != nil {
+		return nil, nil, fmt.Errorf("create stage dir: %w", err)
+	}
+
+	var kernelPath, initramfsPath string
+	for _, layer := range manifest.Layers {
+		switch layer.MediaType {
+		case MediaKernel:
+			kernelPath = filepath.Join(stageDir, "vmlinuz")
+			if err := c.fetchBlobTo(ctx, layer, kernelPath); err != nil {
+				return nil, nil, fmt.Errorf("download kernel: %w", err)
+			}
+		case MediaInitramfs:
+			initramfsPath = filepath.Join(stageDir, "kubesolo-os.gz")
+			if err := c.fetchBlobTo(ctx, layer, initramfsPath); err != nil {
+				return nil, nil, fmt.Errorf("download initramfs: %w", err)
+			}
+		default:
+			slog.Debug("oci: skipping unknown layer", "media", layer.MediaType)
+		}
+	}
+
+	if kernelPath == "" {
+		return nil, nil, fmt.Errorf("manifest has no %s layer", MediaKernel)
+	}
+	if initramfsPath == "" {
+		return nil, nil, fmt.Errorf("manifest has no %s layer", MediaInitramfs)
+	}
+
+	meta := metadataFromAnnotations(manifest.Annotations)
+	staged := &image.StagedImage{
+		VmlinuzPath:   kernelPath,
+		InitramfsPath: initramfsPath,
+		Version:       meta.Version,
+	}
+	return staged, meta, nil
+}
+
+// resolveArchManifest fetches the descriptor at `tag`, walks an index if
+// present, and returns the platform-specific manifest matching c.Arch.
+func (c *Client) resolveArchManifest(ctx context.Context, tag string) (*ocispec.Manifest, *ocispec.Descriptor, error) {
+	desc, err := c.repo.Resolve(ctx, tag)
+	if err != nil {
+		return nil, nil, fmt.Errorf("resolve tag %q: %w", tag, err)
+	}
+
+	switch desc.MediaType {
+	case ocispec.MediaTypeImageIndex, "application/vnd.docker.distribution.manifest.list.v2+json":
+		index, err := fetchJSON[ocispec.Index](ctx, c.repo, desc)
+		if err != nil {
+			return nil, nil, fmt.Errorf("fetch index: %w", err)
+		}
+		var matched *ocispec.Descriptor
+		for i := range index.Manifests {
+			m := &index.Manifests[i]
+			if m.Platform != nil && m.Platform.Architecture == c.Arch {
+				matched = m
+				break
+			}
+		}
+		if matched == nil {
+			return nil, nil, fmt.Errorf("no manifest in index for architecture %q", c.Arch)
+		}
+		manifest, err := fetchJSON[ocispec.Manifest](ctx, c.repo, *matched)
+		if err != nil {
+			return nil, nil, fmt.Errorf("fetch manifest: %w", err)
+		}
+		return manifest, matched, nil
+
+	case ocispec.MediaTypeImageManifest, "application/vnd.docker.distribution.manifest.v2+json":
+		manifest, err := fetchJSON[ocispec.Manifest](ctx, c.repo, desc)
+		if err != nil {
+			return nil, nil, fmt.Errorf("fetch manifest: %w", err)
+		}
+		// Single-arch tag: if it declares an arch, enforce match.
+		if archAnnot := manifest.Annotations[AnnotArch]; archAnnot != "" && archAnnot != c.Arch {
+			return nil, nil, fmt.Errorf("single-arch manifest is %q, want %q", archAnnot, c.Arch)
+		}
+		return manifest, &desc, nil
+
+	default:
+		return nil, nil, fmt.Errorf("unsupported media type %q at tag %q", desc.MediaType, tag)
+	}
+}
+
+// fetchJSON pulls a small JSON document (manifest or index) and decodes it.
+func fetchJSON[T any](ctx context.Context, store content.Fetcher, desc ocispec.Descriptor) (*T, error) {
+	rc, err := store.Fetch(ctx, desc)
+	if err != nil {
+		return nil, err
+	}
+	defer rc.Close()
+	data, err := content.ReadAll(rc, desc)
+	if err != nil {
+		return nil, err
+	}
+	var out T
+	if err := json.Unmarshal(data, &out); err != nil {
+		return nil, fmt.Errorf("decode: %w", err)
+	}
+	return &out, nil
+}
+
+// fetchBlobTo streams a blob to disk and verifies its digest matches.
+// Cleans up the destination file on any error so we never leave a partial.
+func (c *Client) fetchBlobTo(ctx context.Context, desc ocispec.Descriptor, dest string) (retErr error) {
+	rc, err := c.repo.Fetch(ctx, desc)
+	if err != nil {
+		return fmt.Errorf("fetch blob: %w", err)
+	}
+	defer rc.Close()
+
+	f, err := os.Create(dest)
+	if err != nil {
+		return fmt.Errorf("create %s: %w", dest, err)
+	}
+	defer func() {
+		if cerr := f.Close(); retErr == nil && cerr != nil {
+			retErr = cerr
+		}
+		if retErr != nil {
+			_ = os.Remove(dest)
+		}
+	}()
+
+	verifier := desc.Digest.Algorithm().Hash()
+	mw := io.MultiWriter(f, verifier)
+	n, err := io.Copy(mw, rc)
+	if err != nil {
+		return fmt.Errorf("stream blob: %w", err)
+	}
+	if desc.Size > 0 && n != desc.Size {
+		return fmt.Errorf("blob size mismatch: got %d, want %d", n, desc.Size)
+	}
+	got := digest.NewDigest(desc.Digest.Algorithm(), verifier)
+	if got != desc.Digest {
+		return fmt.Errorf("blob digest mismatch: got %s, want %s", got, desc.Digest)
+	}
+	return nil
+}
+
+// metadataFromAnnotations builds an UpdateMetadata from manifest annotations.
+// Always returns a non-nil value (missing fields stay empty).
+func metadataFromAnnotations(a map[string]string) *image.UpdateMetadata {
+	if a == nil {
+		a = map[string]string{}
+	}
+	return &image.UpdateMetadata{
+		Version:              a[AnnotVersion],
+		Channel:              a[AnnotChannel],
+		MinCompatibleVersion: a[AnnotMinVersion],
+		Architecture:         a[AnnotArch],
+		ReleaseNotes:         a[AnnotReleaseNote],
+		ReleaseDate:          a[AnnotReleaseDate],
+	}
+}
+
+// ErrNoManifestForArch is returned from FetchMetadata/Pull when an index has
+// no entry matching the running architecture. Exposed so callers can
+// distinguish "registry unreachable" from "this build doesn't ship for us".
+var ErrNoManifestForArch = errors.New("no manifest in index for runtime architecture")

update/pkg/oci/oci_test.go

@@ -0,0 +1,377 @@
+package oci
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/opencontainers/go-digest"
+	specs "github.com/opencontainers/image-spec/specs-go"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
+
+// fakeRegistry implements the minimum OCI distribution-spec surface our
+// Client touches: /v2/ probe, manifest fetch by tag or digest, blob fetch
+// by digest. Backed by an in-memory blob+manifest store.
+type fakeRegistry struct {
+	t          *testing.T
+	srv        *httptest.Server
+	blobs      map[digest.Digest][]byte // keyed by digest
+	manifests  map[string][]byte        // keyed by digest string (raw form)
+	tags       map[string]digest.Digest // tag -> manifest digest
+	mediaTypes map[digest.Digest]string // descriptor.MediaType per stored object
+}
+
+func newFakeRegistry(t *testing.T) *fakeRegistry {
+	t.Helper()
+	r := &fakeRegistry{
+		t:          t,
+		blobs:      map[digest.Digest][]byte{},
+		manifests:  map[string][]byte{},
+		tags:       map[string]digest.Digest{},
+		mediaTypes: map[digest.Digest]string{},
+	}
+	r.srv = httptest.NewServer(http.HandlerFunc(r.handle))
+	t.Cleanup(r.srv.Close)
+	return r
+}
+
+func (r *fakeRegistry) putBlob(media string, data []byte) digest.Digest {
+	h := sha256.Sum256(data)
+	d := digest.NewDigestFromBytes(digest.SHA256, h[:])
+	r.blobs[d] = data
+	r.mediaTypes[d] = media
+	return d
+}
+
+// putManifest stores a manifest/index document under both its digest and the
+// given tag, returning the digest the caller can embed in indexes.
+func (r *fakeRegistry) putManifest(tag string, media string, doc []byte) digest.Digest {
+	h := sha256.Sum256(doc)
+	d := digest.NewDigestFromBytes(digest.SHA256, h[:])
+	r.manifests[d.String()] = doc
+	r.mediaTypes[d] = media
+	if tag != "" {
+		r.tags[tag] = d
+	}
+	return d
+}
+
+// repoRef returns the "host:port/repo" string for use with NewClient.
+func (r *fakeRegistry) repoRef() string {
+	u, _ := url.Parse(r.srv.URL)
+	return u.Host + "/test/kubesolo-os"
+}
+
+func (r *fakeRegistry) handle(w http.ResponseWriter, req *http.Request) {
+	// Routes we implement:
+	//   GET /v2/                          -> 200 "{}"
+	//   GET /v2/test/kubesolo-os/manifests/<tag-or-digest> -> manifest
+	//   HEAD same                         -> same headers, no body
+	//   GET /v2/test/kubesolo-os/blobs/<digest> -> blob
+
+	path := req.URL.Path
+	if path == "/v2/" || path == "/v2" {
+		w.Header().Set("Docker-Distribution-API-Version", "registry/2.0")
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "{}")
+		return
+	}
+
+	const prefix = "/v2/test/kubesolo-os/"
+	if !strings.HasPrefix(path, prefix) {
+		http.NotFound(w, req)
+		return
+	}
+	rest := strings.TrimPrefix(path, prefix)
+
+	switch {
+	case strings.HasPrefix(rest, "manifests/"):
+		ref := strings.TrimPrefix(rest, "manifests/")
+		var d digest.Digest
+		var data []byte
+		if td, ok := r.tags[ref]; ok {
+			d = td
+			data = r.manifests[d.String()]
+		} else if md, ok := r.manifests[ref]; ok {
+			d = digest.Digest(ref)
+			data = md
+		} else {
+			http.NotFound(w, req)
+			return
+		}
+		media := r.mediaTypes[d]
+		w.Header().Set("Content-Type", media)
+		w.Header().Set("Docker-Content-Digest", d.String())
+		w.Header().Set("Content-Length", fmt.Sprintf("%d", len(data)))
+		if req.Method == http.MethodHead {
+			return
+		}
+		_, _ = w.Write(data)
+
+	case strings.HasPrefix(rest, "blobs/"):
+		ref := strings.TrimPrefix(rest, "blobs/")
+		d := digest.Digest(ref)
+		blob, ok := r.blobs[d]
+		if !ok {
+			http.NotFound(w, req)
+			return
+		}
+		media := r.mediaTypes[d]
+		if media == "" {
+			media = "application/octet-stream"
+		}
+		w.Header().Set("Content-Type", media)
+		w.Header().Set("Docker-Content-Digest", d.String())
+		w.Header().Set("Content-Length", fmt.Sprintf("%d", len(blob)))
+		if req.Method == http.MethodHead {
+			return
+		}
+		_, _ = w.Write(blob)
+
+	default:
+		http.NotFound(w, req)
+	}
+}
+
+// seedSingleArchManifest puts kernel+initramfs blobs and a manifest with the
+// given annotations into the registry, tagged as `tag`.
+func (r *fakeRegistry) seedSingleArchManifest(t *testing.T, tag string, annot map[string]string) (kernelData, initramfsData []byte) {
+	t.Helper()
+	kernelData = []byte("FAKE-KERNEL-" + tag)
+	initramfsData = []byte("FAKE-INITRAMFS-" + tag)
+
+	kd := r.putBlob(MediaKernel, kernelData)
+	id := r.putBlob(MediaInitramfs, initramfsData)
+
+	// An empty config blob with sha256 of "{}" (the canonical "empty" body
+	// per OCI). We don't actually fetch the config so any valid descriptor
+	// works for the tests, but the digest still has to be syntactically valid.
+	emptyConfigBody := []byte("{}")
+	emptyConfigDigest := r.putBlob("application/vnd.oci.empty.v1+json", emptyConfigBody)
+
+	manifest := ocispec.Manifest{
+		Versioned: specs.Versioned{SchemaVersion: 2},
+		MediaType: ocispec.MediaTypeImageManifest,
+		Config: ocispec.Descriptor{
+			MediaType: "application/vnd.oci.empty.v1+json",
+			Size:      int64(len(emptyConfigBody)),
+			Digest:    emptyConfigDigest,
+		},
+		Layers: []ocispec.Descriptor{
+			{MediaType: MediaKernel, Digest: kd, Size: int64(len(kernelData))},
+			{MediaType: MediaInitramfs, Digest: id, Size: int64(len(initramfsData))},
+		},
+		Annotations: annot,
+	}
+	manifestBytes, err := json.Marshal(manifest)
+	if err != nil {
+		t.Fatalf("marshal manifest: %v", err)
+	}
+	r.putManifest(tag, ocispec.MediaTypeImageManifest, manifestBytes)
+	return
+}
+
+// seedIndex creates a manifest index pointing at per-arch manifests created
+// via seedSingleArchManifest with arch-suffixed tags, then publishes the
+// index under `tag`.
+func (r *fakeRegistry) seedIndex(t *testing.T, tag string, perArchAnnots map[string]map[string]string) {
+	t.Helper()
+	var descriptors []ocispec.Descriptor
+	for arch, annot := range perArchAnnots {
+		// Reuse seedSingleArchManifest but under an internal arch-suffixed tag
+		archTag := tag + "-" + arch
+		r.seedSingleArchManifest(t, archTag, annot)
+		d := r.tags[archTag]
+		descriptors = append(descriptors, ocispec.Descriptor{
+			MediaType: ocispec.MediaTypeImageManifest,
+			Digest:    d,
+			Size:      int64(len(r.manifests[d.String()])),
+			Platform:  &ocispec.Platform{Architecture: arch, OS: "linux"},
+		})
+	}
+	index := ocispec.Index{
+		Versioned: specs.Versioned{SchemaVersion: 2},
+		MediaType: ocispec.MediaTypeImageIndex,
+		Manifests: descriptors,
+	}
+	indexBytes, _ := json.Marshal(index)
+	r.putManifest(tag, ocispec.MediaTypeImageIndex, indexBytes)
+}
+
+// ---------------------------------------------------------------------------
+
+func TestFetchMetadataSingleArchManifest(t *testing.T) {
+	reg := newFakeRegistry(t)
+	reg.seedSingleArchManifest(t, "v0.3.0", map[string]string{
+		AnnotVersion: "v0.3.0",
+		AnnotChannel: "stable",
+		AnnotArch:    "amd64",
+	})
+
+	c, err := NewClient(reg.repoRef())
+	if err != nil {
+		t.Fatalf("NewClient: %v", err)
+	}
+	c.WithPlainHTTP(true)
+	c.Arch = "amd64"
+
+	meta, err := c.FetchMetadata(context.Background(), "v0.3.0")
+	if err != nil {
+		t.Fatalf("FetchMetadata: %v", err)
+	}
+	if meta.Version != "v0.3.0" {
+		t.Errorf("version: got %q, want v0.3.0", meta.Version)
+	}
+	if meta.Channel != "stable" {
+		t.Errorf("channel: got %q", meta.Channel)
+	}
+}
+
+func TestFetchMetadataIndexSelectsArch(t *testing.T) {
+	reg := newFakeRegistry(t)
+	reg.seedIndex(t, "stable", map[string]map[string]string{
+		"amd64": {AnnotVersion: "v0.3.0", AnnotChannel: "stable", AnnotArch: "amd64"},
+		"arm64": {AnnotVersion: "v0.3.0", AnnotChannel: "stable", AnnotArch: "arm64"},
+	})
+
+	for _, arch := range []string{"amd64", "arm64"} {
+		t.Run(arch, func(t *testing.T) {
+			c, err := NewClient(reg.repoRef())
+			if err != nil {
+				t.Fatalf("NewClient: %v", err)
+			}
+			c.WithPlainHTTP(true)
+			c.Arch = arch
+
+			meta, err := c.FetchMetadata(context.Background(), "stable")
+			if err != nil {
+				t.Fatalf("FetchMetadata: %v", err)
+			}
+			if meta.Architecture != arch {
+				t.Errorf("arch annotation: got %q, want %q", meta.Architecture, arch)
+			}
+			if meta.Version != "v0.3.0" {
+				t.Errorf("version: got %q, want v0.3.0", meta.Version)
+			}
+		})
+	}
+}
+
+func TestFetchMetadataIndexMissingArchErrors(t *testing.T) {
+	reg := newFakeRegistry(t)
+	reg.seedIndex(t, "stable", map[string]map[string]string{
+		"amd64": {AnnotVersion: "v0.3.0", AnnotArch: "amd64"},
+	})
+
+	c, _ := NewClient(reg.repoRef())
+	c.WithPlainHTTP(true)
+	c.Arch = "arm64" // not in the index
+
+	_, err := c.FetchMetadata(context.Background(), "stable")
+	if err == nil {
+		t.Fatal("expected error for missing arch, got nil")
+	}
+	if !strings.Contains(err.Error(), "arm64") {
+		t.Errorf("expected error mentioning arm64, got: %v", err)
+	}
+}
+
+func TestFetchMetadataSingleArchManifestRejectsCrossArch(t *testing.T) {
+	// If the manifest declares an arch via annotation and it doesn't match
+	// our runtime, Pull should refuse — defense in depth on top of the
+	// channel/version gates in cmd/apply.go.
+	reg := newFakeRegistry(t)
+	reg.seedSingleArchManifest(t, "v0.3.0-arm64", map[string]string{
+		AnnotArch: "arm64",
+	})
+
+	c, _ := NewClient(reg.repoRef())
+	c.WithPlainHTTP(true)
+	c.Arch = "amd64"
+
+	_, err := c.FetchMetadata(context.Background(), "v0.3.0-arm64")
+	if err == nil {
+		t.Fatal("expected error pulling cross-arch single-arch manifest, got nil")
+	}
+}
+
+func TestPullDownloadsBlobsAndVerifiesDigest(t *testing.T) {
+	reg := newFakeRegistry(t)
+	kernelData, initramfsData := reg.seedSingleArchManifest(t, "v0.3.0",
+		map[string]string{AnnotVersion: "v0.3.0", AnnotArch: "amd64"})
+
+	c, _ := NewClient(reg.repoRef())
+	c.WithPlainHTTP(true)
+	c.Arch = "amd64"
+
+	stageDir := filepath.Join(t.TempDir(), "stage")
+	staged, meta, err := c.Pull(context.Background(), "v0.3.0", stageDir)
+	if err != nil {
+		t.Fatalf("Pull: %v", err)
+	}
+	if meta.Version != "v0.3.0" {
+		t.Errorf("meta version: got %q", meta.Version)
+	}
+	if staged.Version != "v0.3.0" {
+		t.Errorf("staged version: got %q", staged.Version)
+	}
+
+	gotKernel, err := os.ReadFile(staged.VmlinuzPath)
+	if err != nil {
+		t.Fatalf("read kernel: %v", err)
+	}
+	if string(gotKernel) != string(kernelData) {
+		t.Errorf("kernel mismatch:\n got %q\nwant %q", gotKernel, kernelData)
+	}
+	gotInit, err := os.ReadFile(staged.InitramfsPath)
+	if err != nil {
+		t.Fatalf("read initramfs: %v", err)
+	}
+	if string(gotInit) != string(initramfsData) {
+		t.Errorf("initramfs mismatch")
+	}
+}
+
+func TestPullRejectsTamperedBlob(t *testing.T) {
+	// Mutate the kernel blob after it's been digested into the manifest.
+	// Pull should refuse with a digest mismatch.
+	reg := newFakeRegistry(t)
+	_, _ = reg.seedSingleArchManifest(t, "v0.3.0",
+		map[string]string{AnnotVersion: "v0.3.0", AnnotArch: "amd64"})
+
+	// Corrupt every stored kernel blob in the registry by replacing its body.
+	for d, m := range reg.mediaTypes {
+		if m == MediaKernel {
+			reg.blobs[d] = []byte("TAMPERED-KERNEL-WRONG-LENGTH-AND-DIGEST")
+		}
+	}
+
+	c, _ := NewClient(reg.repoRef())
+	c.WithPlainHTTP(true)
+	c.Arch = "amd64"
+
+	_, _, err := c.Pull(context.Background(), "v0.3.0", filepath.Join(t.TempDir(), "stage"))
+	if err == nil {
+		t.Fatal("expected digest mismatch error on tampered blob, got nil")
+	}
+	if !strings.Contains(err.Error(), "mismatch") {
+		t.Errorf("expected mismatch in error, got: %v", err)
+	}
+}
+
+func TestNewClientRejectsGarbageReference(t *testing.T) {
+	_, err := NewClient("not a valid reference")
+	if err == nil {
+		t.Error("expected error on bad reference, got nil")
+	}
+}