volumes: reserve hypeman.system/ tag namespace from API callers

The cache volume reaper selected eviction candidates by the
hypeman.system/managed-by=build-cache tag, but CreateVolume and
CreateVolumeFromArchive accepted arbitrary caller tags. A caller could
tag a user volume as managed and have it evicted by the reaper, or
inflate the managed set to force eviction of real cache volumes.

Reject caller-supplied tags in the hypeman.system/ namespace on both
public create paths, and require the reserved build-cache- ID prefix in
addition to the tag when the manager and reaper identify cache volumes.

Author: rgarcia

cmd/api/api/volumes.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"sort"
 
 	"github.com/kernel/hypeman/lib/logger"
 	mw "github.com/kernel/hypeman/lib/middleware"
@@ -56,6 +57,13 @@ func (s *ApiService) CreateVolume(ctx context.Context, request oapi.CreateVolume
 		}
 	}
 
+	if key := reservedTagKey(request.Body.Tags); key != "" {
+		return oapi.CreateVolume400JSONResponse{
+			Code:    "invalid_request",
+			Message: fmt.Sprintf("tag key %q is reserved for internal use", key),
+		}, nil
+	}
+
 	domainReq := volumes.CreateVolumeRequest{
 		Name:   request.Body.Name,
 		SizeGb: request.Body.SizeGb,
@@ -116,6 +124,13 @@ func (s *ApiService) CreateVolumeFromArchive(ctx context.Context, request oapi.C
 		}
 	}
 
