fix: HEAD requests fetch and stream the full body (#89)

Fixes #70

## Why
Docker `HEAD` routes mapped to `handleProxy`, which ran a full `Fetch` + `io.Copy` — downloading the entire blob (and fetching upstream on a miss) only for net/http to discard the body. HEAD existence checks (manifests, blobs) are common.

## Changes
- Add `Engine.Head`: answers cached artifacts/indexes from store metadata (no blob download); on a miss issues an upstream `HEAD` (with bearer-token handling) and never caches a body.
- Route `HEAD /v2/{remote}/*` to a dedicated `handleProxyHead` that writes headers only.
- Add e2e tests for HEAD on a blocklisted path (403) and an unknown remote (404).

## Note
`headUpstream` uses `http.DefaultClient` to build cleanly on master; it will pick up the shared timeout-configured client from #67 once that merges.

## Validation
- `make e2e` passes (includes new HEAD tests).

Reviewed-on: #89
Co-authored-by: Ben Vincent <ben@unkin.net>
Co-committed-by: Ben Vincent <ben@unkin.net>

internal/api/v1/proxy.go

@@ -42,7 +42,7 @@ func (h *ProxyHandler) DockerV2Routes() chi.Router {
 	r.Get("/", h.handleDockerPing)
 	r.Head("/", h.handleDockerPing)
 	r.Get("/{remoteName}/*", h.handleProxy)
-	r.Head("/{remoteName}/*", h.handleProxy)
+	r.Head("/{remoteName}/*", h.handleProxyHead)
 	return r
 }
 
@@ -89,6 +89,42 @@ func (h *ProxyHandler) handleProxy(w http.ResponseWriter, r *http.Request) {
 	io.Copy(w, result.Reader)
 }
 
+func (h *ProxyHandler) handleProxyHead(w http.ResponseWriter, r *http.Request) {
+	remoteName := chi.URLParam(r, "remoteName")
+	path := chi.URLParam(r, "*")
+
+	remote, err := h.db.GetRemote(r.Context(), remoteName)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("remote %q not found", remoteName), http.StatusNotFound)
+		return
+	}
+
+	prov, err := provider.Get(remote.PackageType)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("no provider for %q", remote.PackageType), http.StatusInternalServerError)
+		return
+	}
+
+	result, err := h.engine.Head(r.Context(), *remote, path, prov)
+	if err != nil {
+		var proxyErr *proxy.ProxyError
+		if errors.As(err, &proxyErr) {
+			http.Error(w, proxyErr.Message, proxyErr.Status)
+			return
+		}
+		slog.Error("proxy head failed", "remote", remoteName, "path", path, "error", err)
+		http.Error(w, "bad gateway", http.StatusBadGateway)
+		return
+	}
+
+	w.Header().Set("Content-Type", result.ContentType)
+	w.Header().Set("X-Artifact-Source", result.Source)
+	if result.Size > 0 {
+		w.Header().Set("Content-Length", fmt.Sprintf("%d", result.Size))
+	}
+	w.WriteHeader(http.StatusOK)
+}
+
 func (h *ProxyHandler) handleVirtual(w http.ResponseWriter, r *http.Request) {
 	virtualName := chi.URLParam(r, "virtualName")
 	path := chi.URLParam(r, "*")