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>

build/Dockerfile.builder

@@ -55,6 +55,13 @@ RUN curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" \
     | tar -C /usr/local -xzf -
 ENV PATH="/usr/local/go/bin:${PATH}"
 
+# Install oras (OCI artifact CLI) for push-oci-artifact.sh.
+# Bump ORAS_VERSION when pushing breaks or when oras gains useful flags.
+ARG ORAS_VERSION=1.2.3
+RUN curl -fsSL "https://github.com/oras-project/oras/releases/download/v${ORAS_VERSION}/oras_${ORAS_VERSION}_linux_amd64.tar.gz" \
+    | tar -C /usr/local/bin -xzf - oras \
+    && chmod +x /usr/local/bin/oras
+
 WORKDIR /build
 COPY . /build
 

build/scripts/push-oci-artifact.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# push-oci-artifact.sh — Publish a KubeSolo OS update artifact to an OCI registry.
+#
+# Produces the artifact format consumed by `kubesolo-update --registry`:
+#
+#   <registry>/<repo>:<version>-<arch>     per-arch manifest, layers:
+#     * vmlinuz (Image on arm64)  → application/vnd.kubesolo.os.kernel.v1+octet-stream
+#     * kubesolo-os.gz            → application/vnd.kubesolo.os.initramfs.v1+gzip
+#     annotations:
+#       io.kubesolo.os.version
+#       io.kubesolo.os.channel
+#       io.kubesolo.os.architecture
+#       io.kubesolo.os.min_compatible_version (optional)
+#
+# After running this for each architecture, combine the per-arch tags into a
+# multi-arch index with `oras manifest index create` (see end of script).
+#
+# Requires: oras (>= 1.2), curl, jq.
+#
+# Usage:
+#   build/scripts/push-oci-artifact.sh \
+#       --registry ghcr.io/portainer/kubesolo-os \
+#       --arch amd64 \
+#       --channel stable \
+#       [--min-compatible-version v0.2.0]
+#
+# Authentication: oras reads ~/.docker/config.json. In CI, run
+#   `oras login ghcr.io -u USER -p TOKEN` before invoking this script
+# (or set DOCKER_CONFIG to a directory with config.json).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+VERSION="$(cat "$PROJECT_ROOT/VERSION")"
+OUTPUT_DIR="$PROJECT_ROOT/output"
+CACHE_DIR="$PROJECT_ROOT/build/cache"
+
+REGISTRY=""
+ARCH=""
+CHANNEL="stable"
+MIN_COMPATIBLE_VERSION=""
+RELEASE_NOTES=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --registry) REGISTRY="$2"; shift 2 ;;
+        --arch) ARCH="$2"; shift 2 ;;
+        --channel) CHANNEL="$2"; shift 2 ;;
+        --min-compatible-version) MIN_COMPATIBLE_VERSION="$2"; shift 2 ;;
+        --release-notes) RELEASE_NOTES="$2"; shift 2 ;;
+        *) echo "Unknown option: $1" >&2; exit 1 ;;
+    esac
+done
+
+if [ -z "$REGISTRY" ] || [ -z "$ARCH" ]; then
+    echo "Usage: $0 --registry REGISTRY/REPO --arch (amd64|arm64) [--channel stable] [--min-compatible-version vX.Y.Z]" >&2
+    exit 1
+fi
+
+if ! command -v oras >/dev/null 2>&1; then
+    echo "ERROR: oras CLI not found. Install from https://oras.land/docs/installation/" >&2
+    echo "  or apt-get install oras (Ubuntu 24.04+)" >&2
+    exit 1
+fi
+
+# Locate the artifacts. For arm64 the kernel is "Image"; everywhere else it's
+# "vmlinuz". Initramfs is always kubesolo-os.gz.
+case "$ARCH" in
+    amd64)
+        KERNEL="$CACHE_DIR/custom-kernel/vmlinuz"
+        [ -f "$KERNEL" ] || KERNEL="$OUTPUT_DIR/vmlinuz"
+        KERNEL_BASENAME="vmlinuz"
+        ;;
+    arm64)
+        KERNEL="$CACHE_DIR/kernel-arm64-generic/Image"
+        KERNEL_BASENAME="vmlinuz"  # we publish under the vmlinuz name regardless;
+                                   # the consumer looks up by media type, not filename.
+        ;;
+    *)
+        echo "ERROR: unsupported --arch $ARCH (use amd64 or arm64)" >&2
+        exit 1
+        ;;
+esac
+
+INITRAMFS="$PROJECT_ROOT/build/rootfs-work/kubesolo-os.gz"
+
+if [ ! -f "$KERNEL" ]; then
+    echo "ERROR: kernel not found at $KERNEL" >&2
+    echo "  Run 'make kernel' (amd64) or 'make kernel-arm64' (arm64) first." >&2
+    exit 1
+fi
+if [ ! -f "$INITRAMFS" ]; then
+    echo "ERROR: initramfs not found at $INITRAMFS" >&2
+    echo "  Run 'make initramfs' or 'make rootfs-arm64' first." >&2
+    exit 1
+fi
+
+# Stage files in a temp dir so the basenames in the manifest are clean.
+STAGE="$(mktemp -d)"
+trap 'rm -rf "$STAGE"' EXIT
+cp "$KERNEL" "$STAGE/$KERNEL_BASENAME"
+cp "$INITRAMFS" "$STAGE/kubesolo-os.gz"
+
+KERNEL_MEDIA="application/vnd.kubesolo.os.kernel.v1+octet-stream"
+INITRD_MEDIA="application/vnd.kubesolo.os.initramfs.v1+gzip"
+
+REF="${REGISTRY}:${VERSION}-${ARCH}"
+CHANNEL_REF="${REGISTRY}:${CHANNEL}-${ARCH}"
+
+echo "==> Pushing ${REF}"
+echo "    kernel:     $KERNEL ($(du -h "$KERNEL" | cut -f1))"
+echo "    initramfs:  $INITRAMFS ($(du -h "$INITRAMFS" | cut -f1))"
+
+ORAS_ANNOTATIONS=(
+    --annotation "io.kubesolo.os.version=${VERSION}"
+    --annotation "io.kubesolo.os.channel=${CHANNEL}"
+    --annotation "io.kubesolo.os.architecture=${ARCH}"
+)
+if [ -n "$MIN_COMPATIBLE_VERSION" ]; then
+    ORAS_ANNOTATIONS+=(--annotation "io.kubesolo.os.min_compatible_version=${MIN_COMPATIBLE_VERSION}")
+fi
+if [ -n "$RELEASE_NOTES" ]; then
+    ORAS_ANNOTATIONS+=(--annotation "io.kubesolo.os.release_notes=${RELEASE_NOTES}")
+fi
+ORAS_ANNOTATIONS+=(--annotation "io.kubesolo.os.release_date=$(date -u +%Y-%m-%dT%H:%M:%SZ)")
+
+# oras push: --artifact-type sets the manifest artifactType field;
+# file:type syntax sets per-layer media types.
+(cd "$STAGE" && oras push "$REF" \
+    --artifact-type "application/vnd.kubesolo.os.update.v1+json" \
+    "${ORAS_ANNOTATIONS[@]}" \
+    "${KERNEL_BASENAME}:${KERNEL_MEDIA}" \
+    "kubesolo-os.gz:${INITRD_MEDIA}")
+
+# Also tag as <channel>-<arch> so the manifest-index step can reference it
+# stably across patch releases.
+echo "==> Tagging ${CHANNEL_REF}"
+oras tag "$REF" "${CHANNEL}-${ARCH}"
+
+echo ""
+echo "==> Published:"
+echo "    ${REF}"
+echo "    ${CHANNEL_REF}"
+echo ""
+echo "To combine multi-arch into the channel index, run after both arches are pushed:"
+echo ""
+echo "  oras manifest index create ${REGISTRY}:${CHANNEL} \\"
+echo "      ${REGISTRY}:${CHANNEL}-amd64,platform=linux/amd64 \\"
+echo "      ${REGISTRY}:${CHANNEL}-arm64,platform=linux/arm64"
+echo ""