Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs, tests: one policy shape everywhere, and drop the flag that no longer exists
Antonio Ojea83db1d5dcda2
diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.mdindex dfb3ad6e..1bc4ff82 100644--- a/site/content/docs/development/policy.md+++ b/site/content/docs/development/policy.md@@ -3,7 +3,7 @@ title: "SAM Policy & Authorization Reference"linkTitle: "SAM Policy & Authorization Reference"---SAM uses a decentralized authorization model powered by [Biscuit](https://www.biscuitsec.org/).-The `sam-control-plane` authenticates users via OIDC and injects **Facts** into their token based on `policies.yaml`. The `sam-node` operates offline, evaluating the token against baseline rules and optional local attenuation policies.+The `sam-control-plane` authenticates users via OIDC and injects **Facts** into their token based on the mesh policy held in its database. The `sam-node` operates offline, evaluating the token against baseline rules and optional local attenuation policies.> [!IMPORTANT]> **Default-Deny Security Posture**diff --git a/site/content/docs/manifests/sam-control-plane.yaml b/site/content/docs/manifests/sam-control-plane.yamlindex 02a816e7..ca6bebf6 100644--- a/site/content/docs/manifests/sam-control-plane.yaml+++ b/site/content/docs/manifests/sam-control-plane.yaml@@ -19,6 +19,8 @@ metadata:type: OpaquestringData:SAM_OIDC_ISSUER: "http://mock-oidc:18080"+ # Authenticates the policy admin API. Replace before using this outside a demo.+ SAM_ADMIN_TOKEN: "replace-me-with-a-generated-token"---apiVersion: apps/v1kind: Deployment@@ -46,7 +48,6 @@ spec:- "--db-dsn=/data/control-plane.db"- "--issuer=$(SAM_OIDC_ISSUER)"- "--allowed-audiences=sam-mesh-audience,sam-control-plane-audience"- - "--policy-file=/etc/sam/policies/policies.yaml"- "--insecure-skip-tls-verify"ports:- containerPort: 8080@@ -57,16 +58,15 @@ spec:secretKeyRef:name: sam-control-plane-secretkey: SAM_OIDC_ISSUER+ - name: SAM_ADMIN_TOKEN+ valueFrom:+ secretKeyRef:+ name: sam-control-plane-secret+ key: SAM_ADMIN_TOKENvolumeMounts:- - name: policies-volume- mountPath: /etc/sam/policies- readOnly: true- name: db-datamountPath: /datavolumes:- - name: policies-volume- configMap:- name: sam-control-plane-policies- name: db-dataemptyDir: {}---@@ -84,19 +84,40 @@ spec:targetPort: 8080name: http----apiVersion: v1-kind: ConfigMap+# The control plane starts default closed: it has no policy until one is posted.+# Seed it over the admin API, which is the only way policy is ever set.+apiVersion: batch/v1+kind: Jobmetadata:- name: sam-control-plane-policies-data:- policies.yaml: |- version: "v1alpha1"- bindings:- - members: ["sam:system:authenticated"]- role: "public-mesh"- roles:- public-mesh:- allowed_services:- - "*"- allowed_targets:- - "*"+ name: sam-control-plane-seed-policy+spec:+ template:+ spec:+ restartPolicy: OnFailure+ containers:+ - name: seed+ image: curlimages/curl:8.6.0+ env:+ - name: SAM_ADMIN_TOKEN+ valueFrom:+ secretKeyRef:+ name: sam-control-plane-secret+ key: SAM_ADMIN_TOKEN+ command:+ - sh+ - -c+ - |+ set -eu+ until curl -sf -o /dev/null http://sam-control-plane:8080/healthz; do sleep 2; done+ curl -sf -X POST \+ -H "Content-Type: application/json" \+ -H "Authorization: Bearer ${SAM_ADMIN_TOKEN}" \+ -d '{+ "roles": [+ {"name": "public-mesh", "allowed_services": ["*"], "allowed_targets": ["*"]}+ ],+ "bindings": [+ {"role": "public-mesh", "members": ["sam:system:authenticated"]}+ ]+ }' \+ http://sam-control-plane:8080/policiesdiff --git a/site/content/docs/user/_index.md b/site/content/docs/user/_index.mdindex 95c804c9..4b37c9eb 100644--- a/site/content/docs/user/_index.md+++ b/site/content/docs/user/_index.md@@ -9,7 +9,7 @@ Welcome to the User & Operator Guides. This section provides detailed documentat### In This Section1. **[Control Plane Configuration](control-plane-configuration/)**- Learn how to configure the OIDC identity bridge, set up cryptographic private keys, enforce TLS/mTLS, and write custom security role policy mappings in `policies.yaml`.+ Learn how to configure the OIDC identity bridge, set up cryptographic private keys, enforce TLS/mTLS, and write custom security role policy mappings.2. **[Agent Usage & Connectivity](agent-usage/)**Understand how nodes connect to the mesh via OIDC login, secure credentials, run local Model Context Protocol (MCP) servers, and expose secure remote tool access to agents (like Google Gemini and Claude).diff --git a/site/content/docs/user/kubernetes-deployment.md b/site/content/docs/user/kubernetes-deployment.mdindex 206b3b30..e4284e87 100644--- a/site/content/docs/user/kubernetes-deployment.md+++ b/site/content/docs/user/kubernetes-deployment.md@@ -93,32 +93,7 @@ kubectl rollout status deployment/dex -n dexThe Control Plane verifies OIDC tokens and manages access policies. The Routers handle peer discovery and routing within the GossipSub mesh.-### 1. Configure Access Control Policies (`policies.yaml`)-Create a ConfigMap defining your global mesh access rules:-```yaml-apiVersion: v1-kind: ConfigMap-metadata:- name: sam-control-plane-policies- namespace: sam-data:- policies.yaml: |- version: "v1alpha1"- bindings:- - members: ["user:system:serviceaccount:sam-nodes:sam-node-sa"]- role: "node-role"- roles:- node-role:- allowed_services:- - "*"- allowed_targets:- - "*"-```-```bash-kubectl apply -f policies-configmap.yaml-```--### 2. Deploy SAM Control Plane+### 1. Deploy SAM Control PlaneThe Control Plane is stateless and can scale horizontally. It connects to a shared PostgreSQL database to persist active leases and rotated capability signing keys.```yaml@@ -146,20 +121,35 @@ spec:- "--db-dsn=postgres://sam:password@sam-db-service:5432/sam_mesh?sslmode=disable"- "--issuer=https://AUTH.YOUR-DOMAIN.COM"- "--allowed-audiences=YOUR-CLIENT-AUDIENCE"- - "--policy-file=/etc/sam/policies/policies.yaml"ports:- containerPort: 8080name: http- volumeMounts:- - name: policies-volume- mountPath: /etc/sam/policies- readOnly: true- volumes:- - name: policies-volume- configMap:- name: sam-control-plane-policies```+### 2. Configure Access Control Policies+The Control Plane starts **default closed**: until a policy is posted it authorizes+nothing. Policy lives in the database, not on disk, so seed it through the admin+API. Roles and bindings use the same schema everywhere, including the Mesh Policy+editor in the console.++```bash+curl -sf -X POST \+ -H "Content-Type: application/json" \+ -H "Authorization: Bearer ${SAM_ADMIN_TOKEN}" \+ -d '{+ "roles": [+ {"name": "node-role", "allowed_services": ["*"], "allowed_targets": ["*"]}+ ],+ "bindings": [+ {"role": "node-role", "members": ["user:system:serviceaccount:sam-nodes:sam-node-sa"]}+ ]+ }' \+ https://CONTROL-PLANE.YOUR-DOMAIN.COM/policies+```++The `sam-mesh` Helm chart runs this as a bootstrap Job for you; see+`charts/sam-mesh/templates/bootstrap-job.yaml`.+### 3. Deploy SAM Router StatefulSetThe Router must be deployed as a StatefulSet to allocate a persistent volume for storing its libp2p identity key, ensuring a stable Peer ID across pod restarts.diff --git a/site/content/docs/user/node-configuration.md b/site/content/docs/user/node-configuration.mdindex f3e53ece..086f7b3a 100644--- a/site/content/docs/user/node-configuration.md+++ b/site/content/docs/user/node-configuration.md@@ -56,7 +56,7 @@ The `services` array allows you to register endpoints that remote peers in the S| Property | Description || :--- | :--- || `type` | The protocol protocol type. Supported values are `mcp` (Model Context Protocol), `inference`, or `a2a`. |-| `name` | The unique name of the service (e.g., `git-helper`). This must exactly match the name authorized by the control plane's `policies.yaml` (e.g., `mcp://git-helper`). |+| `name` | The unique name of the service (e.g., `git-helper`). This must exactly match the name authorized by the control plane's mesh policy (e.g., `mcp://git-helper`). || `description` | A human-readable description published to the mesh discovery catalogue. || `command` | *(For MCP)* The executable command array to spawn as a local subprocess (e.g. `["node", "index.js"]`). || `env` | *(For MCP)* Key-value environment variables passed to the subprocess. |diff --git a/tests/integration/failover_test.go b/tests/integration/failover_test.goindex b5aae59b..d536cdc0 100644--- a/tests/integration/failover_test.go+++ b/tests/integration/failover_test.go@@ -48,7 +48,7 @@ func TestFailoverUpdatesRelay(t *testing.T) {policyFile := filepath.Join(tmpDir, "policies.yaml")policyContent := `version: "v1alpha1"bindings: []-roles: {}+roles: []`writePolicyWithRouter(t, policyFile, policyContent)diff --git a/tests/integration/federation_test.go b/tests/integration/federation_test.goindex 0c2ea867..faba4507 100644--- a/tests/integration/federation_test.go+++ b/tests/integration/federation_test.go@@ -49,8 +49,8 @@ bindings:- members: ["user:mock-user"]role: adminroles:- admin:- allowed_services:+ - name: admin+ allowed_services:- "mcp://*"- "system://sam.catalog"allowed_targets: ["*"]diff --git a/tests/integration/local_policy_test.go b/tests/integration/local_policy_test.goindex 49633830..44300ba6 100644--- a/tests/integration/local_policy_test.go+++ b/tests/integration/local_policy_test.go@@ -21,7 +21,7 @@ func TestLocalPolicyCanGrantPermissions(t *testing.T) {controlPlanePolicyFile := filepath.Join(tmpDir, "policies.yaml")controlPlanePolicyYAML := `version: "v1alpha1"roles:- none:+ - name: noneallowed_services: []allowed_targets: ["*"]bindings:@@ -165,7 +165,7 @@ func TestLocalPolicyCannotBypassControlPlaneTargetConstraint(t *testing.T) {controlPlanePolicyFile := filepath.Join(tmpDir, "policies.yaml")controlPlanePolicyYAML := `version: "v1alpha1"roles:- restricted-role:+ - name: restricted-roleallowed_services: ["*"]allowed_targets: ["group:admin-only"]bindings:diff --git a/tests/integration/mcp_local_tools_test.go b/tests/integration/mcp_local_tools_test.goindex 5898a725..1f50992b 100644--- a/tests/integration/mcp_local_tools_test.go+++ b/tests/integration/mcp_local_tools_test.go@@ -34,7 +34,7 @@ func TestMCPLocalTools(t *testing.T) {policyFile := filepath.Join(tmpDir, "policies.yaml")policyContent := `version: "v1alpha1"bindings: []-roles: {}+roles: []`if err := os.WriteFile(policyFile, []byte(policyContent), 0644); err != nil {t.Fatal(err)diff --git a/tests/integration/minimal_helpers_test.go b/tests/integration/minimal_helpers_test.goindex c6b3c540..f359ea1c 100644--- a/tests/integration/minimal_helpers_test.go+++ b/tests/integration/minimal_helpers_test.go@@ -17,6 +17,7 @@ package integration_testimport ("bytes""context"+ "encoding/json""errors""fmt""os"@@ -628,9 +629,9 @@ func writePolicyWithRouter(t *testing.T, path string, yamlContent string) {// Replace empty markers firstcontent = strings.ReplaceAll(content, "bindings: []", "bindings:")- content = strings.ReplaceAll(content, "roles: {}", "roles:")+ content = strings.ReplaceAll(content, "roles: []", "roles:")- routerRole := fmt.Sprintf(` %s:+ routerRole := fmt.Sprintf(` - name: %sallowed_services: []allowed_targets: ["*"]`, api.RoleRouter)routerBinding := fmt.Sprintf(` - role: %s@@ -671,21 +672,10 @@ func waitForNodeOnline(t *testing.T, logPath string) {}}-type testBinding struct {- Role string `yaml:"role"`- Members []string `yaml:"members"`-}--type testRolePolicy struct {- AllowedTargets []string `yaml:"allowed_targets"`- AllowedServices []string `yaml:"allowed_services"`-}--type testPolicyConfig struct {- Bindings []testBinding `yaml:"bindings"`- Roles map[string]testRolePolicy `yaml:"roles"`-}-+// injectPolicyYAML posts a policy fixture through the same conversion the console+// performs: YAML for readability, protojson on the wire. Going through JSON keeps+// this helper free of any field list, so a new PolicyRole field needs no change+// here and cannot be silently dropped.func injectPolicyYAML(t *testing.T, port int, adminToken string, policyFile string) {t.Helper()@@ -694,37 +684,18 @@ func injectPolicyYAML(t *testing.T, port int, adminToken string, policyFile strit.Fatalf("failed to read policy file %s: %v", policyFile, err)}- var config testPolicyConfig- if err := yaml.Unmarshal(data, &config); err != nil {+ var doc interface{}+ if err := yaml.Unmarshal(data, &doc); err != nil {t.Fatalf("failed to unmarshal policy file %s: %v", policyFile, err)}- reqData := &api.PolicyConfigUpdateRequest{- Roles: make([]*api.PolicyRole, 0, len(config.Roles)),- Bindings: make([]*api.PolicyBinding, 0, len(config.Bindings)),- }-- for name, role := range config.Roles {- reqData.Roles = append(reqData.Roles, &api.PolicyRole{- Name: name,- AllowedServices: role.AllowedServices,- AllowedTargets: role.AllowedTargets,- })- }- for _, b := range config.Bindings {- reqData.Bindings = append(reqData.Bindings, &api.PolicyBinding{- Role: b.Role,- Members: b.Members,- })- }-- protoData, err := proto.Marshal(reqData)+ jsonData, err := json.Marshal(yamlToJSON(doc))if err != nil {- t.Fatalf("failed to marshal policy request: %v", err)+ t.Fatalf("failed to convert policy file %s to JSON: %v", policyFile, err)}- req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("http://127.0.0.1:%d/policies", port), bytes.NewReader(protoData))- req.Header.Set("Content-Type", "application/x-protobuf")+ req, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("http://127.0.0.1:%d/policies", port), bytes.NewReader(jsonData))+ req.Header.Set("Content-Type", "application/json")req.Header.Set("Authorization", "Bearer "+adminToken)client := &http.Client{Timeout: 5 * time.Second}@@ -739,3 +710,23 @@ func injectPolicyYAML(t *testing.T, port int, adminToken string, policyFile strit.Fatalf("unexpected POST /policies status: %s (body: %s)", resp.Status, string(body))}}++// yamlToJSON rewrites the map[interface{}]interface{} that yaml.v2 produces into+// the map[string]interface{} encoding/json requires.+func yamlToJSON(v interface{}) interface{} {+ switch typed := v.(type) {+ case map[interface{}]interface{}:+ converted := make(map[string]interface{}, len(typed))+ for key, value := range typed {+ converted[fmt.Sprintf("%v", key)] = yamlToJSON(value)+ }+ return converted+ case []interface{}:+ for i, value := range typed {+ typed[i] = yamlToJSON(value)+ }+ return typed+ default:+ return v+ }+}diff --git a/tests/integration/multimaster_test.go b/tests/integration/multimaster_test.goindex 32e543c5..8d300ed1 100644--- a/tests/integration/multimaster_test.go+++ b/tests/integration/multimaster_test.go@@ -45,7 +45,7 @@ func TestMultiMasterControlPlane(t *testing.T) {policyFile := filepath.Join(tmpDir, "policies.yaml")policyContent := `version: "v1alpha1"bindings: []-roles: {}+roles: []`writePolicyWithRouter(t, policyFile, policyContent)diff --git a/tests/integration/policy_permutations_test.go b/tests/integration/policy_permutations_test.goindex 742e2d7a..bf9267b7 100644--- a/tests/integration/policy_permutations_test.go+++ b/tests/integration/policy_permutations_test.go@@ -79,22 +79,22 @@ func TestPolicyPermutations(t *testing.T) {controlPlanePolicyFile := filepath.Join(tmpDir, "policies.yaml")controlPlanePolicyYAML := `version: "v1alpha1"roles:- role-user:+ - name: role-userallowed_services: ["mcp://test-user"]allowed_targets: ["user:bob-subject"]- role-email:+ - name: role-emailallowed_services: ["mcp://test-email"]allowed_targets: ["email:[email protected]"]- role-group:+ - name: role-groupallowed_services: ["mcp://test-group"]allowed_targets: ["group:compute"]- role-node:+ - name: role-nodeallowed_services: ["mcp://test-node"]allowed_targets: ["group:backend"]- role-direct:+ - name: role-directallowed_services: ["mcp://test-role"]allowed_targets: ["group:compute"]- admin:+ - name: adminallowed_services: ["*"]allowed_targets: ["*:*"]diff --git a/tests/integration/revocation_test.go b/tests/integration/revocation_test.goindex 0741dbe0..64db971e 100644--- a/tests/integration/revocation_test.go+++ b/tests/integration/revocation_test.go@@ -50,7 +50,7 @@ bindings:- members: ["user:mock-user"]role: adminroles:- admin:+ - name: adminallowed_services: ["*"]allowed_targets: ["*"]`diff --git a/tests/integration/rotation_test.go b/tests/integration/rotation_test.goindex 4707bc56..9a5a5a7e 100644--- a/tests/integration/rotation_test.go+++ b/tests/integration/rotation_test.go@@ -45,7 +45,7 @@ bindings:- members: ["user:mock-user"]role: adminroles:- admin:+ - name: adminallowed_services: ["*"]allowed_targets: ["*"]`