Merge pull request #261 from aojea/harden

feat(security): enforce region via control-plane-attested biscuit facts

Author: aojea

api/datalog.go

@@ -198,6 +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"
+
 	// FactTime defines the current system time injected during evaluation.
 	// Contains: biscuit.Date(currentTime)
 	// Example Datalog: check if time($time)
@@ -420,6 +431,40 @@ 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 {
+		return nil
+	}
+	facts := make([]biscuit.Fact, 0, len(prefixes))
+	for _, p := range prefixes {
+		facts = append(facts, biscuit.Fact{Predicate: biscuit.Predicate{
+			Name: FactRegion,
+			IDs:  []biscuit.Term{biscuit.String(p)},
+		}})
+	}
+	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) {
+	if len(required) == 0 {
+		return biscuit.Check{}, fmt.Errorf("no required regions")
+	}
+	clauses := make([]string, 0, len(required))
+	for _, r := range required {
+		if err := ValidateRegion(r); err != nil {
+			return biscuit.Check{}, err
+		}
+		clauses = append(clauses, fmt.Sprintf("%s(%q)", FactRegion, NormalizeRegion(r)))
+	}
+	return parser.FromStringCheck("check if " + strings.Join(clauses, " or "))
+}
+
 // isExactService reports whether serviceStr resolves to a plain exact-match grant, as opposed to a
 // wildcard/prefix/suffix pattern which already collapses to a single, cheap fact via BuildServiceDatalogFact.
 func isExactService(serviceStr string) (svcType, svcName string, exact bool) {

api/datalog_test.go

@@ -556,3 +556,65 @@ func TestBuildTargetDatalogFacts(t *testing.T) {
 		})
 	}
 }
+
+func TestRegionFactsAndCheck(t *testing.T) {
+	pub, priv := makeKeyPair(t)
+
+	if facts := RegionFacts(""); facts != nil {
+		t.Errorf("RegionFacts(\"\") = %v, want nil", facts)
+	}
+	if _, err := RegionCheck(nil); err == nil {
+		t.Error("RegionCheck(nil): expected error, got nil")
+	}
+	if _, err := RegionCheck([]string{"MARS"}); err == nil {
+		t.Error("RegionCheck(MARS): expected error, got nil")
+	}
+
+	tests := []struct {
+		name        string
+		claimed     string // minted into the token via RegionFacts
+		required    []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},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			builder := biscuit.NewBuilder(priv)
+			for _, fact := range RegionFacts(tt.claimed) {
+				if err := builder.AddAuthorityFact(fact); err != nil {
+					t.Fatalf("failed to add region fact: %v", err)
+				}
+			}
+			tok, err := builder.Build()
+			if err != nil {
+				t.Fatalf("failed to build token: %v", err)
+			}
+
+			authorizer, err := tok.Authorizer(pub, biscuit.WithWorldOptions(datalog.WithMaxDuration(5*time.Second)))
+			if err != nil {
+				t.Fatalf("failed to create authorizer: %v", err)
+			}
+			check, err := RegionCheck(tt.required)
+			if err != nil {
+				t.Fatalf("RegionCheck(%v): %v", tt.required, err)
+			}
+			authorizer.AddCheck(check)
+			authorizer.AddPolicy(AllowIfTruePolicy)
+
+			err = authorizer.Authorize()
+			if tt.expectAllow && err != nil {
+				t.Errorf("expected authorized, got error: %v", err)
+			} else if !tt.expectAllow && err == nil {
+				t.Error("expected denied, but authorization succeeded")
+			}
+		})
+	}
+}

api/region.go

@@ -114,6 +114,25 @@ func RegionMatches(required, claimed string) bool {
 	return claimed == required || strings.HasPrefix(claimed, required+"-")
 }
 
