Skip to content

Agent Mesh

Encode exact policy grants as Datalog Sets to fix fact-count scaling

Antonio Ojea7f5965ab3eaf
diff --git a/api/datalog.go b/api/datalog.go
index c12303b7..43255706 100644
--- a/api/datalog.go
+++ b/api/datalog.go
@@ -17,6 +17,7 @@ package api
import (
"fmt"
"maps"
+ "sort"
"strings"
"github.com/biscuit-auth/biscuit-go/v2"
@@ -130,6 +131,13 @@ const (
// Example Datalog: allow if service("mcp", "calculator"), granted_service_exact("mcp", "calculator")
FactGrantedServiceExact = "granted_service_exact"
+ // FactGrantedServiceSet allows access to a Set of exact service names under a specific service
+ // type. This lets many exact grants for the same type be carried as a single Datalog fact instead
+ // of one fact per entry, which keeps token/world fact counts flat regardless of list length.
+ // Contains: biscuit.String(serviceType), biscuit.Set of biscuit.String(serviceName)
+ // Example Datalog: allow if service("mcp", "calculator"), granted_service_set("mcp", $set), $set.contains("calculator")
+ FactGrantedServiceSet = "granted_service_set"
+
// FactGrantedTargetAllTypes allows target access to all network targets (unrestricted).
// Contains: (no terms)
FactGrantedTargetAllTypes = "granted_target_all_types"
@@ -155,6 +163,12 @@ const (
// Contains: (no terms)
FactGrantedTargetAllFacts = "granted_target_all_facts"
+ // FactGrantedTargetSet allows target access to a Set of exact values for a specific fact name.
+ // This lets many exact target grants for the same fact name be carried as a single Datalog fact
+ // instead of one fact per entry, which keeps token/world fact counts flat regardless of list length.
+ // Contains: biscuit.String(factName), biscuit.Set of biscuit.String(factValue)
+ FactGrantedTargetSet = "granted_target_set"
+
// FactConnectionPeerID defines the actual PeerID of the remote peer making the connection.
// Contains: biscuit.String(connectionPeerID)
// Example Datalog: check if client_peer_id($id), connection_peer_id($id)
@@ -233,6 +247,10 @@ func init() {
// that perfectly matches both the protocol type (e.g. "mcp") and the service name (e.g. "calculator").
fmt.Sprintf(`allow if %s($type, $name), %s($type, $name)`, FactService, FactGrantedServiceExact),
+ // Exact Set Match: Allows access if the token possesses a granted_service_set fact for the given
+ // protocol type whose Set of names contains the requested service name.
+ fmt.Sprintf(`allow if %s($type, $name), %s($type, $set), $set.contains($name)`, FactService, FactGrantedServiceSet),
+
// Prefix Match: Allows access if the token possesses a granted_service_prefix fact
// for the given protocol type, and the requested service name starts with that prefix.
fmt.Sprintf(`allow if %s($type, $name), %s($type, $prefix), $name.starts_with($prefix)`, FactService, FactGrantedServicePrefix),
@@ -264,6 +282,10 @@ func init() {
// Exact Match: Derives allow_network_target if the token has a granted_target_exact fact matching a target_fact exactly.
fmt.Sprintf(`%s($fact, $val) <- %s($fact, $val), %s($fact, $val)`, FactAllowNetworkTarget, FactTargetFact, FactGrantedTargetExact),
+ // Exact Set Match: Derives allow_network_target if the token has a granted_target_set fact for the
+ // given fact name whose Set of values contains the target_fact value.
+ fmt.Sprintf(`%s($fact, $val) <- %s($fact, $val), %s($fact, $set), $set.contains($val)`, FactAllowNetworkTarget, FactTargetFact, FactGrantedTargetSet),
+
// Prefix Match: Derives allow_network_target if the token has a granted_target_prefix fact and the target_fact value starts with that prefix.
fmt.Sprintf(`%s($fact, $val) <- %s($fact, $val), %s($fact, $prefix), $val.starts_with($prefix)`, FactAllowNetworkTarget, FactTargetFact, FactGrantedTargetPrefix),
@@ -397,3 +419,92 @@ func BuildTargetDatalogFact(targetStr string) biscuit.Fact {
IDs: []biscuit.Term{biscuit.String(tFact), biscuit.String(tVal)},
}}
}
+
+// 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) {
+ svcType, svcName = ParseServiceTarget(serviceStr)
+ if svcType == "*" && svcName == "*" {
+ return svcType, svcName, false
+ }
+ if svcName == "*" || strings.HasPrefix(svcName, "*.") || strings.HasSuffix(svcName, ".*") {
+ return svcType, svcName, false
+ }
+ return svcType, svcName, true
+}
+
+// isExactTarget reports whether targetStr resolves to a plain exact-match grant, as opposed to a
+// wildcard/prefix/suffix pattern which already collapses to a single, cheap fact via BuildTargetDatalogFact.
+func isExactTarget(targetStr string) (tFact, tVal string, exact bool) {
+ tFact, tVal = ParseServiceTarget(targetStr)
+ if tFact == "" {
+ tFact = "node"
+ }
+ if tFact == "*" && tVal == "*" {
+ return tFact, tVal, false
+ }
+ if tVal == "*" || strings.HasPrefix(tVal, "*.") || strings.HasSuffix(tVal, ".*") {
+ return tFact, tVal, false
+ }
+ return tFact, tVal, true
+}
+
+// BuildServiceDatalogFacts translates a list of service patterns into a minimal set of Datalog facts.
+// Exact-match entries are grouped by service type into a single granted_service_set fact each, so
+// token/world fact counts stay flat regardless of how many exact services a role grants. Wildcard,
+// prefix and suffix entries keep their existing one-fact-per-entry representation via
+// BuildServiceDatalogFact, since those already collapse to a single fact per entry.
+func BuildServiceDatalogFacts(services []string) []biscuit.Fact {
+ facts := make([]biscuit.Fact, 0, len(services))
+ exactByType := make(map[string]biscuit.Set)
+ var types []string
+ for _, svc := range services {
+ svcType, svcName, exact := isExactService(svc)
+ if !exact {
+ facts = append(facts, BuildServiceDatalogFact(svc))
+ continue
+ }
+ if _, ok := exactByType[svcType]; !ok {
+ types = append(types, svcType)
+ }
+ exactByType[svcType] = append(exactByType[svcType], biscuit.String(svcName))
+ }
+ sort.Strings(types)
+ for _, svcType := range types {
+ facts = append(facts, biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: FactGrantedServiceSet,
+ IDs: []biscuit.Term{biscuit.String(svcType), exactByType[svcType]},
+ }})
+ }
+ return facts
+}
+
+// BuildTargetDatalogFacts translates a list of target patterns into a minimal set of Datalog facts.
+// Exact-match entries are grouped by fact name into a single granted_target_set fact each, so
+// token/world fact counts stay flat regardless of how many exact targets a role grants. Wildcard,
+// prefix and suffix entries keep their existing one-fact-per-entry representation via
+// BuildTargetDatalogFact, since those already collapse to a single fact per entry.
+func BuildTargetDatalogFacts(targets []string) []biscuit.Fact {
+ facts := make([]biscuit.Fact, 0, len(targets))
+ exactByFact := make(map[string]biscuit.Set)
+ var factNames []string
+ for _, t := range targets {
+ tFact, tVal, exact := isExactTarget(t)
+ if !exact {
+ facts = append(facts, BuildTargetDatalogFact(t))
+ continue
+ }
+ if _, ok := exactByFact[tFact]; !ok {
+ factNames = append(factNames, tFact)
+ }
+ exactByFact[tFact] = append(exactByFact[tFact], biscuit.String(tVal))
+ }
+ sort.Strings(factNames)
+ for _, tFact := range factNames {
+ facts = append(facts, biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: FactGrantedTargetSet,
+ IDs: []biscuit.Term{biscuit.String(tFact), exactByFact[tFact]},
+ }})
+ }
+ return facts
+}
diff --git a/api/datalog_test.go b/api/datalog_test.go
index c7366d34..c3b299e5 100644
--- a/api/datalog_test.go
+++ b/api/datalog_test.go
@@ -18,6 +18,8 @@ import (
"crypto/ed25519"
"crypto/rand"
reflect "reflect"
+ "slices"
+ "sort"
"testing"
"time"
@@ -443,3 +445,114 @@ func TestBuildTargetDatalogFact(t *testing.T) {
}
}
}
+
+func factStrings(facts []biscuit.Fact) []string {
+ strs := make([]string, len(facts))
+ for i, f := range facts {
+ strs[i] = f.String()
+ }
+ sort.Strings(strs)
+ return strs
+}
+
+func TestBuildServiceDatalogFacts(t *testing.T) {
+ tests := []struct {
+ name string
+ input []string
+ expected []string
+ }{
+ {
+ name: "single exact entry aggregates into one Set fact",
+ input: []string{"mcp://calculator"},
+ expected: []string{`granted_service_set("mcp", ["calculator"])`},
+ },
+ {
+ name: "multiple exact entries of the same type aggregate into one Set fact",
+ input: []string{"mcp://calculator", "mcp://jupyter"},
+ expected: []string{
+ `granted_service_set("mcp", ["calculator", "jupyter"])`,
+ },
+ },
+ {
+ name: "exact entries of different types produce one Set fact per type",
+ input: []string{"mcp://calculator", "inference://model-a"},
+ expected: []string{
+ `granted_service_set("inference", ["model-a"])`,
+ `granted_service_set("mcp", ["calculator"])`,
+ },
+ },
+ {
+ name: "wildcard, prefix and suffix entries keep the existing single-fact representation",
+ input: []string{"*", "mcp://*", "mcp://*.local", "mcp://calc.*", "mcp://calculator"},
+ expected: []string{
+ BuildServiceDatalogFact("*").String(),
+ BuildServiceDatalogFact("mcp://*").String(),
+ BuildServiceDatalogFact("mcp://*.local").String(),
+ BuildServiceDatalogFact("mcp://calc.*").String(),
+ `granted_service_set("mcp", ["calculator"])`,
+ },
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := factStrings(BuildServiceDatalogFacts(tt.input))
+ want := append([]string(nil), tt.expected...)
+ sort.Strings(want)
+ if !slices.Equal(got, want) {
+ t.Errorf("BuildServiceDatalogFacts(%v) = %v, want %v", tt.input, got, want)
+ }
+ })
+ }
+}
+
+func TestBuildTargetDatalogFacts(t *testing.T) {
+ tests := []struct {
+ name string
+ input []string
+ expected []string
+ }{
+ {
+ name: "single exact entry aggregates into one Set fact",
+ input: []string{"group:backend"},
+ expected: []string{`granted_target_set("group", ["backend"])`},
+ },
+ {
+ name: "multiple exact entries of the same fact name aggregate into one Set fact",
+ input: []string{"node:peer-abc", "legacy-peer"},
+ expected: []string{
+ `granted_target_set("node", ["legacy-peer", "peer-abc"])`,
+ },
+ },
+ {
+ name: "exact entries of different fact names produce one Set fact each",
+ input: []string{"node:peer-abc", "group:backend"},
+ expected: []string{
+ `granted_target_set("group", ["backend"])`,
+ `granted_target_set("node", ["peer-abc"])`,
+ },
+ },
+ {
+ name: "wildcard, prefix and suffix entries keep the existing single-fact representation",
+ input: []string{"*", "user:*", "group:*.internal", "group:backend.*", "group:backend"},
+ expected: []string{
+ BuildTargetDatalogFact("*").String(),
+ BuildTargetDatalogFact("user:*").String(),
+ BuildTargetDatalogFact("group:*.internal").String(),
+ BuildTargetDatalogFact("group:backend.*").String(),
+ `granted_target_set("group", ["backend"])`,
+ },
+ },
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := factStrings(BuildTargetDatalogFacts(tt.input))
+ want := append([]string(nil), tt.expected...)
+ sort.Strings(want)
+ if !slices.Equal(got, want) {
+ t.Errorf("BuildTargetDatalogFacts(%v) = %v, want %v", tt.input, got, want)
+ }
+ })
+ }
+}
diff --git a/internal/controlplane/policy_scale_test.go b/internal/controlplane/policy_scale_test.go
index edc05582..451c7be5 100644
--- a/internal/controlplane/policy_scale_test.go
+++ b/internal/controlplane/policy_scale_test.go
@@ -132,3 +132,73 @@ func TestPolicyScale(t *testing.T) {
n, validateDur, resolveDur, mintDur, len(biscuitBytes), authorizeDur, total)
}
}
+
+// TestPolicyScaleSetEncoding demonstrates that aggregating a role's exact
+// AllowedServices/AllowedTargets grants into Set-valued Datalog facts (one
+// fact per service type / target fact name, instead of one fact per entry)
+// keeps minting and authorization working far beyond what previously was a
+// hard ceiling for a single role granting many exact entries.
+//
+// Before the Set-based encoding, a single role with a few hundred exact
+// service/target entries could, by itself, exhaust the biscuit-go
+// authorizer's default 1000-fact world limit (see TestPolicyScale). With
+// Set-based encoding the same role contributes a small, constant number of
+// facts (one granted_service_set + one granted_target_set) regardless of how
+// many exact entries it grants. Probe further with e.g.:
+//
+// SAM_POLICY_SCALE_SET_MAX=20000 go test ./internal/controlplane -run TestPolicyScaleSetEncoding -v
+func TestPolicyScaleSetEncoding(t *testing.T) {
+ entryTiers := []int{10, 100, 2000}
+ if extra := os.Getenv("SAM_POLICY_SCALE_SET_MAX"); extra != "" {
+ n, err := strconv.Atoi(extra)
+ if err != nil {
+ t.Fatalf("invalid SAM_POLICY_SCALE_SET_MAX=%q: %v", extra, err)
+ }
+ entryTiers = append(entryTiers, n)
+ }
+
+ pub, priv, err := ed25519.GenerateKey(rand.Reader)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ nodeKey, _, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
+ if err != nil {
+ t.Fatal(err)
+ }
+ nodePeer, err := peer.IDFromPrivateKey(nodeKey)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ for _, n := range entryTiers {
+ services := make([]string, 0, n)
+ targets := make([]string, 0, n)
+ for i := 0; i < n; i++ {
+ services = append(services, fmt.Sprintf("mcp://svc-%d.example", i))
+ targets = append(targets, fmt.Sprintf("group:team-%d", i))
+ }
+ roles := []*api.PolicyRole{{
+ Name: "bulk-role",
+ AllowedServices: services,
+ AllowedTargets: targets,
+ }}
+
+ claims := jwt.MapClaims{}
+ start := time.Now()
+ 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)
+ }
+
+ start = time.Now()
+ _, authErr := identity.VerifyBiscuit(biscuitBytes, nodePeer, []ed25519.PublicKey{pub}, 5*time.Second)
+ authorizeDur := time.Since(start)
+ if authErr != nil {
+ t.Fatalf("authorize failed at n=%d exact entries granted by a single role (Set-based encoding should keep this well below the fact limit): %v", n, authErr)
+ }
+
+ t.Logf("exact_entries_per_role=%-6d mint=%-12s biscuit_size=%-10dB authorize=%-12s", n, mintDur, len(biscuitBytes), authorizeDur)
+ }
+}
diff --git a/internal/identity/biscuit.go b/internal/identity/biscuit.go
index a728a177..9ad8aee2 100644
--- a/internal/identity/biscuit.go
+++ b/internal/identity/biscuit.go
@@ -127,18 +127,20 @@ func mintBiscuit(signingKey ed25519.PrivateKey, remotePeer peer.ID, roles []stri
if pr, ok := rolesMap[role]; ok {
if len(pr.AllowedServices) > 0 {
hasServices = true
- for _, svc := range pr.AllowedServices {
- if err := addFact(api.BuildServiceDatalogFact(svc)); err != nil {
- errs = append(errs, fmt.Errorf("failed to add service fact %q for role %s: %w", svc, role, err))
+ // Exact-match entries are grouped into a single Set fact per service type so token/world
+ // fact counts stay flat regardless of how many exact services a role grants.
+ for _, fact := range api.BuildServiceDatalogFacts(pr.AllowedServices) {
+ if err := addFact(fact); err != nil {
+ errs = append(errs, fmt.Errorf("failed to add service fact for role %s: %w", role, err))
}
}
}
if len(pr.AllowedTargets) > 0 {
hasTargets = true
- for _, target := range pr.AllowedTargets {
- if err := addFact(api.BuildTargetDatalogFact(target)); err != nil {
- errs = append(errs, fmt.Errorf("failed to add target fact %q for role %s: %w", target, role, err))
+ for _, fact := range api.BuildTargetDatalogFacts(pr.AllowedTargets) {
+ if err := addFact(fact); err != nil {
+ errs = append(errs, fmt.Errorf("failed to add target fact for role %s: %w", role, err))
}
}
}
diff --git a/internal/node/middleware_test.go b/internal/node/middleware_test.go
index 7b0882f8..73256744 100644
--- a/internal/node/middleware_test.go
+++ b/internal/node/middleware_test.go
@@ -191,6 +191,28 @@ func TestBaselineRules(t *testing.T) {
target: "mcp://test_tool",
expectSuccess: true,
},
+ {
+ name: "Baseline Rule 1b: Exact Set Match",
+ mintToken: func(t *testing.T, builder biscuit.Builder) {
+ factStr := fmt.Sprintf(`%s("mcp", ["other_tool", "test_tool"])`, api.FactGrantedServiceSet)
+ fact, _ := parser.FromStringFact(factStr)
+ _ = builder.AddAuthorityFact(fact)
+ },
+ protocol: "test_tool",
+ target: "mcp://test_tool",
+ expectSuccess: true,
+ },
+ {
+ name: "Baseline Rule 1c: Exact Set Rejection for non-member",
+ mintToken: func(t *testing.T, builder biscuit.Builder) {
+ factStr := fmt.Sprintf(`%s("mcp", ["other_tool"])`, api.FactGrantedServiceSet)
+ fact, _ := parser.FromStringFact(factStr)
+ _ = builder.AddAuthorityFact(fact)
+ },
+ protocol: "test_tool",
+ target: "mcp://test_tool",
+ expectSuccess: false,
+ },
{
name: "Baseline Rule 2: Global Wildcard",
mintToken: func(t *testing.T, builder biscuit.Builder) {
@@ -637,6 +659,38 @@ func TestMiddlewareTargetChecks(t *testing.T) {
},
expectSuccess: true,
},
+ {
+ name: "Target Check: Allowed by Group Set Fact",
+ mintToken: func(t *testing.T, builder biscuit.Builder) {
+ _ = builder.AddAuthorityFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactGrantedTargetSet,
+ IDs: []biscuit.Term{biscuit.String("group"), biscuit.Set{biscuit.String("eng"), biscuit.String("sales")}},
+ }})
+ },
+ req: RequestContext{
+ PeerID: dummyPeer,
+ Protocol: "test_tool",
+ Target: "mcp://test_tool",
+ Group: "eng",
+ },
+ expectSuccess: true,
+ },
+ {
+ name: "Target Check: Rejected by Group Set Fact for non-member",
+ mintToken: func(t *testing.T, builder biscuit.Builder) {
+ _ = builder.AddAuthorityFact(biscuit.Fact{Predicate: biscuit.Predicate{
+ Name: api.FactGrantedTargetSet,
+ IDs: []biscuit.Term{biscuit.String("group"), biscuit.Set{biscuit.String("sales")}},
+ }})
+ },
+ req: RequestContext{
+ PeerID: dummyPeer,
+ Protocol: "test_tool",
+ Target: "mcp://test_tool",
+ Group: "eng",
+ },
+ expectSuccess: false,
+ },
}
for _, tt := range tests {
diff --git a/internal/node/policy.go b/internal/node/policy.go
index f80d4c3d..effb6db3 100644
--- a/internal/node/policy.go
+++ b/internal/node/policy.go
@@ -49,8 +49,7 @@ func BuildPolicyRules(roles []*api.PolicyRole, bindings []*api.PolicyBinding) []
}
roleName := role.Name
- for _, svc := range role.AllowedServices {
- fact := api.BuildServiceDatalogFact(svc)
+ for _, fact := range api.BuildServiceDatalogFacts(role.AllowedServices) {
rules = append(rules, biscuit.Rule{
Head: fact.Predicate,
Body: []biscuit.Predicate{
@@ -93,11 +92,13 @@ func BuildPolicyRules(roles []*api.PolicyRole, bindings []*api.PolicyBinding) []
})
}
+ nonWildcardTargets := make([]string, 0, len(role.AllowedTargets))
for _, t := range role.AllowedTargets {
- if t == "*" {
- continue
+ if t != "*" {
+ nonWildcardTargets = append(nonWildcardTargets, t)
}
- fact := api.BuildTargetDatalogFact(t)
+ }
+ for _, fact := range api.BuildTargetDatalogFacts(nonWildcardTargets) {
rules = append(rules, biscuit.Rule{
Head: fact.Predicate,
Body: []biscuit.Predicate{
diff --git a/internal/node/policy_test.go b/internal/node/policy_test.go
index 67d35a1f..4672f83f 100644
--- a/internal/node/policy_test.go
+++ b/internal/node/policy_test.go
@@ -42,20 +42,19 @@ func TestBuildPolicyRules(t *testing.T) {
rules := BuildPolicyRules(roles, bindings)
expectedStrings := map[string]bool{
- "role(\"test-role\")": false,
- "role(\"test-role\") <- user(\"alice\")": false,
- "granted_service_all_types() <- role(\"test-role\")": false,
- "granted_service_all(\"mcp\") <- role(\"test-role\")": false,
- "granted_service_suffix(\"mcp\", \".suffix\") <- role(\"test-role\")": false,
- "granted_service_prefix(\"mcp\", \"prefix.\") <- role(\"test-role\")": false,
- "granted_service_exact(\"mcp\", \"exact\") <- role(\"test-role\")": false,
- "target_unrestricted() <- role(\"test-role\")": false,
- "target_restricted() <- role(\"test-role\")": false,
- "granted_target_exact(\"node\", \"peer-abc\") <- role(\"test-role\")": false,
- "granted_target_exact(\"custom-fact\", \"custom-val\") <- role(\"test-role\")": false,
- "granted_target_exact(\"node\", \"legacy-peer\") <- role(\"test-role\")": false,
- "custom_rule($x) <- fact($x)": false,
- "custom_fact(\"hello\")": false,
+ "role(\"test-role\")": false,
+ "role(\"test-role\") <- user(\"alice\")": false,
+ "granted_service_all_types() <- role(\"test-role\")": false,
+ "granted_service_all(\"mcp\") <- role(\"test-role\")": false,
+ "granted_service_suffix(\"mcp\", \".suffix\") <- role(\"test-role\")": false,
+ "granted_service_prefix(\"mcp\", \"prefix.\") <- role(\"test-role\")": false,
+ "granted_service_set(\"mcp\", [\"exact\"]) <- role(\"test-role\")": false,
+ "target_unrestricted() <- role(\"test-role\")": false,
+ "target_restricted() <- role(\"test-role\")": false,
+ "granted_target_set(\"node\", [\"legacy-peer\", \"peer-abc\"]) <- role(\"test-role\")": false,
+ "granted_target_set(\"custom-fact\", [\"custom-val\"]) <- role(\"test-role\")": false,
+ "custom_rule($x) <- fact($x)": false,
+ "custom_fact(\"hello\")": false,
}
for _, rule := range rules {