Skip to content

Agent Mesh

mobile: support attested labels on the Android node

Tomas Tormo6aeff782b71a
diff --git a/api/labels.go b/api/labels.go
index 73349c71..c216a5f6 100644
--- a/api/labels.go
+++ b/api/labels.go
@@ -87,6 +87,32 @@ func ValidateLabels(labels map[string]string) error {
return nil
}
+// ParseLabels parses a comma-separated "key=value" list (the wire/CLI form of
+// a label set) into a label map; an empty string means no claims. Parsing is
+// syntax only — run the result through ValidateLabels.
+func ParseLabels(s string) (map[string]string, error) {
+ if s == "" {
+ return nil, nil
+ }
+ labels := make(map[string]string)
+ for _, part := range strings.Split(s, ",") {
+ part = strings.TrimSpace(part)
+ if part == "" {
+ continue
+ }
+ k, v, ok := strings.Cut(part, "=")
+ if !ok {
+ return nil, fmt.Errorf("invalid label %q: expected key=value", part)
+ }
+ key := strings.TrimSpace(k)
+ if _, exists := labels[key]; exists {
+ return nil, fmt.Errorf("duplicate label key %q", key)
+ }
+ labels[key] = strings.TrimSpace(v)
+ }
+ return labels, nil
+}
+
// A node declares its own labels when it enrols, so on its own a label is a
// claim rather than an attestation. A role's allowed_labels is what makes it
// one: the control plane only signs a label the operator said that role may
diff --git a/api/labels_test.go b/api/labels_test.go
index 4ad2d80a..9cf0c985 100644
--- a/api/labels_test.go
+++ b/api/labels_test.go
@@ -107,3 +107,22 @@ func TestValidateLabels_AllKeysValidStaysSorted(t *testing.T) {
t.Errorf("ValidateLabels(sorted happy path): unexpected error: %v", err)
}
}
+
+func TestParseLabels(t *testing.T) {
+ labels, err := ParseLabels("region=eu-west-1, team = platform")
+ if err != nil {
+ t.Fatalf("ParseLabels failed: %v", err)
+ }
+ if labels["region"] != "eu-west-1" || labels["team"] != "platform" {
+ t.Fatalf("unexpected labels: %v", labels)
+ }
+ if labels, err := ParseLabels(""); err != nil || labels != nil {
+ t.Fatalf("empty string should yield no labels, got %v, %v", labels, err)
+ }
+ if _, err := ParseLabels("no-equals"); err == nil {
+ t.Fatal("expected error for label without =")
+ }
+ if _, err := ParseLabels("k=a,k=b"); err == nil {
+ t.Fatal("expected error for duplicate key")
+ }
+}
diff --git a/mobile/sam-node-app/integration_test/e2e_test.dart b/mobile/sam-node-app/integration_test/e2e_test.dart
index ba7adeaa..a041fe1e 100644
--- a/mobile/sam-node-app/integration_test/e2e_test.dart
+++ b/mobile/sam-node-app/integration_test/e2e_test.dart
@@ -44,7 +44,7 @@ void main() {
// 3. Enroll Node against the host control plane
const controlPlaneURL = 'http://127.0.0.1:37001';
- final enrollErr = samLib.enroll(dataDir, controlPlaneURL, jwt, true);
+ final enrollErr = samLib.enroll(dataDir, controlPlaneURL, jwt, true, '');
expect(enrollErr, isNull);
// Start local Mock MCP Server inside the Android emulator. It must be
diff --git a/mobile/sam-node-app/lib/main.dart b/mobile/sam-node-app/lib/main.dart
index cf6f005e..8646c1dc 100644
--- a/mobile/sam-node-app/lib/main.dart
+++ b/mobile/sam-node-app/lib/main.dart
@@ -25,9 +25,9 @@ String? _isolatedFetchControlPlaneInfo(String url) {
}
}
-String? _isolatedEnroll(String dataDir, String controlPlaneText, String jwtText, bool allowLoopback) {
+String? _isolatedEnroll(String dataDir, String controlPlaneText, String jwtText, bool allowLoopback, String labelsText) {
try {
- return SamNodeLib().enroll(dataDir, controlPlaneText, jwtText, allowLoopback);
+ return SamNodeLib().enroll(dataDir, controlPlaneText, jwtText, allowLoopback, labelsText);
} catch (e) {
return e.toString();
}
@@ -71,7 +71,9 @@ class _NodeControlPageState extends State<NodeControlPage> {
TextEditingController(text: 'https://bananas.sam-mesh.dev');
final _jwtController = TextEditingController();
final _tokenController = TextEditingController(text: 'secret-token');
-
+ // Labels are attested at enrollment; changing them requires re-enrolling.
+ final _labelsController = TextEditingController();
+
static const _exposeChannel = MethodChannel('com.example.sam_agent/mesh_expose');
late SamNodeLib _samLib;
@@ -116,6 +118,7 @@ class _NodeControlPageState extends State<NodeControlPage> {
_controlPlaneController.dispose();
_jwtController.dispose();
_tokenController.dispose();
+ _labelsController.dispose();
_externalMcpUrlController.dispose();
_externalMcpNameController.dispose();
_externalMcpDescController.dispose();
@@ -574,8 +577,9 @@ class _NodeControlPageState extends State<NodeControlPage> {
final dataDir = '${appDir.path}/sam_data';
final controlPlaneText = _controlPlaneController.text;
final jwtText = _jwtController.text;
+ final labelsText = _labelsController.text.trim();
final err = await Isolate.run(() {
- return _isolatedEnroll(dataDir, controlPlaneText, jwtText, true);
+ return _isolatedEnroll(dataDir, controlPlaneText, jwtText, true, labelsText);
});
setState(() {
@@ -656,6 +660,7 @@ class _NodeControlPageState extends State<NodeControlPage> {
'apiToken': _tokenController.text,
'allowLoopback': true,
'enableRelay': false,
+ 'labels': _labelsController.text.trim(),
'services': services,
});
@@ -688,7 +693,7 @@ class _NodeControlPageState extends State<NodeControlPage> {
_pollingTimer?.cancel();
_embeddedMcpServer.stop();
final err = _samLib.stop();
-
+
// Stop Android Foreground Service
try {
_exposeChannel.invokeMethod('stopBackgroundService');
@@ -929,6 +934,15 @@ class _NodeControlPageState extends State<NodeControlPage> {
),
),
const SizedBox(height: 20),
+ TextField(
+ controller: _labelsController,
+ decoration: const InputDecoration(
+ labelText: 'Labels (key=value, comma-separated)',
+ border: OutlineInputBorder(),
+ hintText: 'region=eu-west-1',
+ ),
+ ),
+ const SizedBox(height: 20),
ElevatedButton.icon(
onPressed: _loggingIn ? null : _loginAndEnroll,
icon: _loggingIn
diff --git a/mobile/sam-node-app/lib/sam_ffi.dart b/mobile/sam-node-app/lib/sam_ffi.dart
index 7b7aca10..e6cf9118 100644
--- a/mobile/sam-node-app/lib/sam_ffi.dart
+++ b/mobile/sam-node-app/lib/sam_ffi.dart
@@ -17,12 +17,14 @@ typedef EnrollNodeC = ffi.Pointer<Utf8> Function(
ffi.Pointer<Utf8> dataDir,
ffi.Pointer<Utf8> controlPlaneURL,
ffi.Pointer<Utf8> jwt,
- ffi.Int8 allowLoopback);
+ ffi.Int8 allowLoopback,
+ ffi.Pointer<Utf8> labels);
typedef EnrollNodeDart = ffi.Pointer<Utf8> Function(
ffi.Pointer<Utf8> dataDir,
ffi.Pointer<Utf8> controlPlaneURL,
ffi.Pointer<Utf8> jwt,
- int allowLoopback);
+ int allowLoopback,
+ ffi.Pointer<Utf8> labels);
typedef FetchControlPlaneInfoJSONC = ffi.Pointer<Utf8> Function(ffi.Pointer<Utf8> controlPlaneURL);
typedef FetchControlPlaneInfoJSONDart = ffi.Pointer<Utf8> Function(ffi.Pointer<Utf8> controlPlaneURL);
@@ -94,17 +96,19 @@ class SamNodeLib {
return goID;
}
- String? enroll(String dataDir, String controlPlaneURL, String jwt, bool allowLoopback) {
+ String? enroll(String dataDir, String controlPlaneURL, String jwt, bool allowLoopback, String labels) {
final cDataDir = dataDir.toNativeUtf8();
final cControlPlaneURL = controlPlaneURL.toNativeUtf8();
final cJWT = jwt.toNativeUtf8();
final cAllowLoopback = allowLoopback ? 1 : 0;
+ final cLabels = labels.toNativeUtf8();
- final cErr = _enrollNode(cDataDir, cControlPlaneURL, cJWT, cAllowLoopback);
+ final cErr = _enrollNode(cDataDir, cControlPlaneURL, cJWT, cAllowLoopback, cLabels);
calloc.free(cDataDir);
calloc.free(cControlPlaneURL);
calloc.free(cJWT);
+ calloc.free(cLabels);
if (cErr.address == 0) return null;
final goErr = cErr.toDartString();
diff --git a/mobile/sam-node-ffi/ffi/ffi.go b/mobile/sam-node-ffi/ffi/ffi.go
index ea26a847..f29ced8f 100644
--- a/mobile/sam-node-ffi/ffi/ffi.go
+++ b/mobile/sam-node-ffi/ffi/ffi.go
@@ -56,8 +56,11 @@ type MobileConfig struct {
LogLevel string `json:"logLevel"`
DiscoveryInterval string `json:"discoveryInterval"`
ListenAddrs string `json:"listenAddrs"` // comma-separated
- AllowLoopback bool `json:"allowLoopback"`
- EnableRelay bool `json:"enableRelay"`
+ // Labels are comma-separated key=value claims (same syntax as the CLI
+ // --labels flag); they are attested only at enrollment.
+ Labels string `json:"labels"`
+ AllowLoopback bool `json:"allowLoopback"`
+ EnableRelay bool `json:"enableRelay"`
// Services this node exposes, declared at start like the node config
// file's services block; there is no runtime registration.
Services []MobileService `json:"services,omitempty"`
@@ -85,6 +88,11 @@ func StartNode(configJSON string) error {
return fmt.Errorf("failed to parse config JSON: %w", err)
}
+ labels, err := api.ParseLabels(config.Labels)
+ if err != nil {
+ return fmt.Errorf("invalid labels: %w", err)
+ }
+
lvl := golog.LevelInfo
if config.LogLevel != "" {
if l, err := golog.LevelFromString(config.LogLevel); err == nil {
@@ -197,7 +205,7 @@ func StartNode(configJSON string) error {
ListenAddrs: listenAddrs,
EnableRelay: config.EnableRelay,
AllowLoopback: config.AllowLoopback,
- NodeConfig: &node.NodeConfigComplete{Services: services},
+ NodeConfig: &node.NodeConfigComplete{Services: services, Labels: labels},
MonitorBootstrap: 2 * time.Minute,
MonitorInterval: 1 * time.Minute,
AutoRelayMinInterval: 30 * time.Second,
@@ -311,8 +319,14 @@ func GetNodeID() string {
return ""
}
-// EnrollNode enrolls a node.
-func EnrollNode(dataDir string, controlPlaneURL string, jwt string, allowLoopback bool) error {
+// EnrollNode enrolls a node. Labels use the CLI --labels syntax and are
+// minted into the node's Biscuit here — changing them requires re-enrolling.
+func EnrollNode(dataDir string, controlPlaneURL string, jwt string, allowLoopback bool, labels string) error {
+ parsedLabels, err := api.ParseLabels(labels)
+ if err != nil {
+ return fmt.Errorf("invalid labels: %w", err)
+ }
+
_ = os.MkdirAll(dataDir, 0700)
logFilePath := filepath.Join(dataDir, "node.log")
golog.SetupLogging(golog.Config{
@@ -354,6 +368,7 @@ func EnrollNode(dataDir string, controlPlaneURL string, jwt string, allowLoopbac
Store: store,
AllowLoopback: allowLoopback,
ListenAddrs: listenAddrs,
+ NodeConfig: &node.NodeConfigComplete{Labels: parsedLabels},
})
if err != nil {
return fmt.Errorf("failed to create node for enrollment: %w", err)
diff --git a/mobile/sam-node-ffi/ffi/ffi_test.go b/mobile/sam-node-ffi/ffi/ffi_test.go
index 559db114..a4da5b7a 100644
--- a/mobile/sam-node-ffi/ffi/ffi_test.go
+++ b/mobile/sam-node-ffi/ffi/ffi_test.go
@@ -72,11 +72,13 @@ func TestMobileFFILifecycle(t *testing.T) {
println("--- MOCK ROUTER: wrote AuthResponse success with valid biscuit")
})
+ var enrolledLabels map[string]string
mux := http.NewServeMux()
mux.HandleFunc("/register", func(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
var req api.EnrollRequest
_ = proto.Unmarshal(body, &req)
+ enrolledLabels = req.Labels
biscuitBytes := mintMockBiscuit(t, req.PeerId, cpPrivKey, api.RoleNode)
resp := &api.EnrollResponse{
@@ -104,10 +106,13 @@ func TestMobileFFILifecycle(t *testing.T) {
// 2. Mobile Enrollment
tmpDir := t.TempDir()
- err = EnrollNode(tmpDir, httpServer.URL, "dummy-jwt", true)
+ err = EnrollNode(tmpDir, httpServer.URL, "dummy-jwt", true, "region=eu-west-1")
if err != nil {
t.Fatalf("EnrollNode failed: %v", err)
}
+ if enrolledLabels["region"] != "eu-west-1" {
+ t.Fatalf("Expected label region=eu-west-1 in enroll request, got %v", enrolledLabels)
+ }
// 3. Mobile Node Start
cfg := MobileConfig{
@@ -117,6 +122,7 @@ func TestMobileFFILifecycle(t *testing.T) {
BindAddr: "127.0.0.1:0", // random free port
ApiToken: "test-token",
AllowLoopback: true,
+ Labels: "region=eu-west-1",
}
cfgBytes, _ := json.Marshal(cfg)
@@ -136,6 +142,13 @@ func TestMobileFFILifecycle(t *testing.T) {
}
}
+func TestStartNodeRejectsInvalidLabels(t *testing.T) {
+ if err := StartNode(`{"labels": "no-equals"}`); err == nil {
+ _ = StopNode()
+ t.Fatal("expected StartNode to reject invalid labels")
+ }
+}
+
func mintMockBiscuit(t *testing.T, peerID string, priv ed25519.PrivateKey, role string) []byte {
builder := biscuit.NewBuilder(priv)
if err := builder.AddAuthorityFact(biscuit.Fact{
diff --git a/mobile/sam-node-ffi/main.go b/mobile/sam-node-ffi/main.go
index a99d4718..622526f5 100644
--- a/mobile/sam-node-ffi/main.go
+++ b/mobile/sam-node-ffi/main.go
@@ -55,13 +55,14 @@ func GetNodeID() *C.char {
}
//export EnrollNode
-func EnrollNode(dataDir *C.char, controlPlaneURL *C.char, jwt *C.char, allowLoopback C.char) *C.char {
+func EnrollNode(dataDir *C.char, controlPlaneURL *C.char, jwt *C.char, allowLoopback C.char, labels *C.char) *C.char {
goDataDir := C.GoString(dataDir)
goControlPlaneURL := C.GoString(controlPlaneURL)
goJWT := C.GoString(jwt)
goAllowLoopback := allowLoopback != 0
+ goLabels := C.GoString(labels)
- err := ffi.EnrollNode(goDataDir, goControlPlaneURL, goJWT, goAllowLoopback)
+ err := ffi.EnrollNode(goDataDir, goControlPlaneURL, goJWT, goAllowLoopback, goLabels)
if err != nil {
return C.CString(err.Error())
}
diff --git a/site/content/docs/development/mobile.md b/site/content/docs/development/mobile.md
index 67ae9d64..0c9759be 100644
--- a/site/content/docs/development/mobile.md
+++ b/site/content/docs/development/mobile.md
@@ -41,7 +41,7 @@ To run `sam-node` on mobile with near-zero codebase maintenance, we avoid rewrit
1. **Go FFI Binding Package (`mobile/sam-node-ffi/`)**: Contains CGO-exported functions (`StartNode`, `StopNode`, `EnrollNode`, `GetNodeID`, `FreeString`) which compile into a C-shared library (`.so`) or static archive (`.a`).
2. **Flutter App (`mobile/sam-node-app/`)**: A cross-platform app containing:
- `lib/sam_ffi.dart`: The Dart FFI wrapper loading the Go library and exposing Dart methods.
- - `lib/main.dart`: Simple control UI to enroll and start/stop the background node.
+ - `lib/main.dart`: Simple control UI to enroll and start/stop the background node. The enrollment screen accepts optional labels (comma-separated `key=value`, same syntax as the CLI `--labels` flag); like on desktop, labels are attested only at enrollment, so changing them requires re-enrolling.
3. **Local Loopback Communication**:
- The Flutter Dart environment controls the node lifecycle (construction, starting, stopping) via FFI.
- Any actual tool registration, discovery, or mesh API queries are performed using standard HTTP JSON-RPC calls over local loopback (`127.0.0.1`) to the `sam-node` sidecar API.