+	if key := reservedTagKey(request.Params.Tags); key != "" {
+		return oapi.CreateVolumeFromArchive400JSONResponse{
+			Code:    "invalid_request",
+			Message: fmt.Sprintf("tag key %q is reserved for internal use", key),
+		}, nil
+	}
+
 	// Create the volume from archive - stream directly without buffering
 	domainReq := volumes.CreateVolumeFromArchiveRequest{
 		Name:   request.Params.Name,
@@ -230,3 +245,22 @@ func volumeToOAPI(vol volumes.Volume) oapi.Volume {
 
 	return oapiVol
 }
+
+// reservedTagKey returns the first caller-supplied tag key in the reserved
+// internal namespace, or "" when all keys are usable by API callers.
+func reservedTagKey(resourceTags *oapi.Tags) string {
+	if resourceTags == nil {
+		return ""
+	}
+	keys := make([]string, 0, len(*resourceTags))
+	for key := range *resourceTags {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		if volumes.ReservedTagNamespace(key) != "" {
+			return key
+		}
+	}
+	return ""
+}

cmd/api/api/volumes_test.go

@@ -79,6 +79,46 @@ func TestDeleteVolume_ByName(t *testing.T) {
 	assert.True(t, ok, "expected 204 response")
 }
 
+func TestCreateVolume_ReservedTagNamespace(t *testing.T) {
+	t.Parallel()
+	svc := newTestService(t)
+
+	resourceTags := oapi.Tags{"hypeman.system/managed-by": "build-cache"}
+	resp, err := svc.CreateVolume(ctx(), oapi.CreateVolumeRequestObject{
+		Body: &oapi.CreateVolumeRequest{
+			Name:   "spoofed-cache",
+			SizeGb: 1,
+			Tags:   &resourceTags,
+		},
+	})
+	require.NoError(t, err)
+	bad, ok := resp.(oapi.CreateVolume400JSONResponse)
+	require.True(t, ok, "expected 400 for reserved tag key")
+	assert.Contains(t, bad.Message, "reserved for internal use")
+
+	vols, err := svc.VolumeManager.ListVolumes(ctx())
+	require.NoError(t, err)
+	assert.Empty(t, vols, "spoofed volume should not be created")
+}
+
+func TestCreateVolumeFromArchive_ReservedTagNamespace(t *testing.T) {
+	t.Parallel()
+	svc := newTestService(t)
+
+	resourceTags := oapi.Tags{"hypeman.system/managed-by": "build-cache"}
+	resp, err := svc.CreateVolumeFromArchive(ctx(), oapi.CreateVolumeFromArchiveRequestObject{
+		Params: oapi.CreateVolumeFromArchiveParams{
+			Name:   "spoofed-cache",
+			SizeGb: 1,
+			Tags:   &resourceTags,
+		},
+	})
+	require.NoError(t, err)
+	bad, ok := resp.(oapi.CreateVolumeFromArchive400JSONResponse)
+	require.True(t, ok, "expected 400 for reserved tag key")
+	assert.Contains(t, bad.Message, "reserved for internal use")
+}
+
 func TestCreateVolume_ReservedIDPrefix(t *testing.T) {
 	t.Parallel()
 	svc := newTestService(t)

lib/builds/cache_volume.go

@@ -11,6 +11,7 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
+	"strings"
 	"sync"
 	"time"
 
@@ -56,8 +57,9 @@ const (
 	// created by the build cache manager. The tag distinguishes cache
 	// volumes from caller-created volumes that happen to share the ID
 	// prefix: the manager only reuses tagged volumes and the reaper only
-	// evicts tagged volumes.
-	cacheVolumeManagedTagKey   = "hypeman.system/managed-by"
+	// evicts tagged volumes. The key lives in a namespace public volume
+	// APIs reserve, so callers cannot spoof it.
+	cacheVolumeManagedTagKey   = volumes.SystemTagNamespace + "managed-by"
 	cacheVolumeManagedTagValue = "build-cache"
 
 	// cacheVolumeSweepInterval is how often the reaper evaluates eviction.
@@ -175,10 +177,14 @@ func (c *cacheVolumeManager) ensureCacheVolume(ctx context.Context, scope string
 	return volID, nil
 }
 
-// isManagedCacheVolume reports whether a volume carries the internal tag
-// marking it as created by the build cache manager.
+// isManagedCacheVolume reports whether a volume is a build cache volume:
+// it carries the internal managed-by tag and the reserved cache volume ID
+// prefix. The prefix check is defense in depth — public APIs already reject
+// both — so a volume created outside the public API cannot be mistaken for
+// a cache volume by tag alone.
 func isManagedCacheVolume(vol *volumes.Volume) bool {
-	return vol.Tags[cacheVolumeManagedTagKey] == cacheVolumeManagedTagValue
+	return strings.HasPrefix(vol.Id, cacheVolumeIDPrefix) &&
+		vol.Tags[cacheVolumeManagedTagKey] == cacheVolumeManagedTagValue
 }
 
 // touchLastUsed records that a cache volume was used now.

lib/builds/cache_volume_test.go

@@ -150,6 +150,32 @@ func TestReap_IgnoresUnmanagedPrefixedVolume(t *testing.T) {
 	assert.NoError(t, err, "unmanaged volume must never be evicted")
 }
 
+func TestReap_IgnoresTaggedVolumeWithoutPrefix(t *testing.T) {
+	mgr, volumeMgr, now, tempDir := setupCacheVolumeManager(t, CacheVolumeConfig{
+		Enabled: true,
+		SizeGB:  10,
+		IdleTTL: time.Hour,
+	})
+	defer os.RemoveAll(tempDir)
+
+	// A volume carrying the managed-by tag but an arbitrary ID — e.g. one
+	// created before the tag namespace was reserved, or outside the public
+	// API — must survive the reaper even when idle past the TTL.
+	userVol := &volumes.Volume{
+		Id:        "user-tagged-volume",
+		Name:      "user-data",
+		SizeGb:    10,
+		CreatedAt: now.Add(-72 * time.Hour),
+		Tags:      tags.Tags{cacheVolumeManagedTagKey: cacheVolumeManagedTagValue},
+	}
+	volumeMgr.volumes[userVol.Id] = userVol
+
+	mgr.reap(context.Background())
+
+	_, err := volumeMgr.GetVolume(context.Background(), userVol.Id)
+	assert.NoError(t, err, "tagged volume without the reserved ID prefix must never be evicted")
+}
+
 func TestLockScope_SerializesSameScope(t *testing.T) {
 	mgr, _, _, tempDir := setupCacheVolumeManager(t, CacheVolumeConfig{Enabled: true})
 	defer os.RemoveAll(tempDir)

lib/volumes/reserved.go

@@ -25,3 +25,18 @@ func ReservedVolumeIDPrefix(id string) string {
 	}
 	return ""
 }
+
+// SystemTagNamespace is the tag key namespace reserved for internal,
+// server-managed metadata (e.g. the tag marking build cache volumes).
+const SystemTagNamespace = "hypeman.system/"
+
+// ReservedTagNamespace returns the reserved internal tag namespace key
+// starts with, or "" when key is usable by API callers. Public APIs must
+// reject caller-supplied tags in this namespace so a caller cannot
+// impersonate an internally managed volume.
+func ReservedTagNamespace(key string) string {
+	if strings.HasPrefix(key, SystemTagNamespace) {
+		return SystemTagNamespace
+	}
+	return ""
+}

lib/volumes/reserved_test.go

@@ -14,3 +14,11 @@ func TestReservedVolumeIDPrefix(t *testing.T) {
 	assert.Empty(t, ReservedVolumeIDPrefix("my-data"))
 	assert.Empty(t, ReservedVolumeIDPrefix("build-caches"))
 }
+
+func TestReservedTagNamespace(t *testing.T) {
+	assert.Equal(t, SystemTagNamespace, ReservedTagNamespace("hypeman.system/managed-by"))
+	assert.Equal(t, SystemTagNamespace, ReservedTagNamespace("hypeman.system/anything"))
+	assert.Empty(t, ReservedTagNamespace("managed-by"))
+	assert.Empty(t, ReservedTagNamespace("hypeman.system"))
+	assert.Empty(t, ReservedTagNamespace("team"))
+}