Merge pull request #264 from aojea/refactor_alpha

Replace region semantics by opaque labels

Author: aojea

.github/k8s/sam-control-plane-template.yaml

@@ -52,7 +52,10 @@ spec:
         - name: POSTGRES_USER
           value: sam
         - name: POSTGRES_PASSWORD
-          value: sam-secret-password
+          valueFrom:
+            secretKeyRef:
+              name: sam-control-plane-secret-${ENV_NAME}
+              key: db-password
         - name: PGDATA
           value: /var/lib/postgresql/data/pgdata
         ports:
@@ -99,6 +102,11 @@ spec:
               name: sam-control-plane-secret-${ENV_NAME}
               key: admin-token
               optional: true
+        - name: SAM_DB_DSN
+          valueFrom:
+            secretKeyRef:
+              name: sam-control-plane-secret-${ENV_NAME}
+              key: db-dsn
         ports:
         - containerPort: 8080
           protocol: TCP
@@ -120,7 +128,6 @@ spec:
         args:
         - "--bind-address=0.0.0.0:8080"
         - "--db-driver=postgres"
-        - "--db-dsn=postgres://sam:sam-secret-password@sam-db-${ENV_NAME}:5432/sam_mesh?sslmode=disable"
         - "--issuer=https://auth.sam-mesh.dev,https://container.googleapis.com/v1/projects/${GCP_PROJECT_ID}/locations/${CLUSTER_REGION}/clusters/${CLUSTER_NAME}"
         - "--allowed-audiences=sam-mesh-audience,sam-control-plane-audience"
         - "--auto-approve-enrollment"

.github/workflows/deploy.yaml

@@ -314,11 +314,15 @@ jobs:
           export ENV_NAME="${VAR_ENV_NAME}"
           export NAMESPACE="sam-${ENV_NAME}"
           if ! kubectl get secret sam-control-plane-secret-${ENV_NAME} -n ${NAMESPACE} >/dev/null 2>&1; then
-            echo "Generating a new random 32-byte hex key for admin-token..."
+            echo "Generating new random secrets for admin-token and the DB..."
             ADMIN_TOKEN=$(openssl rand -hex 32)
+            DB_PASSWORD=$(openssl rand -hex 32)
+            DB_DSN="postgres://sam:${DB_PASSWORD}@sam-db-${ENV_NAME}:5432/sam_mesh?sslmode=disable"
             kubectl create secret generic sam-control-plane-secret-${ENV_NAME} \
               --namespace=${NAMESPACE} \
-              --from-literal=admin-token="${ADMIN_TOKEN}"
+              --from-literal=admin-token="${ADMIN_TOKEN}" \
+              --from-literal=db-password="${DB_PASSWORD}" \
+              --from-literal=db-dsn="${DB_DSN}"
           else
             echo "sam-control-plane-secret-${ENV_NAME} already exists in namespace ${NAMESPACE}. Skipping generation."
           fi

api/datalog.go

@@ -198,16 +198,17 @@ const (
 	// Example Datalog: service("mcp", "calculator")
 	FactService = "service"
 
-	// FactRegion is the control-plane-attested jurisdiction of the token's node,
-	// following the hierarchical model of region.go. The control plane mints one
-	// fact per hierarchy level (RegionPrefixes), so a requirement is a single
-	// exact match: a node attested as "EU-DE" carries region("EU") and
-	// region("EU-DE"), satisfying `check if region("EU")` but never a finer
-	// requirement it cannot guarantee. Distinct from LabelRegion, the
-	// unauthenticated gossip routing hint.
-	// Contains: biscuit.String(regionPrefix)
-	// Example Datalog: check if region("EU")
-	FactRegion = "region"
+	// FactLabel is a control-plane-attested key=value label on the token's
+	// node (see api/labels.go). The control plane mints one fact per
+	// declared label, so a requirement is a single exact match: a node
+	// attested with region="us-east-1" carries label("region", "us-east-1"),
+	// satisfying `check if label("region", "us-east-1")` only — composition
+	// across values is left entirely to the operator (attest as many labels
+	// as needed). Distinct from the unauthenticated gossip routing hint
+	// carried in ServiceAnnounce.labels.
+	// Contains: biscuit.String(key), biscuit.String(value)
+	// Example Datalog: check if label("region", "us-east-1")
+	FactLabel = "label"
 
 	// FactTime defines the current system time injected during evaluation.
 	// Contains: biscuit.Date(currentTime)
@@ -431,36 +432,51 @@ func BuildTargetDatalogFact(targetStr string) biscuit.Fact {
 	}}
 }
 