+// RegionPrefixes returns the hierarchy prefix closure of a region claim in
+// canonical form, coarsest first: "EU-DE-BY" -> ["EU", "EU-DE", "EU-DE-BY"].
+// Materializing every level lets policies match a requirement with a single
+// exact fact lookup (see FactRegion) while keeping RegionMatches semantics:
+// a finer claim carries its coarser prefixes, a coarser claim never gains
+// finer ones. The empty string returns nil.
+func RegionPrefixes(s string) []string {
+	s = NormalizeRegion(s)
+	if s == "" {
+		return nil
+	}
+	parts := strings.Split(s, "-")
+	out := make([]string, 0, len(parts))
+	for i := range parts {
+		out = append(out, strings.Join(parts[:i+1], "-"))
+	}
+	return out
+}
+
 // ContinentCodes returns the valid continent codes, sorted.
 func ContinentCodes() []string {
 	codes := make([]string, 0, len(continentNames))

api/region_test.go

@@ -71,3 +71,27 @@ func TestNormalizeRegion(t *testing.T) {
 		t.Errorf("NormalizeRegion: got %q, want EU-DE", got)
 	}
 }
+
+func TestRegionPrefixes(t *testing.T) {
+	tests := []struct {
+		in   string
+		want []string
+	}{
+		{"", nil},
+		{"EU", []string{"EU"}},
+		{"eu-de", []string{"EU", "EU-DE"}}, // normalized
+		{"EU-DE-BY", []string{"EU", "EU-DE", "EU-DE-BY"}},
+	}
+	for _, tt := range tests {
+		got := RegionPrefixes(tt.in)
+		if len(got) != len(tt.want) {
+			t.Errorf("RegionPrefixes(%q) = %v, want %v", tt.in, got, tt.want)
+			continue
+		}
+		for i := range got {
+			if got[i] != tt.want[i] {
+				t.Errorf("RegionPrefixes(%q)[%d] = %q, want %q", tt.in, i, got[i], tt.want[i])
+			}
+		}
+	}
+}

api/sam.pb.go

@@ -49,6 +49,11 @@ message EnrollRequest {
   string peer_id = 2;
   bytes public_key = 3;
   string requested_role = 4;
+  // Operator-declared region claim (CONTINENT[-COUNTRY[-ZONE]], see
+  // api/region.go). Validated fail-closed by the control plane and, once
+  // attested by the enrollment flow's gates, minted as signed region()
+  // facts in the biscuit. Empty means no claim.
+  string region = 5;
 }
 
 message EnrollResponse {
@@ -75,6 +80,9 @@ message BootstrapEnrollRequest {
   string peer_id = 2;
   bytes public_key = 3;
   string requested_role = 4;
+  // Operator-declared region claim; the admin approving the enrollment
+  // attests it (see EnrollRequest.region).
+  string region = 5;
 }
 
 message BootstrapEnrollResponse {

api/sam.proto

@@ -114,7 +114,7 @@ func TestPolicyScale(t *testing.T) {
 		}
 
 		start = time.Now()
-		biscuitBytes, _, err := identity.MintBiscuitToken(priv, claims, nil, nodePeer, time.Now().Add(time.Hour), roleNames, roles)
+		biscuitBytes, _, err := identity.MintBiscuitToken(priv, claims, nil, nodePeer, time.Now().Add(time.Hour), roleNames, roles, "")
 		mintDur := time.Since(start)
 		if err != nil {
 			t.Fatalf("mint failed at n=%d: %v", n, err)
@@ -200,7 +200,7 @@ func TestPolicyScaleSetEncoding(t *testing.T) {
 
 		claims := jwt.MapClaims{}
 		start := time.Now()
-		biscuitBytes, _, err := identity.MintBiscuitToken(priv, claims, nil, nodePeer, time.Now().Add(time.Hour), []string{"bulk-role"}, roles)
+		biscuitBytes, _, err := identity.MintBiscuitToken(priv, claims, nil, nodePeer, time.Now().Add(time.Hour), []string{"bulk-role"}, roles, "")
 		mintDur := time.Since(start)
 		if err != nil {
 			t.Fatalf("mint failed at n=%d exact entries: %v", n, err)
@@ -319,7 +319,7 @@ func TestPolicyScaleManyRoles(t *testing.T) {
 
 		claims := jwt.MapClaims{}
 		start := time.Now()
-		biscuitBytes, _, err := identity.MintBiscuitToken(priv, claims, nil, nodePeer, time.Now().Add(time.Hour), roleNames, roles)
+		biscuitBytes, _, err := identity.MintBiscuitToken(priv, claims, nil, nodePeer, time.Now().Add(time.Hour), roleNames, roles, "")
 		mintDur := time.Since(start)
 		if err != nil {
 			t.Fatalf("mint failed at n=%d matched roles: %v", n, err)