feat: introduce system buckets (part one)

* initial support for system buckets, starting with ".sys-inventory"
* add QparamSystem to explicitly ask to "include system"
* bucket naming: disallow leading '.' (is now reserved)
* list-buckets: hide system buckets by default
* enforce admin access for system buckets (when Auth is enabled - no-op otherwise)
-----------
* TODO:
  - review/find all possible execution paths that are not yet covered
    (and require admin access if found)
  - CLI, tests, docs - the works

Signed-off-by: Alex Aizman <alex.aizman@gmail.com>

Author: alex-aizman

ais/dpq.go

@@ -82,6 +82,7 @@ type (
 		silent        bool // QparamSilent
 		latestVer     bool // QparamLatestVer
 		sync          bool // QparamSync
+		system        bool // QparamSystem (allow system buckets)
 
 		// Special use (internal context)
 		isS3 bool // frontend S3 API
@@ -185,6 +186,8 @@ func (dpq *dpq) parse(rawQuery string) error {
 			dpq.latestVer = cos.IsParseBool(value)
 		case apc.QparamSync:
 			dpq.sync = cos.IsParseBool(value)
+		case apc.QparamSystem:
+			dpq.system = cos.IsParseBool(value)
 
 		case apc.QparamColoc:
 			var coloc uint64

ais/proxy.go

@@ -663,7 +663,12 @@ func (p *proxy) httpbckget(w http.ResponseWriter, r *http.Request, dpq *dpq) {
 		if qbck.IsRemoteAIS() {
 			qbck.Ns.UUID = p.a2u(qbck.Ns.UUID)
 		}
-		if err := p.checkAccess(w, r, nil, apc.AceListBuckets); err == nil {
+
+		ace := apc.AceListBuckets
+		if dpq.system {
+			ace |= apc.AceAdmin
+		}
+		if err := p.checkAccess(w, r, nil, ace); err == nil {
 			p.listBuckets(w, r, qbck, msg, dpq)
 		}
 		return
@@ -2257,7 +2262,7 @@ func (p *proxy) listBuckets(w http.ResponseWriter, r *http.Request, qbck *cmn.Qu
 		present bool
 	)
 	if qbck.IsAIS() || qbck.IsHT() {
-		bcks := bmd.Select(qbck)
+		bcks := bmd.Select(qbck, dpq.system)
 		p.writeJSON(w, r, bcks, "list-buckets")
 		return
 	}
@@ -2269,7 +2274,7 @@ func (p *proxy) listBuckets(w http.ResponseWriter, r *http.Request, qbck *cmn.Qu
 		}
 	}
 	if present {
-		bcks := bmd.Select(qbck)
+		bcks := bmd.Select(qbck, dpq.system)
 		p.writeJSON(w, r, bcks, "list-buckets")
 		return
 	}

ais/prxauth.go

@@ -413,6 +413,13 @@ func (p *proxy) access(ctx context.Context, hdr http.Header, bck *meta.Bck, ace
 		return err
 	}
 
+	// System buckets: require admin
+	// - note that majority of control flows that operate on bucket(s) validate perm-s via bckArgs.initAndTry() => p.access()
+	// - the rest that pass `bck == nil` MUST explicitly add apc.AceAdmin
+	if bck != nil && bck.Bucket().IsSystem() {
+		ace |= apc.AceAdmin
+	}
+
 	// Validate token and parse claims ONCE
 	claims, err := p.validateToken(ctx, hdr)
 	if err != nil {

ais/tgtbck.go

@@ -70,7 +70,7 @@ func (t *target) httpbckget(w http.ResponseWriter, r *http.Request, dpq *dpq) {
 		// (see api.ListBuckets and the line below)
 		if !qbck.IsBucket() {
 			qbck.Name = msg.Name
-			t.listBuckets(w, r, qbck)
+			t.listBuckets(w, r, qbck, dpq)
 			return
 		}
 		bck := meta.CloneBck((*cmn.Bck)(qbck))
@@ -169,7 +169,7 @@ func (t *target) httpbckget(w http.ResponseWriter, r *http.Request, dpq *dpq) {
 // there's a difference between looking for all (any) provider vs a specific one -
 // in the former case the fact that (the corresponding backend is not configured)
 // is not an error
-func (t *target) listBuckets(w http.ResponseWriter, r *http.Request, qbck *cmn.QueryBcks) {
+func (t *target) listBuckets(w http.ResponseWriter, r *http.Request, qbck *cmn.QueryBcks, dpq *dpq) {
 	var (
 		bcks   cmn.Bcks
 		config = cmn.GCO.Get()
@@ -179,7 +179,7 @@ func (t *target) listBuckets(w http.ResponseWriter, r *http.Request, qbck *cmn.Q
 	)
 	if qbck.Provider != "" {
 		if qbck.IsAIS() || qbck.IsHT() { // built-in providers
-			bcks = bmd.Select(qbck)
+			bcks = bmd.Select(qbck, dpq.system)
 		} else {
 			bcks, code, err = t.blist(qbck, config)
 			if err != nil {
@@ -195,7 +195,7 @@ func (t *target) listBuckets(w http.ResponseWriter, r *http.Request, qbck *cmn.Q
 			var buckets cmn.Bcks
 			qbck.Provider = provider
 			if qbck.IsAIS() || qbck.IsHT() {
-				buckets = bmd.Select(qbck)
+				buckets = bmd.Select(qbck, dpq.system)
 			} else {
 				buckets, code, err = t.blist(qbck, config)
 				if err != nil {

api/apc/query.go

@@ -241,6 +241,9 @@ const (
 	// GetBatch
 	QparamTID   = "tid"   // designated target
 	QparamColoc = "coloc" // colocation hint: enum { 0=ColocNone, 1=ColocOne, 2=ColocTwo }
+
+	// System
+	QparamSystem = "sys"
 )
 
 // QparamWhat enum.

cmn/bck.go

@@ -309,8 +309,11 @@ func (b *Bck) ValidateName() error {
 	if b.Name == "" {
 		return errors.New("bucket name is missing")
 	}
-	if b.Name == "." {
-		return fmt.Errorf(fmtErrBckName, b.Name)
+	if b.Name[0] == '.' {
+		if b.IsSystem() {
+			return nil
+		}
+		return fmt.Errorf("reserved bucket name %q (unknown system bucket)", b.Name)
 	}
 	return cos.CheckAlphaPlus(b.Name, "bucket name")
 }
@@ -648,3 +651,16 @@ func NewHTTPObjPath(rawURL string) (*HTTPBckObj, error) {
 	}
 	return NewHTTPObj(urlObj), nil
 }
+
+//
+// system buckets -----------------------------------------------
+//
+
+const (
+	sysPrefix        = ".sys-" // currently unused; must be enforced when we add more system buckets
+	sysInventoryName = ".sys-inventory"
+)
+
+func (b *Bck) IsSystem() bool {
+	return b.Name == sysInventoryName
+}

cmn/err.go

@@ -32,7 +32,6 @@ import (
 const (
 	stackTracePrefix = "stack: ["
 
-	fmtErrBckName   = "bucket name %q is invalid: " + cos.OnlyPlus
 	fmtErrNamespace = "bucket namespace (uuid: %q, name: %q) " + cos.OnlyNice
 
 	FmtErrIntegrity      = "[%s%d, for troubleshooting see %s/blob/main/docs/troubleshooting.md]"

core/meta/bmd.go

@@ -155,22 +155,28 @@ func (m *BMD) Range(providerQuery *string, nsQuery *cmn.Ns, callback func(*Bck)
 	}
 }
 
-func (m *BMD) Select(qbck *cmn.QueryBcks) cmn.Bcks {
+func (m *BMD) Select(qbck *cmn.QueryBcks, includeSystem bool) cmn.Bcks {
 	var (
 		cp   *string
-		bcks = cmn.Bcks{} // (json representation: nil slice != empty slice)
+		bcks = cmn.Bcks{} // nil slice != empty slice
 	)
 	if qbck.Provider != "" {
 		cp = &qbck.Provider
 	}
 	m.Range(cp, nil, func(bck *Bck) bool {
 		b := bck.Bucket()
-		if qbck.Equal(b) || qbck.Contains(b) {
-			if len(bcks) == 0 {
-				bcks = make(cmn.Bcks, 0, 8)
-			}
-			bcks = append(bcks, bck.Clone())
+		if !qbck.Equal(b) && !qbck.Contains(b) {
+			return false
+		}
+
+		if !includeSystem && b.IsSystem() {
+			return false
+		}
+
+		if len(bcks) == 0 {
+			bcks = make(cmn.Bcks, 0, 16)
 		}
+		bcks = append(bcks, bck.Clone())
 		return false
 	})
 	sort.Sort(bcks)

core/meta/bmd_test.go

@@ -1,6 +1,6 @@
 // Package meta_test: unit tests for the package
 /*
- * Copyright (c) 2018-2025, NVIDIA CORPORATION. All rights reserved.
+ * Copyright (c) 2018-2026, NVIDIA CORPORATION. All rights reserved.
  */
 package meta_test
 
@@ -23,8 +23,8 @@ var _ = Describe("BMD", func() {
 				"bucket-1024",
 			),
 			Entry(
-				"with dots",
-				".bucket.name",
+				"with dot in the middle",
+				"bucket.name",
 			),
 			Entry(
 				"with '_' and '-'",
@@ -41,6 +41,10 @@ var _ = Describe("BMD", func() {
 				"empty bucket",
 				"",
 			),
+			Entry(
+				"with a leading dot",
+				".bucket.name",
+			),
 			Entry(
 				"contains '$'",
 				"jhljs$lsf",