-// RegionFacts materializes a region claim as one Datalog fact per hierarchy
-// level (see FactRegion and RegionPrefixes). An empty region returns nil.
-func RegionFacts(region string) []biscuit.Fact {
-	prefixes := RegionPrefixes(region)
-	if len(prefixes) == 0 {
+// LabelFacts materializes a label set as one Datalog fact per key=value
+// pair (see FactLabel). Keys are sorted for deterministic fact ordering. An
+// empty set returns nil.
+func LabelFacts(labels map[string]string) []biscuit.Fact {
+	if len(labels) == 0 {
 		return nil
 	}
-	facts := make([]biscuit.Fact, 0, len(prefixes))
-	for _, p := range prefixes {
+	keys := make([]string, 0, len(labels))
+	for k := range labels {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	facts := make([]biscuit.Fact, 0, len(labels))
+	for _, k := range keys {
 		facts = append(facts, biscuit.Fact{Predicate: biscuit.Predicate{
-			Name: FactRegion,
-			IDs:  []biscuit.Term{biscuit.String(p)},
+			Name: FactLabel,
+			IDs:  []biscuit.Term{biscuit.String(k), biscuit.String(labels[k])},
 		}})
 	}
 	return facts
 }
 
-// RegionCheck compiles required regions (canonical, pre-validated with
-// ValidateRegion) into a single fail-closed check satisfied when the token
-// carries any of them: `check if region("EU") or region("NA-US")`.
-func RegionCheck(required []string) (biscuit.Check, error) {
+// LabelCheck compiles a required label set (canonical, pre-validated with
+// ValidateLabels) into a single fail-closed check satisfied when the token
+// carries any of them: `check if label("region", "us-east-1") or
+// label("team", "platform")`.
+func LabelCheck(required map[string]string) (biscuit.Check, error) {
 	if len(required) == 0 {
-		return biscuit.Check{}, fmt.Errorf("no required regions")
+		return biscuit.Check{}, fmt.Errorf("no required labels")
+	}
+	keys := make([]string, 0, len(required))
+	for k := range required {
+		keys = append(keys, k)
 	}
+	sort.Strings(keys)
 	clauses := make([]string, 0, len(required))
-	for _, r := range required {
-		if err := ValidateRegion(r); err != nil {
+	for _, k := range keys {
+		if err := ValidateLabelKey(k); err != nil {
+			return biscuit.Check{}, err
+		}
+		v := required[k]
+		if err := ValidateLabelValue(v); err != nil {
 			return biscuit.Check{}, err
 		}
-		clauses = append(clauses, fmt.Sprintf("%s(%q)", FactRegion, NormalizeRegion(r)))
+		clauses = append(clauses, fmt.Sprintf("%s(%q, %q)", FactLabel, k, v))
 	}
 	return parser.FromStringCheck("check if " + strings.Join(clauses, " or "))
 }

api/datalog_test.go

@@ -557,40 +557,40 @@ func TestBuildTargetDatalogFacts(t *testing.T) {
 	}
 }
 
-func TestRegionFactsAndCheck(t *testing.T) {
+func TestLabelFactsAndCheck(t *testing.T) {
 	pub, priv := makeKeyPair(t)
 
-	if facts := RegionFacts(""); facts != nil {
-		t.Errorf("RegionFacts(\"\") = %v, want nil", facts)
+	if facts := LabelFacts(nil); facts != nil {
+		t.Errorf("LabelFacts(nil) = %v, want nil", facts)
 	}
-	if _, err := RegionCheck(nil); err == nil {
-		t.Error("RegionCheck(nil): expected error, got nil")
+	if _, err := LabelCheck(nil); err == nil {
+		t.Error("LabelCheck(nil): expected error, got nil")
 	}
-	if _, err := RegionCheck([]string{"MARS"}); err == nil {
-		t.Error("RegionCheck(MARS): expected error, got nil")
+	if _, err := LabelCheck(map[string]string{"region": "bad,value"}); err == nil {
+		t.Error("LabelCheck(invalid value): expected error, got nil")
 	}
 
 	tests := []struct {
 		name        string
-		claimed     string // minted into the token via RegionFacts
-		required    []string
+		claimed     map[string]string // minted into the token via LabelFacts
+		required    map[string]string
 		expectAllow bool
 	}{
-		{"finer claim satisfies coarser requirement", "EU-DE-BY", []string{"EU"}, true},
-		{"exact level match", "EU-DE", []string{"EU-DE"}, true},
-		{"any-of requirement", "NA-US", []string{"EU", "NA-US"}, true},
-		{"lowercase requirement is normalized", "EU-DE", []string{"eu"}, true},
-		{"coarser claim never satisfies finer requirement", "EU", []string{"EU-DE"}, false},
-		{"disjoint region", "NA-US", []string{"EU"}, false},
-		{"unattested token fails closed", "", []string{"EU"}, false},
+		{"exact match", map[string]string{"region": "us-east-1"}, map[string]string{"region": "us-east-1"}, true},
+		{"any-of requirement", map[string]string{"region": "us-east-1"}, map[string]string{"region": "eu", "team": "us-east-1"}, false},
+		{"any-of requirement matches one key", map[string]string{"region": "us-east-1", "team": "platform"}, map[string]string{"region": "eu", "team": "platform"}, true},
+		{"case-sensitive value mismatch", map[string]string{"region": "us-east-1"}, map[string]string{"region": "US-EAST-1"}, false},
+		{"no built-in hierarchy: coarser requirement does not match a finer claim", map[string]string{"region": "us-east-1"}, map[string]string{"region": "us"}, false},
+		{"disjoint labels", map[string]string{"region": "us-east-1"}, map[string]string{"region": "eu-west-1"}, false},
+		{"unattested token fails closed", nil, map[string]string{"region": "us-east-1"}, false},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			builder := biscuit.NewBuilder(priv)
-			for _, fact := range RegionFacts(tt.claimed) {
+			for _, fact := range LabelFacts(tt.claimed) {
 				if err := builder.AddAuthorityFact(fact); err != nil {
-					t.Fatalf("failed to add region fact: %v", err)
+					t.Fatalf("failed to add label fact: %v", err)
 				}
 			}
 			tok, err := builder.Build()
@@ -602,9 +602,9 @@ func TestRegionFactsAndCheck(t *testing.T) {
 			if err != nil {
 				t.Fatalf("failed to create authorizer: %v", err)
 			}
-			check, err := RegionCheck(tt.required)
+			check, err := LabelCheck(tt.required)
 			if err != nil {
-				t.Fatalf("RegionCheck(%v): %v", tt.required, err)
+				t.Fatalf("LabelCheck(%v): %v", tt.required, err)
 			}
 			authorizer.AddCheck(check)
 			authorizer.AddPolicy(AllowIfTruePolicy)

api/labels.go

@@ -0,0 +1,77 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// Labels are free-form, control-plane-attested key=value metadata a node's
+// identity carries (e.g. region="us-east-1", team="platform"). Cloud
+// providers, on-prem operators, and countries all name things differently,
+// so SAM imposes no taxonomy or hierarchy on keys or values: composition
+// (e.g. attesting both a precise and a coarser value so a coarser
+// requirement also matches) is entirely up to the operator. Matching is
+// exact and case-sensitive on both key and value (see LabelCheck).
+//
+// Keys are plain conventions agreed by operators (e.g. "region"); SAM does
+// not reserve or interpret any key beyond ValidateLabelKey/ValidateLabelValue.
+
+// labelKeySyntax bounds label keys to a safe, portable charset.
+var labelKeySyntax = regexp.MustCompile(`^[a-zA-Z0-9_.-]{1,63}$`)
+
+// maxLabelValueLen bounds label values defensively; well within any
+// realistic cloud region/zone or on-prem naming convention.
+const maxLabelValueLen = 255
+
+// ValidateLabelKey checks that a label key is well-formed: 1-63 characters
+// from [a-zA-Z0-9_.-].
+func ValidateLabelKey(key string) error {
+	if !labelKeySyntax.MatchString(key) {
+		return fmt.Errorf("invalid label key %q: must be 1-63 chars of [a-zA-Z0-9_.-]", key)
+	}
+	return nil
+}
+
+// ValidateLabelValue checks that a label value is well-formed: non-empty,
+// bounded length, and free of characters that collide with the wire-format
+// separators (comma-separated key=value pairs) or control characters.
+func ValidateLabelValue(value string) error {
+	if value == "" {
+		return fmt.Errorf("label value must not be empty")
+	}
+	if len(value) > maxLabelValueLen {
+		return fmt.Errorf("label value %q exceeds %d characters", value, maxLabelValueLen)
+	}
+	if strings.ContainsAny(value, ",=\n\r\t") {
+		return fmt.Errorf("label value %q must not contain ',', '=', or control characters", value)
+	}
+	return nil
+}
+
+// ValidateLabels checks every key and value in a label set.
+func ValidateLabels(labels map[string]string) error {
+	for k, v := range labels {
+		if err := ValidateLabelKey(k); err != nil {
+			return err
+		}
+		if err := ValidateLabelValue(v); err != nil {
+			return err
+		}
+	}
+	return nil
+}

api/labels_test.go

@@ -0,0 +1,67 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package api
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateLabelKey(t *testing.T) {
+	valid := []string{"region", "team", "cloud-region", "on_prem.zone", "A1"}
+	for _, k := range valid {
+		if err := ValidateLabelKey(k); err != nil {
+			t.Errorf("ValidateLabelKey(%q): unexpected error: %v", k, err)
+		}
+	}
+
+	invalid := []string{"", "has space", "has,comma", "has=equals", strings.Repeat("a", 64)}
+	for _, k := range invalid {
+		if err := ValidateLabelKey(k); err == nil {
+			t.Errorf("ValidateLabelKey(%q): expected error, got nil", k)
+		}
+	}
+}
+
+func TestValidateLabelValue(t *testing.T) {
+	valid := []string{"us-east-1", "EU-DE", "office-berlin", "rack.3", "123"}
+	for _, v := range valid {
+		if err := ValidateLabelValue(v); err != nil {
+			t.Errorf("ValidateLabelValue(%q): unexpected error: %v", v, err)
+		}
+	}
+
+	invalid := []string{"", "has,comma", "has=equals", "has\ttab", strings.Repeat("a", maxLabelValueLen+1)}
+	for _, v := range invalid {
+		if err := ValidateLabelValue(v); err == nil {
+			t.Errorf("ValidateLabelValue(%q): expected error, got nil", v)
+		}
+	}
+}
+
+func TestValidateLabels(t *testing.T) {
+	if err := ValidateLabels(nil); err != nil {
+		t.Errorf("ValidateLabels(nil): unexpected error: %v", err)
+	}
+	if err := ValidateLabels(map[string]string{"region": "us-east-1", "team": "platform"}); err != nil {
+		t.Errorf("ValidateLabels(valid): unexpected error: %v", err)
+	}
+	if err := ValidateLabels(map[string]string{"region": ""}); err == nil {
+		t.Error("ValidateLabels(empty value): expected error, got nil")
+	}
+	if err := ValidateLabels(map[string]string{"bad key!": "v"}); err == nil {
+		t.Error("ValidateLabels(bad key): expected error, got nil")
+	}
+}