Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
update content
Antonio Ojea861551d24b65
diff --git a/README.md b/README.mdindex 65910860..6fb52436 100644--- a/README.md+++ b/README.md@@ -26,7 +26,6 @@ Start exploring the Sovereign Agent Mesh:Get a node running on the public testnet (`bananas.sam-mesh.dev`) in minutes:- π **[User Quick Start Guide](site/content/docs/quickstart.md)**: Connect and run a SAM node using binaries or Docker, and query the local MCP server.- π€ **[Agent Integration Guides](site/content/docs/integrations/_index.md)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to dynamically discover and call tools across the mesh.-- π **[CLI Reference](site/content/docs/cli/reference.md)**: Comprehensive CLI reference and configurations.- π‘ **[Testnet Validation Tutorial](site/content/docs/development/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.### For Developers & Contributorsdiff --git a/site/content/docs/_index.md b/site/content/docs/_index.mdindex aa6dc087..b4b115f9 100644--- a/site/content/docs/_index.md+++ b/site/content/docs/_index.md@@ -24,7 +24,6 @@ The documentation here is intentionally small and aligned with what is implement- [Quick Start](quickstart.md) - User Quick Start using Docker.- [Hub Configuration](user/hub-configuration.md) - OIDC authentication, key rings, and custom policy rules in `policies.yaml`.- [Agent Usage](user/agent-usage.md) - Node authorization flows, MCP endpoints, and how agents connect.-- [CLI Reference](cli/reference.md) - CLI command usage reference.- [Developer Guide](development/_index.md) - Building from source, local testing, and Kind setups.- [Testing Guide](development/testing.md) - Detailed test layer and troubleshooting information.- [Testnet Validation Tutorial](development/testnet-validation.md) - Real-time integration and MCP verification with public testnets.diff --git a/site/content/docs/development/kubernetes-deployment.md b/site/content/docs/development/kubernetes-deployment.mdindex 09a2605f..2c5460b7 100644--- a/site/content/docs/development/kubernetes-deployment.md+++ b/site/content/docs/development/kubernetes-deployment.md@@ -90,31 +90,32 @@ To connect a `sam-node` to the hub, you just need the hub's external IP and portTo connect a `sam-node` to the hub for the first time, you need to enroll it. The node needs to authenticate with the hub using a JWT token.-If you are using the **Mock OIDC Provider**, the node can fetch the token automatically from the mock provider's token endpoint.+If you are using the **Mock OIDC Provider**, the node can fetch the token using OIDC Client Credentials flow:1. **Get the Mock OIDC Service IP:**```bashMOCK_IP=$(kubectl get svc mock-oidc -o jsonpath='{.status.loadBalancer.ingress[0].ip}')```-2. **Run the Node with Token URL:**+2. **Run the Node to enroll:**```bashsam-node run \- --hub "$HUB_IP:4002" \- --token-url "http://$MOCK_IP:18080/token"+ --hub "http://$HUB_IP:9090" \+ --oidc-issuer "http://$MOCK_IP:18080" \+ --client-id "sam-mesh-audience" \+ --client-secret "sam-e2e-secret"```If you are using **Google OIDC**, you must obtain a valid Google ID token for your user and pass it via the `--jwt` flag:```bashsam-node run \- --hub "$HUB_IP:4002" \+ --hub "http://$HUB_IP:9090" \--jwt "<your-google-id-token>"```-Once enrolled, identity is stored in the local database, and you can run without authentication flags:+Once enrolled, the identity is stored in the local database (`agent.db`), and you can run subsequent times without OIDC credentials:```bash-sam-node run \- --hub "$HUB_IP:4002"+sam-node run```---@@ -148,9 +149,13 @@ spec:command: ["sam-node", "run"]args:- "--hub"- - "sam-hub:4002"- - "--token-url"- - "http://mock-oidc:18080/token"+ - "http://sam-hub:9090"+ - "--oidc-issuer"+ - "http://mock-oidc:18080"+ - "--client-id"+ - "sam-mesh-audience"+ - "--client-secret"+ - "sam-e2e-secret"env:- name: HOMEvalue: /data@@ -169,25 +174,27 @@ The SAM project supports three primary flows for acquiring a JWT token to enroll#### 1. Client Credentials Flow (Machine-to-Machine)* **Description:** Defined in OAuth 2.0 RFC 6749, section 4.4. An application exchanges its application credentials (such as Client ID and Client Secret) for an access token.* **Use Case:** For unattended services or deployments connecting to a production OIDC provider.-* **How to use:** Pass the `--token-url`, `--client-id`, and `--client-secret` flags to `sam-node run`.+* **How to use:** Pass the `--oidc-issuer`, `--client-id`, and `--client-secret` flags to `sam-node run`.* **Example:**```bashsam-node run \- --hub "hub.example.com:4002" \- --token-url "https://oauth2.googleapis.com/token" \+ --hub "http://hub.example.com:9090" \+ --oidc-issuer "https://accounts.google.com" \--client-id "$SAM_OIDC_ID" \--client-secret "$SAM_OIDC_SECRET"```#### 2. Native App Authorization Code Flow (Human Intervention)-* **Description:** For devices operated by humans, this uses the standard Authorization Code Flow with PKCE for native apps (RFC 8252). `sam-node` spins up a temporary local HTTP server, opens your browser, and receives the authentication token locally via an ephemeral loopback address.+* **Description:** For devices operated by humans, this uses the standard Authorization Code Flow with PKCE for native apps (RFC 8252). The human operator runs `sam-node join` to open a web browser (or get a verification code via `--headless`), completes the login, and obtains a Biscuit token which is stored in the local database (`agent.db`).* **Use Case:** When a human operator is enrolling a node manually via their local terminal.-* **How to use:** When you omit the `--jwt` or `--token-url` flags (or pass the OIDC issuer flag interactively), the node opens the browser and completes the flow without needing to enter complex passwords in the CLI. Alternatively, you can obtain a token yourself and pass it via the `--jwt` flag.+* **How to use:** Run `sam-node join <hub-url>` before running the node daemon. Alternatively, you can obtain a token yourself and pass it via the `--jwt` flag to `sam-node run`.* **Example:**```bash-sam-node run \- --hub "hub.example.com:4002" \- --jwt "eyJhbGciOiJSUzI1NiIs..."+# First, join interactively:+sam-node join https://hub.example.com++# Then start the node daemon:+sam-node run```#### 3. Workload Identity Federation (Secretless Kubernetes)@@ -198,7 +205,7 @@ sam-node run \* **Example:**```bashsam-node run \- --hub "hub.example.com:4002" \+ --hub "http://hub.example.com:9090" \--jwt-path "/var/run/secrets/kubernetes.io/serviceaccount/token"```> [!NOTE]@@ -269,7 +276,7 @@ spec:command: ["sam-node", "run"]args:- "--hub"- - "sam-hub:4002"+ - "http://sam-hub:9090"- "--jwt-path"- "/var/run/secrets/tokens/sam-token"volumeMounts:diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.mdindex bbb5ce2f..d929b4c2 100644--- a/site/content/docs/development/policy.md+++ b/site/content/docs/development/policy.md@@ -67,6 +67,9 @@ allow if group("engineering");## 2. Hub Policy Schema (`policies.yaml`)Admins define central permissions by mapping OIDC roles to specific capabilities.+> [!IMPORTANT]+> Wildcards (e.g. `*`) are explicitly disallowed in policy definitions. All allowed network targets and MCP servers must be explicitly listed.+```yamlversion: "v1alpha1"roles:@@ -74,7 +77,7 @@ roles:network:allowed_targets: ["db-agent.data-mesh"] # Who they can connect tomcp:- allowed_tools: ["query_database"] # What tools they can run+ allowed_servers: ["db-agent"] # Allowed MCP server namescustom_datalog:- 'department("analytics");' # Raw injected facts```diff --git a/site/content/docs/manifests/sam-hub.yaml b/site/content/docs/manifests/sam-hub.yamlindex 8d35a29a..7afdf99b 100644--- a/site/content/docs/manifests/sam-hub.yaml+++ b/site/content/docs/manifests/sam-hub.yaml@@ -47,7 +47,7 @@ spec:- "--mesh=public-mesh"- "--issuer=$(SAM_OIDC_ISSUER)"ports:- - containerPort: 8080+ - containerPort: 9090name: public-portenv:- name: SAM_HUB_KEY@@ -81,7 +81,7 @@ spec:app: sam-hubports:- protocol: TCP- port: 8080- targetPort: 8080+ port: 9090+ targetPort: 9090name: public-portdiff --git a/site/content/docs/user/agent-usage.md b/site/content/docs/user/agent-usage.mdindex 9e1abfc9..6bbc34dd 100644--- a/site/content/docs/user/agent-usage.md+++ b/site/content/docs/user/agent-usage.md@@ -19,13 +19,13 @@ sequenceDiagramparticipant Agent as AI Agent (Gemini/Claude)Note over User,Hub: Phase 1: Mesh Join (OIDC Authorization)- User->>Node: sam-node join --hub <hub-url>+ User->>Node: sam-node join <hub-url>Node->>Hub: Get Hub OIDC InfoHub-->>Node: OIDC Issuer, Client IDNode->>User: Display Login URL & CodeUser->>User: Login in BrowserNode->>Hub: Exchange Code for Biscuit Identity- Node->>Node: Persist Biscuit in Local Store+ Node->>Node: Persist Biscuit in Local Store (agent.db)Note over User,Agent: Phase 2: Agent Tool InvocationUser->>Node: sam-node run --api-token "secret-key"@@ -45,23 +45,23 @@ Before starting the node daemon, you must authorize your node and obtain a crypt### Standard LoginRun the `join` command, pointing to the mesh control hub:```bash-sam-node join --hub https://bananas.sam-mesh.dev+sam-node join https://bananas.sam-mesh.dev```* **Browser Flow**: The CLI will discover the OIDC credentials from the hub, print an OIDC authorization URL, and attempt to open your system's default web browser automatically.-* **Approval**: Log in with your corporate or identity credentials (e.g. Google Accounts), approve the authorization request, and return to the terminal. The node will automatically exchange the credentials for a Biscuit token and save it to `~/.config/sam-mesh/identity.json`.+* **Approval**: Log in with your corporate or identity credentials (e.g. Google Accounts), approve the authorization request, and return to the terminal. The node will automatically exchange the credentials for a Biscuit token and save it to `~/.config/sam-mesh/agent.db`.### Headless (Server) LoginIf you are running the node on a remote server via SSH (without a web browser), force headless out-of-band mode:```bash-sam-node join --hub https://bananas.sam-mesh.dev --headless+sam-node join https://bananas.sam-mesh.dev --headless```The CLI will print a verification URL and code (e.g. `https://google.com/device` and `ABCD-EFGH`). Open this URL on your local laptop, enter the code, complete the login, and the remote terminal session will activate automatically.### Automatic Token RenewalTo allow long-lived nodes to automatically renew their tokens in the background, request offline access (refreshes the OIDC session):```bash-sam-node join --hub https://bananas.sam-mesh.dev --offline-access+sam-node join https://bananas.sam-mesh.dev --offline-access```---diff --git a/site/content/docs/user/hub-configuration.md b/site/content/docs/user/hub-configuration.mdindex 1d90c39f..6b272297 100644--- a/site/content/docs/user/hub-configuration.md+++ b/site/content/docs/user/hub-configuration.md@@ -28,7 +28,7 @@ The hub is highly configurable. Each setting can be passed as a command-line fla| `--listen` | *None* | `[]` | Comma-separated libp2p multiaddrs to listen on (e.g. `/ip4/0.0.0.0/tcp/9090`). || `--bind-address` | *None* | `:9090` | Host and port to listen on for the HTTP/HTTPS admin service. || `--policy-file` | *None* | `policies.yaml` | Path to the YAML file defining authorization roles and bindings. |-| `--allowed-audiences` | *None* | `sam-audience` | Comma-separated list of allowed JWT audiences. |+| `--allowed-audiences` | *None* | `sam-mesh-audience` | Comma-separated list of allowed JWT audiences. || `--insecure-skip-tls-verify` | *None* | `false` | Set to `true` to skip certificate validation for development/testing OIDC providers. || `--keys-db` | *None* | `keys.db` | Path to the BoltDB file storing public/private keys for token validation. || `--admin-token` | *None* | *None* | Secret token string required in the HTTP Header `Authorization: Bearer <token>` for admin operations. |@@ -41,6 +41,9 @@ The hub is highly configurable. Each setting can be passed as a command-line flaThe hub dynamically issues permissions inside the Biscuit token based on identity claims (users or groups) mapped to specific roles in the policy file.+> [!IMPORTANT]+> For security reasons, wildcards (e.g. `*`) are explicitly disallowed in policy definitions. All allowed network targets and MCP servers must be explicitly listed.+### Example Policy MappingCreate a `policies.yaml` file in the directory where you run `sam-hub`:@@ -51,22 +54,25 @@ version: v1alpha1roles:developer-role:network:- allowedTargets:+ allowed_targets:- "10.0.0.0/8"- "192.168.1.0/24"mcp:- allowedServers:+ allowed_servers:- "local-shell-tools"- "git-helper"admin-role:network:- allowedTargets:+ allowed_targets:- "10.0.0.0/8"- "172.16.0.0/12"+ - "192.168.1.0/24"mcp:- allowedServers:- - "*" # Allow access to all MCP servers+ allowed_servers:+ - "local-shell-tools"+ - "git-helper"+ - "db-agent"# Bind OIDC user emails or group claims to rolesbindings: