Skip to content

Agent Mesh

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

Antonio Ojeabda7e72e48a1
diff --git a/api/datalog.go b/api/datalog.go
index 82f6253f..6e3be2ec 100644
--- a/api/datalog.go
+++ b/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) {
diff --git a/api/datalog_test.go b/api/datalog_test.go
index 320159d1..d2781793 100644
--- a/api/datalog_test.go
+++ b/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")
+ }
+ })
+ }
+}
diff --git a/api/region.go b/api/region.go
index ef0881b2..2fd6f568 100644
--- a/api/region.go
+++ b/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))
diff --git a/api/region_test.go b/api/region_test.go
index 5a520be6..753addc1 100644
--- a/api/region_test.go
+++ b/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])
+ }
+ }
+ }
+}
diff --git a/api/sam.pb.go b/api/sam.pb.go
index db4723f2..e3bdc292 100644
--- a/api/sam.pb.go
+++ b/api/sam.pb.go
@@ -379,6 +379,11 @@ type EnrollRequest struct {
PeerId string `protobuf:"bytes,2,opt,name=peer_id,json=peerId,proto3" json:"peer_id,omitempty"`
PublicKey []byte `protobuf:"bytes,3,opt,name=public_key,json=publicKey,proto3" json:"public_key,omitempty"`
RequestedRole string `protobuf:"bytes,4,opt,name=requested_role,json=requestedRole,proto3" json:"requested_role,omitempty"`
+ // 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.
+ Region string `protobuf:"bytes,5,opt,name=region,proto3" json:"region,omitempty"`
unknownFields protoimpl.UnknownFields
sizeCache protoimpl.SizeCache
}
@@ -441,6 +446,13 @@ func (x *EnrollRequest) GetRequestedRole() string {
return ""
}
+func (x *EnrollRequest) GetRegion() string {
+ if x != nil {
+ return x.Region
+ }
+ return ""
+}
+
type EnrollResponse struct {
state protoimpl.MessageState `protogen:"open.v1"`
BiscuitToken []byte `protobuf:"bytes,1,opt,name=biscuit_token,json=biscuitToken,proto3" json:"biscuit_token,omitempty"`
@@ -567,8 +579,11 @@ type BootstrapEnrollRequest struct {
PeerId string `protobuf:"bytes,2,opt,name=peer_id,json=peerId,proto3" json:"peer_id,omitempty"`
PublicKey []byte `protobuf:"bytes,3,opt,name=public_key,json=publicKey,proto3" json:"public_key,omitempty"`
RequestedRole string `protobuf:"bytes,4,opt,name=requested_role,json=requestedRole,proto3" json:"requested_role,omitempty"`
- unknownFields protoimpl.UnknownFields
- sizeCache protoimpl.SizeCache
+ // Operator-declared region claim; the admin approving the enrollment
+ // attests it (see EnrollRequest.region).
+ Region string `protobuf:"bytes,5,opt,name=region,proto3" json:"region,omitempty"`
+ unknownFields protoimpl.UnknownFields
+ sizeCache protoimpl.SizeCache
}
func (x *BootstrapEnrollRequest) Reset() {
@@ -629,6 +644,13 @@ func (x *BootstrapEnrollRequest) GetRequestedRole() string {
return ""
}
+func (x *BootstrapEnrollRequest) GetRegion() string {
+ if x != nil {
+ return x.Region
+ }
+ return ""
+}
+
type BootstrapEnrollResponse struct {
state protoimpl.MessageState `protogen:"open.v1"`
Status EnrollmentStatus `protobuf:"varint,1,opt,name=status,proto3,enum=sam.v1.EnrollmentStatus" json:"status,omitempty"`
@@ -1890,13 +1912,14 @@ const file_api_sam_proto_rawDesc = "" +
"\n" +
"\x06BANNED\x10\x00\x12\x10\n" +
"\fKEY_ROTATION\x10\x01\x12\x11\n" +
- "\rPOLICY_UPDATE\x10\x02\"\x80\x01\n" +
+ "\rPOLICY_UPDATE\x10\x02\"\x98\x01\n" +
"\rEnrollRequest\x12\x10\n" +
"\x03jwt\x18\x01 \x01(\tR\x03jwt\x12\x17\n" +
"\apeer_id\x18\x02 \x01(\tR\x06peerId\x12\x1d\n" +
"\n" +
"public_key\x18\x03 \x01(\fR\tpublicKey\x12%\n" +
- "\x0erequested_role\x18\x04 \x01(\tR\rrequestedRole\"\xde\x01\n" +
+ "\x0erequested_role\x18\x04 \x01(\tR\rrequestedRole\x12\x16\n" +
+ "\x06region\x18\x05 \x01(\tR\x06region\"\xde\x01\n" +
"\x0eEnrollResponse\x12#\n" +
"\rbiscuit_token\x18\x01 \x01(\fR\fbiscuitToken\x12#\n" +
"\rerror_message\x18\x02 \x01(\tR\ferrorMessage\x127\n" +
@@ -1906,13 +1929,14 @@ const file_api_sam_proto_rawDesc = "" +
"expiration\x18\x05 \x01(\x03R\n" +
"expiration\"2\n" +
"\x17EnrollmentStatusRequest\x12\x17\n" +
- "\apeer_id\x18\x01 \x01(\tR\x06peerId\"\xa0\x01\n" +
+ "\apeer_id\x18\x01 \x01(\tR\x06peerId\"\xb8\x01\n" +
"\x16BootstrapEnrollRequest\x12'\n" +
"\x0fbootstrap_token\x18\x01 \x01(\tR\x0ebootstrapToken\x12\x17\n" +
"\apeer_id\x18\x02 \x01(\tR\x06peerId\x12\x1d\n" +
"\n" +
"public_key\x18\x03 \x01(\fR\tpublicKey\x12%\n" +
- "\x0erequested_role\x18\x04 \x01(\tR\rrequestedRole\"\xcd\x02\n" +
+ "\x0erequested_role\x18\x04 \x01(\tR\rrequestedRole\x12\x16\n" +
+ "\x06region\x18\x05 \x01(\tR\x06region\"\xcd\x02\n" +
"\x17BootstrapEnrollResponse\x120\n" +
"\x06status\x18\x01 \x01(\x0e2\x18.sam.v1.EnrollmentStatusR\x06status\x12#\n" +
"\rbiscuit_token\x18\x02 \x01(\fR\fbiscuitToken\x122\n" +
diff --git a/api/sam.proto b/api/sam.proto
index 12076f00..8c21e23e 100644
--- a/api/sam.proto
+++ b/api/sam.proto
@@ -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 {
diff --git a/internal/controlplane/policy_scale_test.go b/internal/controlplane/policy_scale_test.go
index c19a3913..658f2d0e 100644
--- a/internal/controlplane/policy_scale_test.go
+++ b/internal/controlplane/policy_scale_test.go
@@ -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)
diff --git a/internal/controlplane/server.go b/internal/controlplane/server.go
index d25a8147..7abab35a 100644
--- a/internal/controlplane/server.go
+++ b/internal/controlplane/server.go
@@ -431,6 +431,16 @@ func (s *Server) HandleRegister(w http.ResponseWriter, r *http.Request) {
return
}
+ // Fail closed on malformed region claims; canonical form is what gets
+ // attested into the biscuit and persisted for refreshes.
+ region := api.NormalizeRegion(req.Region)
+ if region != "" {
+ if err := api.ValidateRegion(region); err != nil {
+ http.Error(w, "Invalid region: "+err.Error(), http.StatusBadRequest)
+ return
+ }
+ }
+
policyRoles, bindings, err := s.store.GetMeshPolicy(ctx)
if err != nil && err != storage.ErrNotFound {
logger.Errorf("Failed to load policy for registration: %v", err)
@@ -468,7 +478,7 @@ func (s *Server) HandleRegister(w http.ResponseWriter, r *http.Request) {
// Mint token
biscuitExpiry := time.Now().Add(api.BiscuitTokenTTL)
- biscuitData, _, err := identity.MintBiscuitToken(privKey, claims, token, pID, biscuitExpiry, finalRoles, policyRoles)
+ biscuitData, _, err := identity.MintBiscuitToken(privKey, claims, token, pID, biscuitExpiry, finalRoles, policyRoles, region)
if err != nil {
logger.Errorw("Biscuit minting failed", "peer_id", req.PeerId, "error", err)
http.Error(w, "Failed to mint biscuit: "+err.Error(), http.StatusForbidden)
@@ -493,6 +503,7 @@ func (s *Server) HandleRegister(w http.ResponseWriter, r *http.Request) {
Role: primaryRole,
EnrollmentType: "OIDC",
ClaimsJSON: string(claimsBytes),
+ Region: region,
EnrolledAt: time.Now(),
ExpiresAt: sessionExpiresAt,
}
@@ -683,7 +694,7 @@ func (s *Server) HandleRefresh(w http.ResponseWriter, r *http.Request) {
finalRoles := []string{nodeRecord.Role}
finalRoles = append(finalRoles, customAccessRoles...)
- bBytes, _, err := identity.MintBiscuitToken(privKey, claims, nil, pID, biscuitExpiry, finalRoles, policyRoles)
+ bBytes, _, err := identity.MintBiscuitToken(privKey, claims, nil, pID, biscuitExpiry, finalRoles, policyRoles, nodeRecord.Region)
if err != nil {
logger.Errorf("Failed to mint refreshed token for node %s: %v", nodeRecord.PeerID, err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -692,7 +703,7 @@ func (s *Server) HandleRefresh(w http.ResponseWriter, r *http.Request) {
biscuitBytes = bBytes
} else {
// Bootstrap node
- bBytes, err := identity.MintBootstrapBiscuitToken(privKey, pID, nodeRecord.Role, biscuitExpiry, policyRoles)
+ bBytes, err := identity.MintBootstrapBiscuitToken(privKey, pID, nodeRecord.Role, biscuitExpiry, policyRoles, nodeRecord.Region)
if err != nil {
logger.Errorf("Failed to mint refreshed token for node %s: %v", nodeRecord.PeerID, err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -1085,6 +1096,14 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {
return
}
+ region := api.NormalizeRegion(req.Region)
+ if region != "" {
+ if err := api.ValidateRegion(region); err != nil {
+ s.writeEnrollError(w, api.EnrollmentStatus_ENROLLMENT_STATUS_REJECTED, "Invalid region: "+err.Error())
+ return
+ }
+ }
+
pID, err := peer.Decode(req.PeerId)
if err != nil {
http.Error(w, "Invalid Peer ID", http.StatusBadRequest)
@@ -1124,6 +1143,7 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {
PublicKey: req.PublicKey,
TokenID: tokenRecord.ID,
Status: api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING,
+ Region: region,
CreatedAt: time.Now(),
}
@@ -1145,7 +1165,7 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {
http.Error(w, "Internal server error", http.StatusInternalServerError)
return
}
- biscuitBytes, err := identity.MintBootstrapBiscuitToken(privKey, pID, tokenRecord.Role, time.Now().Add(api.BiscuitTokenTTL), policyRoles)
+ biscuitBytes, err := identity.MintBootstrapBiscuitToken(privKey, pID, tokenRecord.Role, time.Now().Add(api.BiscuitTokenTTL), policyRoles, region)
if err != nil {
logger.Errorf("Failed to mint bootstrap biscuit: %v", err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -1170,6 +1190,7 @@ func (s *Server) HandleEnroll(w http.ResponseWriter, r *http.Request) {
Biscuit: biscuitBytes,
Role: tokenRecord.Role,
EnrollmentType: "BOOTSTRAP",
+ Region: region,
EnrolledAt: time.Now(),
ExpiresAt: time.Time{},
}
@@ -1494,7 +1515,9 @@ func (s *Server) HandleAdminEnrollmentAction(w http.ResponseWriter, r *http.Requ
http.Error(w, "Internal server error", http.StatusInternalServerError)
return
}
- biscuitBytes, err := identity.MintBootstrapBiscuitToken(privKey, pID, tokenRecord.Role, time.Now().Add(api.BiscuitTokenTTL), policyRoles)
+ // Admin approval is the attestation of the operator-declared region
+ // recorded on the pending request.
+ biscuitBytes, err := identity.MintBootstrapBiscuitToken(privKey, pID, tokenRecord.Role, time.Now().Add(api.BiscuitTokenTTL), policyRoles, enrollReq.Region)
if err != nil {
logger.Errorf("Failed to mint bootstrap biscuit: %v", err)
http.Error(w, "Internal server error", http.StatusInternalServerError)
@@ -1514,6 +1537,7 @@ func (s *Server) HandleAdminEnrollmentAction(w http.ResponseWriter, r *http.Requ
Biscuit: biscuitBytes,
Role: tokenRecord.Role,
EnrollmentType: "BOOTSTRAP",
+ Region: enrollReq.Region,
EnrolledAt: time.Now(),
ExpiresAt: time.Time{},
}
diff --git a/internal/identity/biscuit.go b/internal/identity/biscuit.go
index 22b7fc93..7e389092 100644
--- a/internal/identity/biscuit.go
+++ b/internal/identity/biscuit.go
@@ -32,19 +32,20 @@ import (
)
// MintBiscuitToken generates a signed Biscuit token for a peer with policy rules based on JWT claims.
-func MintBiscuitToken(signingKey ed25519.PrivateKey, claims jwt.MapClaims, token *oidc.IDToken, remotePeer peer.ID, biscuitExpiry time.Time, roles []string, policyRoles []*api.PolicyRole) ([]byte, []string, error) {
+// region is the control-plane-attested region claim (canonical, pre-validated); empty means no claim.
+func MintBiscuitToken(signingKey ed25519.PrivateKey, claims jwt.MapClaims, token *oidc.IDToken, remotePeer peer.ID, biscuitExpiry time.Time, roles []string, policyRoles []*api.PolicyRole, region string) ([]byte, []string, error) {
if claims == nil {
return nil, nil, fmt.Errorf("claims cannot be nil")
}
- biscuitBytes, err := mintBiscuit(signingKey, remotePeer, roles, biscuitExpiry, claims, policyRoles)
+ biscuitBytes, err := mintBiscuit(signingKey, remotePeer, roles, biscuitExpiry, claims, policyRoles, region)
if err != nil {
return nil, nil, err
}
return biscuitBytes, roles, nil
}
-func mintBiscuit(signingKey ed25519.PrivateKey, remotePeer peer.ID, roles []string, expiration time.Time, claims jwt.MapClaims, policyRoles []*api.PolicyRole) ([]byte, error) {
+func mintBiscuit(signingKey ed25519.PrivateKey, remotePeer peer.ID, roles []string, expiration time.Time, claims jwt.MapClaims, policyRoles []*api.PolicyRole, region string) ([]byte, error) {
builder := biscuit.NewBuilder(signingKey)
addedFacts := make(map[string]bool)
addFact := func(fact biscuit.Fact) error {
@@ -80,6 +81,14 @@ func mintBiscuit(signingKey ed25519.PrivateKey, remotePeer peer.ID, roles []stri
return nil, fmt.Errorf("failed to add client_peer_id fact: %w", err)
}
+ // One signed fact per hierarchy level so a requirement is a single exact
+ // match (see api.FactRegion).
+ for _, fact := range api.RegionFacts(region) {
+ if err := addFact(fact); err != nil {
+ return nil, fmt.Errorf("failed to add region fact: %w", err)
+ }
+ }
+
if claims != nil {
if err := translateClaimsToFacts(addFact, claims); err != nil {
return nil, err
@@ -334,8 +343,9 @@ func toStringSlice(val any) []string {
}
// MintBootstrapBiscuitToken generates a signed Biscuit token for a peer using a bootstrap role.
-func MintBootstrapBiscuitToken(signingKey ed25519.PrivateKey, remotePeer peer.ID, role string, expiration time.Time, policyRoles []*api.PolicyRole) ([]byte, error) {
- return mintBiscuit(signingKey, remotePeer, []string{role}, expiration, nil, policyRoles)
+// region is the control-plane-attested region claim (canonical, pre-validated); empty means no claim.
+func MintBootstrapBiscuitToken(signingKey ed25519.PrivateKey, remotePeer peer.ID, role string, expiration time.Time, policyRoles []*api.PolicyRole, region string) ([]byte, error) {
+ return mintBiscuit(signingKey, remotePeer, []string{role}, expiration, nil, policyRoles, region)
}
// VerifyAndExtractPeerID checks that the biscuit is signed by one of the trusted keys and returns the peer ID.
diff --git a/internal/identity/biscuit_test.go b/internal/identity/biscuit_test.go
index 0987ab0a..0e8a3081 100644
--- a/internal/identity/biscuit_test.go
+++ b/internal/identity/biscuit_test.go
@@ -71,7 +71,7 @@ func TestVerifyBiscuit_Expiration(t *testing.T) {
"roles": []any{"admin"},
}
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"admin"}, nil)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"admin"}, nil, "")
if err != nil {
t.Fatalf("MintBiscuitToken failed: %v", err)
}
@@ -112,7 +112,7 @@ func TestMintBiscuitToken_ClaimsTranslation(t *testing.T) {
"groups": []any{"beta-testers", "engineering"},
}
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, nil, nil)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, nil, nil, "")
if err != nil {
t.Fatalf("Failed to mint biscuit: %v", err)
}
@@ -202,7 +202,7 @@ func TestVerifyBiscuit_Concurrent(t *testing.T) {
"roles": []any{"admin"},
}
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"admin"}, nil)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"admin"}, nil, "")
if err != nil {
t.Fatalf("MintBiscuitToken failed: %v", err)
}
@@ -250,7 +250,7 @@ func TestMintBiscuitToken(t *testing.T) {
"groups": []any{"group1", "group2"},
"roles": []any{"admin", "user"},
}
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"admin", "user"}, nil)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"admin", "user"}, nil, "")
if err != nil {
t.Fatal(err)
}
@@ -349,7 +349,7 @@ func TestMintBiscuitToken_VariousClaimsTypes(t *testing.T) {
claims["groups"] = tt.groupsClaim
}
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, tt.expectedRoles, nil)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, tt.expectedRoles, nil, "")
if err != nil {
t.Fatalf("MintBiscuitToken failed: %v", err)
}
@@ -428,7 +428,7 @@ func TestMintBiscuitToken_WithPolicyRoles(t *testing.T) {
}
t.Run("Mint with matching policy role", func(t *testing.T) {
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"data-scientist"}, policyRoles)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"data-scientist"}, policyRoles, "")
if err != nil {
t.Fatalf("MintBiscuitToken failed: %v", err)
}
@@ -457,7 +457,7 @@ func TestMintBiscuitToken_WithPolicyRoles(t *testing.T) {
})
t.Run("Mint with unmapped role when policy exists", func(t *testing.T) {
- biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"unmapped-role"}, policyRoles)
+ biscuitData, _, err := MintBiscuitToken(priv, claims, token, dummyPeer, token.Expiry, []string{"unmapped-role"}, policyRoles, "")
if err != nil {
t.Fatalf("MintBiscuitToken failed: %v", err)
}
@@ -484,6 +484,59 @@ func TestMintBiscuitToken_WithPolicyRoles(t *testing.T) {
})
}
+func TestMintBiscuitToken_RegionFacts(t *testing.T) {
+ pub, priv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+ dummyPeer := peer.ID("dummy-peer-region")
+
+ biscuitData, err := MintBootstrapBiscuitToken(priv, dummyPeer, api.RoleNode, time.Now().Add(1*time.Hour), nil, "EU-DE-BY")
+ if err != nil {
+ t.Fatalf("MintBootstrapBiscuitToken failed: %v", err)
+ }
+ b, err := biscuit.Unmarshal(biscuitData)
+ if err != nil {
+ t.Fatalf("Unmarshal biscuit failed: %v", err)
+ }
+
+ // Every hierarchy level is present as its own fact.
+ for _, region := range []string{"EU", "EU-DE", "EU-DE-BY"} {
+ authorizer, err := b.Authorizer(pub)
+ if err != nil {
+ t.Fatalf("Authorizer failed: %v", err)
+ }
+ authorizer.AddCheck(biscuit.Check{Queries: []biscuit.Rule{
+ {Body: []biscuit.Predicate{{Name: api.FactRegion, IDs: []biscuit.Term{biscuit.String(region)}}}},
+ }})
+ authorizer.AddPolicy(api.AllowIfTruePolicy)
+ if err := authorizer.Authorize(); err != nil {
+ t.Errorf("expected region(%q) fact, got error: %v", region, err)
+ }
+ }
+
+ // No region facts when minted without a claim.
+ noRegionData, err := MintBootstrapBiscuitToken(priv, dummyPeer, api.RoleNode, time.Now().Add(1*time.Hour), nil, "")
+ if err != nil {
+ t.Fatalf("MintBootstrapBiscuitToken failed: %v", err)
+ }
+ b2, err := biscuit.Unmarshal(noRegionData)
+ if err != nil {
+ t.Fatalf("Unmarshal biscuit failed: %v", err)
+ }
+ authorizer, err := b2.Authorizer(pub)
+ if err != nil {
+ t.Fatalf("Authorizer failed: %v", err)
+ }
+ authorizer.AddCheck(biscuit.Check{Queries: []biscuit.Rule{
+ {Body: []biscuit.Predicate{{Name: api.FactRegion, IDs: []biscuit.Term{biscuit.Variable("r")}}}},
+ }})
+ authorizer.AddPolicy(api.AllowIfTruePolicy)
+ if err := authorizer.Authorize(); err == nil {
+ t.Error("expected no region facts for an unclaimed region, but check passed")
+ }
+}
+
func TestVerifyAndExtractPeerID_MultipleTrustedKeys(t *testing.T) {
pub1, _, err := ed25519.GenerateKey(rand.Reader)
if err != nil {
@@ -503,7 +556,7 @@ func TestVerifyAndExtractPeerID_MultipleTrustedKeys(t *testing.T) {
t.Fatal(err)
}
- biscuitData, err := MintBootstrapBiscuitToken(priv2, dummyPeer, api.RoleNode, time.Now().Add(1*time.Hour), nil)
+ biscuitData, err := MintBootstrapBiscuitToken(priv2, dummyPeer, api.RoleNode, time.Now().Add(1*time.Hour), nil, "")
if err != nil {
t.Fatalf("MintBootstrapBiscuitToken failed: %v", err)
}
diff --git a/internal/node/enroll.go b/internal/node/enroll.go
index d3b484bd..a0b96e16 100644
--- a/internal/node/enroll.go
+++ b/internal/node/enroll.go
@@ -71,6 +71,7 @@ func (n *SamNode) Enroll(ctx context.Context, controlPlaneURL string, jwt string
PeerId: n.Host.ID().String(),
PublicKey: pubBytes,
RequestedRole: n.config.RequiredRole,
+ Region: n.config.Region, // normalized and validated at startup
}
data, err := proto.Marshal(req)
if err != nil {
@@ -197,6 +198,7 @@ func (n *SamNode) EnrollBootstrap(ctx context.Context, controlPlaneURL string, b
PeerId: n.Host.ID().String(),
PublicKey: pubBytes,
RequestedRole: n.config.RequiredRole,
+ Region: n.config.Region, // normalized and validated at startup
}
data, err := proto.Marshal(req)
if err != nil {
diff --git a/internal/node/middleware.go b/internal/node/middleware.go
index d5b3a77f..9baeb439 100644
--- a/internal/node/middleware.go
+++ b/internal/node/middleware.go
@@ -118,8 +118,10 @@ func (n *SamNode) WithBiscuitAuth(next func(network.Stream, RequestContext)) net
return
}
- // Valid
- resp := &api.AuthResponse{Success: true}
+ // Valid. Mutual auth: return our control-plane-minted identity so the
+ // caller can verify this node's attested facts (e.g. region) before
+ // sending request data.
+ resp := &api.AuthResponse{Success: true, Biscuit: n.GetIdentity()}
respBytes, _ := proto.Marshal(resp)
if err := writer.WriteMsg(respBytes); err != nil {
logger.Errorf("[Auth] Failed to write ACK to %s: %v", remotePeer, err)
diff --git a/internal/node/middleware_test.go b/internal/node/middleware_test.go
index 73256744..9f56e28e 100644
--- a/internal/node/middleware_test.go
+++ b/internal/node/middleware_test.go
@@ -29,6 +29,7 @@ import (
"github.com/biscuit-auth/biscuit-go/v2"
"github.com/biscuit-auth/biscuit-go/v2/parser"
"github.com/google/sam/api"
+ "github.com/google/sam/internal/identity"
lru "github.com/hashicorp/golang-lru/v2"
golog "github.com/ipfs/go-log/v2"
"github.com/libp2p/go-libp2p/core/crypto"
@@ -555,6 +556,93 @@ func TestRevocation(t *testing.T) {
}
}
+func TestWithBiscuitAuth_MutualBiscuit(t *testing.T) {
+ pub, priv, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ clientPeer := peer.ID("dummy-peer-id")
+ serverPeer := peer.ID("server-peer-id")
+
+ // Client token satisfying replay, service and target checks.
+ builder := biscuit.NewBuilder(priv)
+ for _, f := range []biscuit.Fact{
+ {Predicate: biscuit.Predicate{Name: "node", IDs: []biscuit.Term{biscuit.String(clientPeer.String())}}},
+ {Predicate: biscuit.Predicate{Name: "client_peer_id", IDs: []biscuit.Term{biscuit.String(clientPeer.String())}}},
+ {Predicate: biscuit.Predicate{Name: "granted_service_all_types"}},
+ {Predicate: biscuit.Predicate{Name: "target_unrestricted"}},
+ } {
+ if err := builder.AddAuthorityFact(f); err != nil {
+ t.Fatal(err)
+ }
+ }
+ b, err := builder.Build()
+ if err != nil {
+ t.Fatal(err)
+ }
+ tokenBytes, err := b.Serialize()
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ // Server identity: control-plane-minted with an attested region.
+ serverIdentity, err := identity.MintBootstrapBiscuitToken(priv, serverPeer, api.RoleNode, time.Now().Add(time.Hour), nil, "EU-DE")
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ rl, _ := NewPeerRateLimiter(100)
+ node := &SamNode{
+ trustedKeys: []TrustedKey{{Key: pub, ReceivedAt: time.Now()}},
+ rateLimiter: rl,
+ BiscuitTimeout: 500 * time.Millisecond,
+ }
+ node.SetIdentityCache(serverIdentity)
+
+ pr1, pw1 := io.Pipe()
+ pr2, pw2 := io.Pipe()
+ serverStream := &mockStream{r: pr1, w: pw2, protocol: protocol.ID("/test/proto"), conn: &mockConn{remotePeer: clientPeer}}
+
+ done := make(chan struct{})
+ go func() {
+ defer close(done)
+ handler := node.WithBiscuitAuth(func(s network.Stream, reqCtx RequestContext) {})
+ handler(serverStream)
+ }()
+
+ writer := msgio.NewVarintWriter(pw1)
+ data, _ := proto.Marshal(&api.AuthFrame{Biscuit: tokenBytes})
+ if err := writer.WriteMsg(data); err != nil {
+ t.Fatal(err)
+ }
+
+ reader := msgio.NewVarintReaderSize(pr2, 1024*64)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ t.Fatalf("failed to read response: %v", err)
+ }
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(msg, &resp); err != nil {
+ t.Fatal(err)
+ }
+ if !resp.Success {
+ t.Fatalf("handshake failed: %s", resp.Error)
+ }
+ if !bytes.Equal(resp.Biscuit, serverIdentity) {
+ t.Error("mutual auth response must carry the server's identity biscuit")
+ }
+
+ // The returned biscuit satisfies the consumer-side region gate.
+ if err := node.checkPeerRegions(resp.Biscuit, serverPeer, []string{"EU"}); err != nil {
+ t.Errorf("region gate rejected the mutual-auth biscuit: %v", err)
+ }
+ if err := node.checkPeerRegions(resp.Biscuit, serverPeer, []string{"NA"}); err == nil {
+ t.Error("region gate must reject a non-matching requirement")
+ }
+ <-done
+}
+
func TestVerifyEvent(t *testing.T) {
pub, priv, err := ed25519.GenerateKey(nil)
if err != nil {
diff --git a/internal/node/node.go b/internal/node/node.go
index 6857aad1..543b18df 100644
--- a/internal/node/node.go
+++ b/internal/node/node.go
@@ -136,6 +136,7 @@ type SamNode struct {
mu sync.Mutex
LocalPolicy *NodeConfigComplete
revokedPeers *lru.Cache[string, int64]
+ peerRegionGate *lru.Cache[string, time.Time]
authPeers sync.Map
trustedKeys []TrustedKey
keysMu sync.RWMutex
@@ -263,6 +264,10 @@ func NewSamNode(cfg Options) (*SamNode, error) {
if err != nil {
return nil, fmt.Errorf("failed to create revocation cache: %w", err)
}
+ node.peerRegionGate, err = lru.New[string, time.Time](regionGateCacheSize)
+ if err != nil {
+ return nil, fmt.Errorf("failed to create region gate cache: %w", err)
+ }
return node, nil
}
@@ -1405,6 +1410,14 @@ func (n *SamNode) HandleAuthHandshake(s network.Stream) {
n.authPeers.Store(remotePeer, true)
logger.Infof("[AuthN] Successfully authenticated peer %s", remotePeer)
+
+ // Mutual response with our identity, mirroring the router handler, so
+ // peers can verify this node's attested facts (e.g. region).
+ writer := msgio.NewVarintWriter(s)
+ respBytes, _ := proto.Marshal(&api.AuthResponse{Success: true, Biscuit: n.GetIdentity()})
+ if err := writer.WriteMsg(respBytes); err != nil {
+ logger.Errorf("[AuthN] Failed to write mutual ACK to %s: %v", remotePeer, err)
+ }
}
func (n *SamNode) verifyBiscuit(biscuitData []byte, remotePeer peer.ID) (*biscuit.Biscuit, error) {
diff --git a/internal/node/openai_facade.go b/internal/node/openai_facade.go
index c93e76f7..efe78bda 100644
--- a/internal/node/openai_facade.go
+++ b/internal/node/openai_facade.go
@@ -78,6 +78,14 @@ type openAIFacade struct {
// Scorer seams (may be nil): revocation check and this node's region.
isRevoked func(peerID string) bool
localRegion func() string
+ // peerRegion resolves a peer's gossip-observed region label for providers
+ // discovered via the registry probe, which carries no labels.
+ peerRegion func(peerID string) string
+ // Region gate seam (may be nil = enforcement unavailable, fail closed
+ // when a requirement exists): verifies the provider's
+ // control-plane-attested region facts before any request data is sent
+ // (see region_gate.go).
+ verifyPeerRegions func(ctx context.Context, peerID string, required []string) error
ttl time.Duration
mu sync.Mutex
@@ -133,6 +141,19 @@ func newOpenAIFacade(node *SamNode, egress http.Handler) *openAIFacade {
return node.revokedPeers != nil && node.revokedPeers.Contains(peerID)
},
localRegion: func() string { return node.config.Region },
+ peerRegion: func(peerID string) string {
+ if node.Discovery == nil {
+ return ""
+ }
+ return node.Discovery.PeerLabels(peerID)[api.LabelRegion]
+ },
+ verifyPeerRegions: func(ctx context.Context, peerID string, required []string) error {
+ pid, err := peer.Decode(peerID)
+ if err != nil {
+ return fmt.Errorf("invalid peer ID %q: %w", peerID, err)
+ }
+ return node.VerifyPeerRegions(ctx, pid, required)
+ },
}
}
@@ -381,6 +402,25 @@ func (f *openAIFacade) handleCompletions(w http.ResponseWriter, r *http.Request)
if p.peerID == "" {
f.serveLocal(aw, attempt, p.service)
} else {
+ // Labels ranked this provider; the region gate is the enforcement
+ // point: the provider's biscuit must attest the requirement before
+ // the request body leaves this node.
+ if len(requiredRegions) > 0 {
+ if f.verifyPeerRegions == nil {
+ recordFacadeRejection(reasonRegionUnattested)
+ writeOpenAIError(w, http.StatusServiceUnavailable, "region_unattested",
+ "region enforcement is unavailable on this node")
+ return
+ }
+ // No backoff on failure: the verdict is requirement-scoped,
+ // the provider stays eligible for unconstrained requests.
+ if err := f.verifyPeerRegions(r.Context(), p.peerID, requiredRegions); err != nil {
+ recordFacadeRejection(reasonRegionUnattested)
+ logger.Warnf("[OpenAIFacade] provider peer=%q service=%q failed region attestation for %v: %v; trying next",
+ p.peerID, p.service, requiredRegions, err)
+ continue
+ }
+ }
attempt.URL.Path = fmt.Sprintf("/sam/%s/%s/%s%s", p.peerID, api.ServiceTypeStringInference, p.service, r.URL.Path)
attempt.URL.RawPath = ""
f.forward.ServeHTTP(aw, attempt)
diff --git a/internal/node/openai_facade_test.go b/internal/node/openai_facade_test.go
index 1a79d0cf..d0991ff2 100644
--- a/internal/node/openai_facade_test.go
+++ b/internal/node/openai_facade_test.go
@@ -398,10 +398,12 @@ func TestRankProviders(t *testing.T) {
t.Run("region requirement is fail-closed and hierarchical", func(t *testing.T) {
f := newTestFacade()
- // Requiring the continent matches the finer country claim; the
- // unlabeled remote and unlabeled local must both be excluded.
+ // Requiring the continent matches the finer country claim and drops
+ // the known-mismatched remote. The unlabeled remote survives ranking
+ // (the region gate attests it before any bytes are sent); the
+ // unlabeled local has no gate and stays excluded.
got := f.rankProviders([]modelProvider{remoteEU, remoteUS, remoteNoLabel, local}, []string{"EU"})
- if len(got) != 1 || got[0].peerID != "peerEU" {
+ if len(got) != 2 || got[0].peerID != "peerX" || got[1].peerID != "peerEU" {
t.Fatalf("unexpected ranking under region requirement: %+v", got)
}
// A finer requirement never matches a coarser claim.
@@ -558,6 +560,11 @@ func TestFacade_Completions_RegionRequirement(t *testing.T) {
{peerID: "peerUS", service: "srvUS", region: "NA-US"},
}
}
+ var attested [][2]string
+ f.verifyPeerRegions = func(_ context.Context, peerID string, required []string) error {
+ attested = append(attested, [2]string{peerID, strings.Join(required, ",")})
+ return nil
+ }
var gotPath, gotRegionHeader string
f.forward = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
gotPath = r.URL.Path
@@ -575,6 +582,9 @@ func TestFacade_Completions_RegionRequirement(t *testing.T) {
if gotRegionHeader != "" {
t.Errorf("%s must not travel to the provider, got %q", api.HeaderSamRequiredRegion, gotRegionHeader)
}
+ if len(attested) != 1 || attested[0] != [2]string{"peerEU", "EU"} {
+ t.Errorf("expected one attestation for peerEU/EU, got %v", attested)
+ }
// No provider satisfies the requirement (valid code, no claimant).
req = httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(`{"model":"m1"}`))
@@ -595,6 +605,70 @@ func TestFacade_Completions_RegionRequirement(t *testing.T) {
}
}
+func TestFacade_Completions_RegionAttestation(t *testing.T) {
+ newRegionFacade := func() *openAIFacade {
+ f := newTestFacade()
+ f.viewProviders = func(model string) []modelProvider {
+ return []modelProvider{
+ {peerID: "peerEU1", service: "srv1", region: "EU-DE", active: 1},
+ {peerID: "peerEU2", service: "srv2", region: "EU-FR", active: 2},
+ }
+ }
+ return f
+ }
+
+ t.Run("unattested provider is skipped, attested one serves", func(t *testing.T) {
+ f := newRegionFacade()
+ f.verifyPeerRegions = func(_ context.Context, peerID string, _ []string) error {
+ if peerID == "peerEU1" {
+ return fmt.Errorf("no attested region")
+ }
+ return nil
+ }
+ var gotPath string
+ f.forward = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ gotPath = r.URL.Path
+ })
+
+ req := httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(`{"model":"m1"}`))
+ req.Header.Set(api.HeaderSamRequiredRegion, "EU")
+ rec := httptest.NewRecorder()
+ f.handleCompletions(rec, req)
+
+ if want := "/sam/peerEU2/inference/srv2/v1/chat/completions"; gotPath != want {
+ t.Errorf("forwarded path: got %q, want %q", gotPath, want)
+ }
+ })
+
+ t.Run("requirement with enforcement unavailable fails closed", func(t *testing.T) {
+ f := newRegionFacade() // verifyPeerRegions deliberately nil
+ f.forward = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ t.Error("request must not be forwarded without attestation")
+ })
+
+ req := httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(`{"model":"m1"}`))
+ req.Header.Set(api.HeaderSamRequiredRegion, "EU")
+ rec := httptest.NewRecorder()
+ f.handleCompletions(rec, req)
+
+ if rec.Code != http.StatusServiceUnavailable || !strings.Contains(rec.Body.String(), "region_unattested") {
+ t.Errorf("got status %d, body %s", rec.Code, rec.Body.String())
+ }
+ })
+
+ t.Run("no requirement never attests", func(t *testing.T) {
+ f := newRegionFacade()
+ f.verifyPeerRegions = func(_ context.Context, _ string, _ []string) error {
+ t.Error("attestation must not run without a requirement")
+ return nil
+ }
+ f.forward = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {})
+
+ req := httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(`{"model":"m1"}`))
+ f.handleCompletions(httptest.NewRecorder(), req)
+ })
+}
+
func TestAttemptWriter(t *testing.T) {
t.Run("retryable status swallowed", func(t *testing.T) {
rec := httptest.NewRecorder()
diff --git a/internal/node/openai_scorer.go b/internal/node/openai_scorer.go
index 45143ef1..a5a34999 100644
--- a/internal/node/openai_scorer.go
+++ b/internal/node/openai_scorer.go
@@ -31,6 +31,7 @@ const (
reasonPeerRevoked = "peer_revoked"
reasonProviderBackoff = "provider_backoff"
reasonRegionMismatch = "region_mismatch"
+ reasonRegionUnattested = "region_unattested"
reasonNoEligible = "no_eligible_provider"
reasonAttemptsExceeded = "attempts_exceeded"
)
@@ -77,13 +78,22 @@ func (f *openAIFacade) rankProviders(providers []modelProvider, requiredRegions
region := p.region
if p.peerID == "" && f.localRegion != nil {
region = f.localRegion()
+ } else if region == "" && p.peerID != "" && f.peerRegion != nil {
+ // Registry-probed providers carry no labels; the gossip view may
+ // still know the peer's claim.
+ region = f.peerRegion(p.peerID)
}
- // Region is fail-closed: a requirement never matches an unlabeled or
- // coarser-scoped provider. Labels are routing hints until
- // biscuit-attested.
- if len(requiredRegions) > 0 && !regionAllowed(requiredRegions, region) {
- recordFacadeRejection(reasonRegionMismatch)
- continue
+ // Labels are routing hints: a remote whose own claim mismatches the
+ // requirement is dropped early, but an unlabeled remote proceeds to
+ // the region gate, the authoritative fail-closed check on the
+ // provider's biscuit-attested region (see region_gate.go). Locals
+ // have no gate, so their declared region stays fail-closed here.
+ if len(requiredRegions) > 0 {
+ knownMismatch := region != "" && !regionAllowed(requiredRegions, region)
+ if knownMismatch || (p.peerID == "" && !regionAllowed(requiredRegions, region)) {
+ recordFacadeRejection(reasonRegionMismatch)
+ continue
+ }
}
if p.peerID == "" {
locals = append(locals, p)
diff --git a/internal/node/region_gate.go b/internal/node/region_gate.go
new file mode 100644
index 00000000..2964c518
--- /dev/null
+++ b/internal/node/region_gate.go
@@ -0,0 +1,155 @@
+// 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 node
+
+import (
+ "context"
+ "crypto/ed25519"
+ "fmt"
+ "strings"
+ "time"
+
+ "github.com/biscuit-auth/biscuit-go/v2"
+ "github.com/biscuit-auth/biscuit-go/v2/datalog"
+ "github.com/google/sam/api"
+ "github.com/google/sam/internal/identity"
+ "github.com/libp2p/go-libp2p/core/peer"
+ "github.com/libp2p/go-msgio"
+ "google.golang.org/protobuf/proto"
+)
+
+// The region gate is the consumer-side enforcement point for region
+// requirements: gossip labels only rank providers, this gate verifies the
+// provider's control-plane-attested region() facts (api.FactRegion) before
+// any request data leaves this node. Fail-closed: a provider that returns no
+// biscuit or lacks a matching fact is rejected.
+const (
+ regionGateCacheSize = 1024
+ // regionGateTTL bounds how long a positive verification verdict is
+ // reused before the provider's biscuit is fetched and checked again.
+ regionGateTTL = 5 * time.Minute
+ // regionGateDialTimeout bounds the biscuit-fetch handshake.
+ regionGateDialTimeout = 10 * time.Second
+)
+
+// VerifyPeerRegions ensures the peer holds a control-plane-attested region
+// satisfying any of the required regions (canonical, pre-validated). A nil
+// requirement passes without network traffic. Positive verdicts are cached.
+func (n *SamNode) VerifyPeerRegions(ctx context.Context, peerID peer.ID, required []string) error {
+ if len(required) == 0 {
+ return nil
+ }
+ key := peerID.String() + "|" + strings.Join(required, ",")
+ if until, ok := n.peerRegionGate.Get(key); ok && time.Now().Before(until) {
+ return nil
+ }
+
+ providerBiscuit, err := n.fetchPeerBiscuit(ctx, peerID)
+ if err != nil {
+ return fmt.Errorf("provider %s region unverifiable: %w", peerID, err)
+ }
+ if err := n.checkPeerRegions(providerBiscuit, peerID, required); err != nil {
+ return err
+ }
+
+ n.peerRegionGate.Add(key, time.Now().Add(regionGateTTL))
+ return nil
+}
+
+// checkPeerRegions verifies the provider's biscuit (control-plane signature,
+// expiry, binding to peerID) and evaluates the compiled region requirement
+// against its attested facts.
+func (n *SamNode) checkPeerRegions(providerBiscuit []byte, peerID peer.ID, required []string) error {
+ if len(providerBiscuit) == 0 {
+ return fmt.Errorf("provider %s returned no identity biscuit; cannot attest required region %v", peerID, required)
+ }
+
+ n.keysMu.RLock()
+ trustedKeys := make([]ed25519.PublicKey, 0, len(n.trustedKeys))
+ for _, tk := range n.trustedKeys {
+ trustedKeys = append(trustedKeys, tk.Key)
+ }
+ n.keysMu.RUnlock()
+ if len(trustedKeys) == 0 {
+ return fmt.Errorf("no trusted control plane keys loaded")
+ }
+
+ b, key, err := identity.VerifyBiscuitAndGetKey(providerBiscuit, peerID, trustedKeys, n.BiscuitTimeout)
+ if err != nil {
+ return fmt.Errorf("provider %s biscuit verification failed: %w", peerID, err)
+ }
+
+ var authOpts []biscuit.AuthorizerOption
+ if n.BiscuitTimeout > 0 {
+ authOpts = append(authOpts, biscuit.WithWorldOptions(datalog.WithMaxDuration(n.BiscuitTimeout)))
+ }
+ authorizer, err := b.Authorizer(key, authOpts...)
+ if err != nil {
+ return fmt.Errorf("provider %s authorizer instantiation failed: %w", peerID, err)
+ }
+ check, err := api.RegionCheck(required)
+ if err != nil {
+ return err
+ }
+ authorizer.AddCheck(check)
+ authorizer.AddPolicy(api.AllowIfTruePolicy)
+ if err := authorizer.Authorize(); err != nil {
+ return fmt.Errorf("provider %s has no attested region matching %v: %w", peerID, required, err)
+ }
+ return nil
+}
+
+// fetchPeerBiscuit obtains the peer's control-plane-minted identity via the
+// mutual auth handshake on AuthProtocolID, authenticating with our own.
+func (n *SamNode) fetchPeerBiscuit(ctx context.Context, peerID peer.ID) ([]byte, error) {
+ ourBiscuit := n.GetIdentity()
+ if ourBiscuit == nil {
+ return nil, fmt.Errorf("missing node identity")
+ }
+
+ dialCtx, cancel := context.WithTimeout(ctx, regionGateDialTimeout)
+ defer cancel()
+ s, err := n.Host.NewStream(dialCtx, peerID, api.AuthProtocolID)
+ if err != nil {
+ return nil, fmt.Errorf("failed to open auth stream: %w", err)
+ }
+ defer func() { _ = s.Close() }()
+ _ = s.SetDeadline(time.Now().Add(regionGateDialTimeout))
+
+ authBytes, err := proto.Marshal(&api.AuthFrame{Biscuit: ourBiscuit})
+ if err != nil {
+ return nil, fmt.Errorf("marshal auth frame: %w", err)
+ }
+ writer := msgio.NewVarintWriter(s)
+ if err := writer.WriteMsg(authBytes); err != nil {
+ return nil, fmt.Errorf("write auth frame: %w", err)
+ }
+
+ reader := msgio.NewVarintReaderSize(s, 1024*64)
+ msg, err := reader.ReadMsg()
+ if err != nil {
+ return nil, fmt.Errorf("read auth response (peer may predate mutual auth): %w", err)
+ }
+ defer reader.ReleaseMsg(msg)
+
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(msg, &resp); err != nil {
+ return nil, fmt.Errorf("invalid auth response: %w", err)
+ }
+ if !resp.Success {
+ return nil, fmt.Errorf("auth rejected: %s", resp.Error)
+ }
+ return resp.Biscuit, nil
+}
diff --git a/internal/node/region_gate_test.go b/internal/node/region_gate_test.go
new file mode 100644
index 00000000..079d8009
--- /dev/null
+++ b/internal/node/region_gate_test.go
@@ -0,0 +1,89 @@
+// 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 node
+
+import (
+ "crypto/ed25519"
+ "testing"
+ "time"
+
+ "github.com/google/sam/api"
+ "github.com/google/sam/internal/identity"
+ "github.com/libp2p/go-libp2p/core/peer"
+)
+
+func TestCheckPeerRegions(t *testing.T) {
+ cpPub, cpPriv, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ otherPub, otherPriv, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ _ = otherPub
+
+ providerPeer := peer.ID("provider-peer-id")
+ expiry := time.Now().Add(time.Hour)
+
+ mint := func(key ed25519.PrivateKey, p peer.ID, region string) []byte {
+ t.Helper()
+ b, err := identity.MintBootstrapBiscuitToken(key, p, api.RoleNode, expiry, nil, region)
+ if err != nil {
+ t.Fatalf("mint: %v", err)
+ }
+ return b
+ }
+
+ node := &SamNode{
+ trustedKeys: []TrustedKey{{Key: cpPub, ReceivedAt: time.Now()}},
+ BiscuitTimeout: 500 * time.Millisecond,
+ }
+
+ tests := []struct {
+ name string
+ biscuit []byte
+ required []string
+ expectErr bool
+ }{
+ {"finer claim satisfies coarser requirement", mint(cpPriv, providerPeer, "EU-DE"), []string{"EU"}, false},
+ {"exact match", mint(cpPriv, providerPeer, "EU-DE"), []string{"EU-DE"}, false},
+ {"any-of requirement", mint(cpPriv, providerPeer, "NA-US"), []string{"EU", "NA-US"}, false},
+ {"coarser claim fails finer requirement", mint(cpPriv, providerPeer, "EU"), []string{"EU-DE"}, true},
+ {"disjoint region fails", mint(cpPriv, providerPeer, "NA-US"), []string{"EU"}, true},
+ {"unattested token fails closed", mint(cpPriv, providerPeer, ""), []string{"EU"}, true},
+ {"empty biscuit fails closed", nil, []string{"EU"}, true},
+ {"untrusted signer fails", mint(otherPriv, providerPeer, "EU-DE"), []string{"EU"}, true},
+ {"token bound to another peer fails", mint(cpPriv, peer.ID("other-peer"), "EU-DE"), []string{"EU"}, true},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ err := node.checkPeerRegions(tt.biscuit, providerPeer, tt.required)
+ if tt.expectErr && err == nil {
+ t.Error("expected error, got nil")
+ } else if !tt.expectErr && err != nil {
+ t.Errorf("unexpected error: %v", err)
+ }
+ })
+ }
+
+ t.Run("no trusted keys fails closed", func(t *testing.T) {
+ bare := &SamNode{BiscuitTimeout: 500 * time.Millisecond}
+ if err := bare.checkPeerRegions(mint(cpPriv, providerPeer, "EU"), providerPeer, []string{"EU"}); err == nil {
+ t.Error("expected error, got nil")
+ }
+ })
+}
diff --git a/internal/storage/sql_store.go b/internal/storage/sql_store.go
index bba9da7a..5dbe2ccd 100644
--- a/internal/storage/sql_store.go
+++ b/internal/storage/sql_store.go
@@ -301,6 +301,17 @@ var migrations = []migration{
)`,
},
},
+ {
+ version: 5,
+ postgres: []string{
+ `ALTER TABLE nodes ADD COLUMN region VARCHAR(16) DEFAULT '' NOT NULL`,
+ `ALTER TABLE enrollment_requests ADD COLUMN region VARCHAR(16) DEFAULT '' NOT NULL`,
+ },
+ sqlite: []string{
+ `ALTER TABLE nodes ADD COLUMN region TEXT DEFAULT '' NOT NULL`,
+ `ALTER TABLE enrollment_requests ADD COLUMN region TEXT DEFAULT '' NOT NULL`,
+ },
+ },
}
func (s *SQLStore) initSchema() error {
@@ -525,16 +536,16 @@ func (s *SQLStore) EnrollNode(ctx context.Context, node *EnrolledNode) error {
var query string
if s.isPostgres() {
query = s.rebind(`
- INSERT INTO nodes (peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, enrolled_at, expires_at, banned)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, FALSE)
+ INSERT INTO nodes (peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, region, enrolled_at, expires_at, banned)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, FALSE)
ON CONFLICT (peer_id)
- DO UPDATE SET public_key = EXCLUDED.public_key, biscuit_token = EXCLUDED.biscuit_token, role = EXCLUDED.role, enrollment_type = EXCLUDED.enrollment_type, claims_json = EXCLUDED.claims_json, owner_id = EXCLUDED.owner_id, enrolled_at = EXCLUDED.enrolled_at, expires_at = EXCLUDED.expires_at`)
+ DO UPDATE SET public_key = EXCLUDED.public_key, biscuit_token = EXCLUDED.biscuit_token, role = EXCLUDED.role, enrollment_type = EXCLUDED.enrollment_type, claims_json = EXCLUDED.claims_json, owner_id = EXCLUDED.owner_id, region = EXCLUDED.region, enrolled_at = EXCLUDED.enrolled_at, expires_at = EXCLUDED.expires_at`)
} else {
query = s.rebind(`
- INSERT INTO nodes (peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, enrolled_at, expires_at, banned)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
+ INSERT INTO nodes (peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, region, enrolled_at, expires_at, banned)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)
ON CONFLICT (peer_id)
- DO UPDATE SET public_key = excluded.public_key, biscuit_token = excluded.biscuit_token, role = excluded.role, enrollment_type = excluded.enrollment_type, claims_json = excluded.claims_json, owner_id = excluded.owner_id, enrolled_at = excluded.enrolled_at, expires_at = excluded.expires_at`)
+ DO UPDATE SET public_key = excluded.public_key, biscuit_token = excluded.biscuit_token, role = excluded.role, enrollment_type = excluded.enrollment_type, claims_json = excluded.claims_json, owner_id = excluded.owner_id, region = excluded.region, enrolled_at = excluded.enrolled_at, expires_at = excluded.expires_at`)
}
ownerIDNull := sql.NullString{String: node.OwnerID, Valid: node.OwnerID != ""}
@@ -546,6 +557,7 @@ func (s *SQLStore) EnrollNode(ctx context.Context, node *EnrolledNode) error {
node.EnrollmentType,
node.ClaimsJSON,
ownerIDNull,
+ node.Region,
node.EnrolledAt.UnixMilli(),
node.ExpiresAt.UnixMilli(),
)
@@ -554,7 +566,7 @@ func (s *SQLStore) EnrollNode(ctx context.Context, node *EnrolledNode) error {
// GetNode implements Store.
func (s *SQLStore) GetNode(ctx context.Context, peerID string) (*EnrolledNode, error) {
- query := s.rebind(`SELECT peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, enrolled_at, expires_at, banned FROM nodes WHERE peer_id = ?`)
+ query := s.rebind(`SELECT peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, region, enrolled_at, expires_at, banned FROM nodes WHERE peer_id = ?`)
var node EnrolledNode
var claimsJSON, ownerID sql.NullString
var enrolledAtUnix, expiresAtUnix int64
@@ -566,6 +578,7 @@ func (s *SQLStore) GetNode(ctx context.Context, peerID string) (*EnrolledNode, e
&node.EnrollmentType,
&claimsJSON,
&ownerID,
+ &node.Region,
&enrolledAtUnix,
&expiresAtUnix,
&node.Banned,
@@ -885,8 +898,8 @@ func (s *SQLStore) IncrementBootstrapTokenUsage(ctx context.Context, id string)
// CreateEnrollmentRequest saves a new pending request.
func (s *SQLStore) CreateEnrollmentRequest(ctx context.Context, req *EnrollmentRequest) error {
- query := `INSERT INTO enrollment_requests (id, peer_id, public_key, token_id, status, biscuit_token, created_at, resolved_at, resolved_by)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+ query := `INSERT INTO enrollment_requests (id, peer_id, public_key, token_id, status, region, biscuit_token, created_at, resolved_at, resolved_by)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
var resAt sql.NullInt64
if req.ResolvedAt != nil {
resAt = sql.NullInt64{Int64: req.ResolvedAt.Unix(), Valid: true}
@@ -897,6 +910,7 @@ func (s *SQLStore) CreateEnrollmentRequest(ctx context.Context, req *EnrollmentR
req.PublicKey,
req.TokenID,
int(req.Status),
+ req.Region,
req.BiscuitToken,
req.CreatedAt.Unix(),
resAt,
@@ -910,14 +924,14 @@ func (s *SQLStore) CreateEnrollmentRequest(ctx context.Context, req *EnrollmentR
// GetEnrollmentRequest retrieves request by PeerID.
func (s *SQLStore) GetEnrollmentRequest(ctx context.Context, peerID string) (*EnrollmentRequest, error) {
- query := `SELECT id, peer_id, public_key, token_id, status, biscuit_token, created_at, resolved_at, resolved_by
+ query := `SELECT id, peer_id, public_key, token_id, status, region, biscuit_token, created_at, resolved_at, resolved_by
FROM enrollment_requests WHERE peer_id = ?`
return s.scanEnrollmentRequest(s.db.QueryRowContext(ctx, s.rebind(query), peerID))
}
// GetEnrollmentRequestByID retrieves request by UUID.
func (s *SQLStore) GetEnrollmentRequestByID(ctx context.Context, id string) (*EnrollmentRequest, error) {
- query := `SELECT id, peer_id, public_key, token_id, status, biscuit_token, created_at, resolved_at, resolved_by
+ query := `SELECT id, peer_id, public_key, token_id, status, region, biscuit_token, created_at, resolved_at, resolved_by
FROM enrollment_requests WHERE id = ?`
return s.scanEnrollmentRequest(s.db.QueryRowContext(ctx, s.rebind(query), id))
}
@@ -938,6 +952,7 @@ func (s *SQLStore) scanEnrollmentRequest(row scannable) (*EnrollmentRequest, err
&req.PublicKey,
&req.TokenID,
&statusVal,
+ &req.Region,
&req.BiscuitToken,
&created,
&resAt,
@@ -969,7 +984,7 @@ func (s *SQLStore) scanEnrollmentRequest(row scannable) (*EnrollmentRequest, err
// ListEnrollmentRequests retrieves all requests.
func (s *SQLStore) ListEnrollmentRequests(ctx context.Context) ([]EnrollmentRequest, error) {
- query := `SELECT id, peer_id, public_key, token_id, status, biscuit_token, created_at, resolved_at, resolved_by
+ query := `SELECT id, peer_id, public_key, token_id, status, region, biscuit_token, created_at, resolved_at, resolved_by
FROM enrollment_requests ORDER BY created_at DESC`
rows, err := s.db.QueryContext(ctx, s.rebind(query))
if err != nil {
@@ -1009,7 +1024,7 @@ func (s *SQLStore) UpdateEnrollmentRequest(ctx context.Context, id string, statu
// ListNodes retrieves all enrolled nodes.
func (s *SQLStore) ListNodes(ctx context.Context) ([]EnrolledNode, error) {
- query := s.rebind(`SELECT peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, enrolled_at, expires_at, banned FROM nodes ORDER BY enrolled_at DESC`)
+ query := s.rebind(`SELECT peer_id, public_key, biscuit_token, role, enrollment_type, claims_json, owner_id, region, enrolled_at, expires_at, banned FROM nodes ORDER BY enrolled_at DESC`)
rows, err := s.db.QueryContext(ctx, query)
if err != nil {
return nil, fmt.Errorf("failed to query nodes: %w", err)
@@ -1029,6 +1044,7 @@ func (s *SQLStore) ListNodes(ctx context.Context) ([]EnrolledNode, error) {
&node.EnrollmentType,
&claimsJSON,
&ownerID,
+ &node.Region,
&enrolledAtUnix,
&expiresAtUnix,
&node.Banned,
diff --git a/internal/storage/sql_store_test.go b/internal/storage/sql_store_test.go
index 2a166266..6237a0c2 100644
--- a/internal/storage/sql_store_test.go
+++ b/internal/storage/sql_store_test.go
@@ -170,6 +170,7 @@ func TestNodeEnrollmentOps(t *testing.T) {
Biscuit: biscuitData,
Role: "node",
EnrollmentType: "OIDC",
+ Region: "EU-DE",
EnrolledAt: time.Now(),
ExpiresAt: expiresAt,
}
@@ -186,6 +187,9 @@ func TestNodeEnrollmentOps(t *testing.T) {
if n.PeerID != peerID || !bytes.Equal(n.Biscuit, biscuitData) || n.Banned {
t.Fatalf("node data mismatch: %+v", n)
}
+ if n.Region != "EU-DE" {
+ t.Fatalf("node region mismatch: got %q, want EU-DE", n.Region)
+ }
// Ban node
err = store.SetNodeBanned(ctx, peerID, true)
@@ -398,6 +402,7 @@ func TestBootstrapTokensAndEnrollmentRequestsOps(t *testing.T) {
PublicKey: []byte("my-public-key-bytes"),
TokenID: tok.ID,
Status: api.EnrollmentStatus_ENROLLMENT_STATUS_PENDING,
+ Region: "NA-US",
BiscuitToken: nil,
CreatedAt: time.Now().Truncate(time.Second),
}
@@ -413,6 +418,9 @@ func TestBootstrapTokensAndEnrollmentRequestsOps(t *testing.T) {
if gotReq.ID != req.ID || gotReq.Status != req.Status || !bytes.Equal(gotReq.PublicKey, req.PublicKey) {
t.Errorf("retrieved request mismatch: %+v", gotReq)
}
+ if gotReq.Region != "NA-US" {
+ t.Errorf("retrieved request region mismatch: got %q, want NA-US", gotReq.Region)
+ }
gotReqByID, err := store.GetEnrollmentRequestByID(ctx, req.ID)
if err != nil {
diff --git a/internal/storage/storage.go b/internal/storage/storage.go
index cb122ded..252819c9 100644
--- a/internal/storage/storage.go
+++ b/internal/storage/storage.go
@@ -61,9 +61,12 @@ type EnrolledNode struct {
EnrollmentType string
ClaimsJSON string
OwnerID string
- EnrolledAt time.Time
- ExpiresAt time.Time
- Banned bool
+ // Region is the attested region claim minted into the node's biscuit;
+ // kept on the record so token refreshes re-mint it unchanged.
+ Region string
+ EnrolledAt time.Time
+ ExpiresAt time.Time
+ Banned bool
}
// BootstrapToken represents a pre-shared token for node enrollment.
@@ -81,11 +84,14 @@ type BootstrapToken struct {
// EnrollmentRequest represents a pending or resolved node registration request (CSR).
type EnrollmentRequest struct {
- ID string
- PeerID string
- PublicKey []byte
- TokenID string
- Status api.EnrollmentStatus
+ ID string
+ PeerID string
+ PublicKey []byte
+ TokenID string
+ Status api.EnrollmentStatus
+ // Region is the operator-declared region claim, surfaced to the
+ // approving admin; approval attests it into the minted biscuit.
+ Region string
BiscuitToken []byte
CreatedAt time.Time
ResolvedAt *time.Time
diff --git a/site/content/docs/user/node-configuration.md b/site/content/docs/user/node-configuration.md
index 7fd6face..1bd78044 100644
--- a/site/content/docs/user/node-configuration.md
+++ b/site/content/docs/user/node-configuration.md
@@ -77,3 +77,43 @@ You can further restrict access using the `attenuation` block. Local policies de
1. **`rules`**: Inject custom Datalog facts asserting local node state (e.g., `time($time)`).
2. **`policies`**: Add local restrictions (e.g., `deny if user("banned_user");`).
+
+---
+
+## 4. Regions & Data Sovereignty
+
+SAM supports jurisdiction constraints so a request never leaves a required region.
+
+### Declaring a region (provider)
+
+Start the node with its operator-declared region, using the hierarchical form `CONTINENT[-COUNTRY[-ZONE]]` (ISO 3166, e.g. `EU`, `EU-DE`, `NA-US-CA`):
+
+```bash
+sam-node run --region EU-DE ...
+```
+
+The region is declared at enrollment and **attested by the control plane**: for bootstrap enrollments the administrator sees the declared region on the pending request and approving it attests the claim. The control plane then mints one signed `region()` fact per hierarchy level into the node's Biscuit (`region("EU")`, `region("EU-DE")`), so a coarser requirement matches a finer claim, but never the reverse. An invalid region is rejected at enrollment; an empty one means no claim.
+
+### Requiring a region (consumer)
+
+On the sidecar's OpenAI-compatible endpoints, constrain a request with the `X-Sam-Required-Region` header (comma-separated, any-of):
+
+```bash
+curl http://localhost:8080/v1/chat/completions \
+ -H "Authorization: Bearer $SAM_API_TOKEN" \
+ -H "X-Sam-Required-Region: EU" \
+ -d '{"model":"test-model","messages":[{"role":"user","content":"hi"}]}'
+```
+
+Enforcement is fail-closed and cryptographic: gossiped region labels only rank candidate providers, and before any request data leaves your node the sidecar verifies the provider's control-plane-signed Biscuit and checks its attested `region()` facts. Providers that return no identity or lack a matching fact are rejected.
+
+### Restricting callers by region (provider)
+
+Because every enrolled node's token carries its attested region facts, a provider can require callers to be in a region with a single local check in its `attenuation` block:
+
+```yaml
+attenuation:
+ checks:
+ - 'check if region("EU");'
+```
+
diff --git a/tests/integration/minimal_helpers_test.go b/tests/integration/minimal_helpers_test.go
index 7c15a2f0..b74dffbd 100644
--- a/tests/integration/minimal_helpers_test.go
+++ b/tests/integration/minimal_helpers_test.go
@@ -265,7 +265,7 @@ func startMockRouter(t *testing.T) (peer.ID, string) {
}
resp := &api.EnrollResponse{
- BiscuitToken: createMockBiscuitToken(t, req.PeerId, priv, api.RoleNode),
+ BiscuitToken: createMockBiscuitToken(t, req.PeerId, priv, api.RoleNode, req.Region),
ControlPlanePublicKey: pub,
RouterAddresses: []string{h.Addrs()[0].String() + "/p2p/" + h.ID().String()},
}
@@ -365,7 +365,7 @@ func startMockRouterWithOIDC(t *testing.T, oidcIssuerURL string) (peer.ID, strin
}
resp := &api.EnrollResponse{
- BiscuitToken: createMockBiscuitToken(t, req.PeerId, priv, api.RoleNode),
+ BiscuitToken: createMockBiscuitToken(t, req.PeerId, priv, api.RoleNode, req.Region),
ControlPlanePublicKey: pub,
RouterAddresses: []string{h.Addrs()[0].String() + "/p2p/" + h.ID().String()},
}
@@ -390,13 +390,21 @@ func startMockRouterWithOIDC(t *testing.T, oidcIssuerURL string) (peer.ID, strin
return h.ID(), httpServer.URL
}
-func createMockBiscuitToken(t *testing.T, peerID string, priv ed25519.PrivateKey, role string) []byte {
+func createMockBiscuitToken(t *testing.T, peerID string, priv ed25519.PrivateKey, role string, region ...string) []byte {
builder := biscuit.NewBuilder(priv)
err := builder.AddAuthorityFact(biscuit.Fact{Predicate: biscuit.Predicate{Name: "target_unrestricted"}})
if err != nil {
t.Fatalf("failed to add target_unrestricted: %v", err)
}
+ for _, r := range region {
+ for _, fact := range api.RegionFacts(r) {
+ if err := builder.AddAuthorityFact(fact); err != nil {
+ t.Fatalf("failed to add region fact: %v", err)
+ }
+ }
+ }
+
err = builder.AddAuthorityFact(biscuit.Fact{Predicate: biscuit.Predicate{
Name: api.FactExpiration,
IDs: []biscuit.Term{biscuit.Date(time.Now().Add(1 * time.Hour))},
diff --git a/tests/integration/openai_facade_test.go b/tests/integration/openai_facade_test.go
index ddd9c852..815ee6ee 100644
--- a/tests/integration/openai_facade_test.go
+++ b/tests/integration/openai_facade_test.go
@@ -133,6 +133,45 @@ func TestOpenAIFacadeCUJ(t *testing.T) {
t.Fatalf("unexpected completion: %s", string(body))
}
+ // CUJ step 2b: a region requirement is enforced end to end — the provider
+ // declared "eu" at enrollment, so its biscuit carries attested region
+ // facts and the consumer's region gate admits it. The region label
+ // arrives via interest-scoped gossip, so poll until it propagates.
+ deadline := time.Now().Add(30 * time.Second)
+ for {
+ req, _ = http.NewRequest("POST", "http://"+apiAddrB+"/v1/chat/completions", strings.NewReader(reqBody))
+ req.Header.Set("Authorization", "Bearer "+apiToken)
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set(api.HeaderSamRequiredRegion, "EU")
+ respEU, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatalf("region-constrained completion request failed: %v", err)
+ }
+ euBody, _ := io.ReadAll(respEU.Body)
+ _ = respEU.Body.Close()
+ if respEU.StatusCode == http.StatusOK {
+ break
+ }
+ if time.Now().After(deadline) {
+ t.Fatalf("region-constrained completion status: got %d, body: %s", respEU.StatusCode, string(euBody))
+ }
+ time.Sleep(200 * time.Millisecond)
+ }
+
+ // A finer requirement than the provider's claim fails closed.
+ req, _ = http.NewRequest("POST", "http://"+apiAddrB+"/v1/chat/completions", strings.NewReader(reqBody))
+ req.Header.Set("Authorization", "Bearer "+apiToken)
+ req.Header.Set(api.HeaderSamRequiredRegion, "EU-DE")
+ respDE, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatalf("finer-region completion request failed: %v", err)
+ }
+ defer func() { _ = respDE.Body.Close() }()
+ deBody, _ := io.ReadAll(respDE.Body)
+ if respDE.StatusCode != http.StatusServiceUnavailable {
+ t.Fatalf("finer region must fail closed: got %d, body: %s", respDE.StatusCode, string(deBody))
+ }
+
// CUJ step 3: unknown models fail with an OpenAI-style error.
req, _ = http.NewRequest("POST", "http://"+apiAddrB+"/v1/chat/completions",
strings.NewReader(`{"model":"no-such-model","messages":[]}`))