Skip to content

Agent Mesh

sdk: follow the control plane and publish, milestone 5

Antonio Ojea0b16a9e09776
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 3c9c27aa..2e60d005 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -35,3 +35,49 @@ jobs:
args: release --clean
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ # The native SDKs (sdk/) ship with the same version as the release tag,
+ # through trusted publishing: npm and PyPI accept this workflow's OIDC
+ # token for the packages once an owner has registered it on each registry
+ # (see sdk/README.md); no publishing secret is stored in the repository.
+ publish-sdks:
+ runs-on: ubuntu-latest
+ needs: goreleaser
+ permissions:
+ contents: read
+ id-token: write
+ env:
+ SDK_VERSION: ${{ github.ref_name }}
+ steps:
+ - name: Checkout
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+ with:
+ node-version: "22"
+ registry-url: "https://registry.npmjs.org"
+ cache: npm
+ cache-dependency-path: sdk/js/package-lock.json
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: "3.12"
+ - name: Stamp the release version on both SDKs
+ run: ./hack/sdk-version.sh "${SDK_VERSION#v}"
+ - name: Build and publish @agent-mesh/sdk
+ # npm's trusted publishing needs npm 11.5 or later; Node 22 ships 10.
+ working-directory: sdk/js
+ run: |
+ npm install -g npm@latest
+ npm ci
+ npm run build
+ npm publish --provenance --access public
+ - name: Build agent-mesh
+ working-directory: sdk/python
+ run: |
+ python -m pip install --upgrade build
+ python -m build
+ - name: Publish agent-mesh
+ uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+ with:
+ packages-dir: sdk/python/dist/
diff --git a/hack/sdk-version.sh b/hack/sdk-version.sh
new file mode 100755
index 00000000..3057550c
--- /dev/null
+++ b/hack/sdk-version.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# 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.
+
+# Stamps one version on both native SDKs, so a release publishes
+# @agent-mesh/sdk and agent-mesh at the version of its tag. The release
+# workflow runs it on the tag; a developer never needs to.
+#
+# ./hack/sdk-version.sh 1.2.3
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+if [[ $# -ne 1 || ! "$1" =~ ^[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.-]+)?$ ]]; then
+ echo "usage: $0 <semver, e.g. 1.2.3>" >&2
+ exit 2
+fi
+VERSION="$1"
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "${REPO_ROOT}"
+
+# package.json and package-lock.json together; the client identity the SDK
+# presents to MCP peers follows.
+(cd sdk/js && npm version --no-git-tag-version --allow-same-version "${VERSION}" >/dev/null)
+sed -i -E "s/^(export const MCP_CLIENT_INFO = \{ name: \"agent-mesh-sdk\", version: \")[^\"]+(\" \};)$/\1${VERSION}\2/" sdk/js/src/mcp.ts
+
+sed -i -E "s/^version = \"[^\"]+\"$/version = \"${VERSION}\"/" sdk/python/pyproject.toml
+sed -i -E "s/^__version__ = \"[^\"]+\"$/__version__ = \"${VERSION}\"/" sdk/python/src/agent_mesh/__init__.py
+sed -i -E "s/^(MCP_CLIENT_INFO = mcp_types.Implementation\(name=\"agent-mesh-sdk\", version=\")[^\"]+(\"\))$/\1${VERSION}\2/" sdk/python/src/agent_mesh/mcp_client.py
+
+for f in sdk/js/package.json sdk/python/pyproject.toml sdk/python/src/agent_mesh/__init__.py sdk/js/src/mcp.ts sdk/python/src/agent_mesh/mcp_client.py; do
+ if ! grep -q "\"${VERSION}\"" "$f"; then
+ echo "ERROR: ${f} does not carry ${VERSION} after stamping" >&2
+ exit 1
+ fi
+done
+echo "SDKs stamped as ${VERSION}."
diff --git a/sdk/README.md b/sdk/README.md
index f6202914..458c363a 100644
--- a/sdk/README.md
+++ b/sdk/README.md
@@ -21,7 +21,7 @@ node and to the control plane, a `sam-node`.
## What exists today
-Milestones 1 to 4 are implemented and tested in both languages:
+Milestones 1 to 5 are implemented and tested in both languages:
| Capability | JS | Python |
| --- | --- | --- |
@@ -43,12 +43,19 @@ Milestones 1 to 4 are implemented and tested in both languages:
| `/libp2p-http` server: publish inference and A2A services, forwarded to a local URL or an in-process handler | yes | yes |
| `/libp2p-http` client: call inference and A2A services on the mesh | yes | yes |
| DHT provide with reprovide, `POST /nodes/catalog` self-report | yes | yes |
+| Control plane pull on `sam-node`'s interval: `/keys` verified against the trusted set, credential refresh after a rotation, `/info` bans and router addresses | yes | yes |
+| Gossip events from the control plane (`/sam/mesh/events/v1`, StrictSign): ban enforced at once, key rotation adopted, policy update pulls | yes | yes |
+| Banned peers refused: connections dropped and denied, handshakes and requests refused, dials refused | yes | yes |
+| Published to a registry from the release workflow | npm `@agent-mesh/sdk` | PyPI `agent-mesh` |
A member built this way is on the mesh and uses it in both directions: it
finds a service in the DHT and calls it through the router, verifying the
provider on every call, and it publishes services of its own that a
`sam-node` or another SDK member discovers and calls, authorizing every
-caller with the same Datalog the Go node evaluates.
+caller with the same Datalog the Go node evaluates. It follows the control
+plane while it runs: a ban reaches it as a gossip event within a second and
+again with the next pull, and a key rotation makes it refresh its credential
+under the new key.
Facts about the libp2p implementations that the SDKs work around, each
pinned by a test:
@@ -91,6 +98,18 @@ pinned by a test:
with `Host` set to the peer ID. The JS SDK bridges the stream to a Node
duplex and runs Node's HTTP server and client on it; the Python SDK
drives `h11` over the stream.
+- Every Go component runs GossipSub with `StrictSign`. `@libp2p/gossipsub`
+ (the libp2p-maintained package; `@chainsafe/libp2p-gossipsub` stops at
+ libp2p 2) and py-libp2p's `GossipSub` with `strict_signing=True` both
+ exchange messages with `sam-router`. py-libp2p's Pubsub learns of peers
+ through a notifee it registers when constructed, so it is built before
+ the first connection; it also opens a meshsub stream to every new peer
+ and its host logs an error for peers that do not run pubsub, which is
+ expected on a mesh with plain peers.
+- py-libp2p's connection gate is address-based, not peer-based, so the
+ Python SDK enforces a ban by disconnecting the peer and refusing its
+ handshakes, requests and dials; js-libp2p's `connectionGater` also denies
+ the connection itself, as sam-node's gater does.
## Wire contract
@@ -124,6 +143,7 @@ messages in `api/sam.proto`. Bodies are capped at 1 MiB on both sides.
| `POST /refresh` | `TokenRefreshRequest`, header `Authorization: Bearer <base64 biscuit>` | `TokenRefreshResponse` | sign `sam:refresh:<peer_id>:<ts>` |
| `GET /keys` | — | `KeysResponse` | none; see below |
| `GET /policies` | header `Authorization: Bearer <base64 biscuit>` | `PolicyConfigGetResponse{datalog_rules}` | none; the biscuit must belong to an admitted node |
+| `POST /nodes/catalog` | `NodeCatalogReport`, header `Authorization: Bearer <base64 biscuit>` | `204` | none; the reporting peer is read from the biscuit |
- `<ts>` is unix milliseconds and must be within 5 minutes of the control
plane's clock (`challengeMaxAge`). Challenges are defined in
@@ -340,14 +360,55 @@ holds against the control plane's records.
the HTTP path, then served once it presents a node-role token. About 9
seconds for the whole mesh.
-### Milestone 5 — parity and release
-
-- Control plane sync loop (`/keys`, bans, router addresses) and gossip
- event handling for bans, key rotation and policy updates.
-- Publishing: `@agent-mesh/sdk` to npm and `agent-mesh` to PyPI from the
- release workflow, versioned with the repository.
-- Docs: a guide under `site/content/docs/guides/` and the connector
- interface for platforms (issue #480).
+### Milestone 5 — parity and release (done)
+
+- Control plane pull (`session.sync()`, `mesh.syncControlPlane()`), as
+ `SyncControlPlane` in `internal/node/controlplane_sync.go`: `/keys`
+ verified against the keys already trusted, so whoever answers the URL
+ cannot become the trust root; a credential refresh when a key trusted now
+ was unknown when the credential was issued (`issuedUnderKeys` in the
+ credential file); `/info` for router addresses and the ban set,
+ reconciled with the rule that a ban recorded after the request went out
+ survives an answer that omits it; the mesh policy when serving. Runs
+ once shortly after join, then on `sam-node`'s interval with the same
+ jitter, and whenever an event triggers it.
+- Gossip events on `/sam/mesh/events/v1`: the topic validator rejects
+ anything not signed by a trusted control plane key and ignores stale
+ events; `BANNED` evicts the peer at once, `KEY_ROTATION` adopts the key
+ and triggers a pull, `POLICY_UPDATE` triggers a pull. Bans are not
+ persisted; a restarted member reads them from `/info`.
+- Ban enforcement: the auth handshake, the MCP handshake and HTTP ingress
+ refuse a banned peer before looking at its token; `connect()` refuses to
+ dial one; its connections are dropped when the ban lands.
+- Publishing: `.github/workflows/release.yml` stamps the release tag's
+ version on both packages (`hack/sdk-version.sh`) and publishes
+ `@agent-mesh/sdk` to npm and `agent-mesh` to PyPI through trusted
+ publishing. One-time setup by a package owner: on npmjs.com, add
+ `google/sam` with workflow `release.yml` as a trusted publisher of
+ `@agent-mesh/sdk`; on pypi.org, add the same repository and workflow as
+ a trusted publisher of `agent-mesh` (environment left empty). No
+ publishing token is stored in the repository.
+- Docs: `site/content/docs/guides/native-sdks.md`.
+- Tests. Unit: a fake control plane rotates its key and bans a peer; each
+ SDK learns both from a pull, refreshes under the new key and only under
+ it, drops and refuses the banned peer, and lifts the ban when the control
+ plane does; `BanSet` and `verifyMeshEvent` alone. Integration: the mesh
+ of `sdk_mesh_test.go` gets the control plane's real event publisher; an
+ enrolled Go peer admitted by every member is banned with
+ `POST /admin/revoke` and each member learns it from the gossip event
+ through the router without pulling, refuses the peer's next handshake,
+ and a pull agrees; then the control plane rotates its key and announces
+ it, and every member ends up trusting both keys, holding a credential
+ that verifies only under the new one, and still authenticating with the
+ `sam-node`.
+
+### Later
+
+- The connector interface for platforms (issue #480): `Attach`, `Detach`,
+ `Refresh`, `Status` and the agent bundle, so a scheduler places SDK
+ members the way it places `sam-box` sandboxes.
+- Reading the control plane's events also for router address changes, and
+ re-dialing a router that replaced another.
### Non-goals
@@ -382,8 +443,8 @@ both so nothing skips there. The SDK members in the mesh test are the
runners `sdk/js/src/conformance-join.ts` and
`sdk/python/src/agent_mesh/conformance_join.py`: each joins, prints what it
holds, then takes JSON commands on stdin (`auth`, `discover`, `tools`,
-`call`, `serve`, `http`, `peers`, `quit`) so the Go test can drive both
-languages through the same script.
+`call`, `serve`, `http`, `peers`, `sync`, `banned`, `quit`) so the Go test
+can drive both languages through the same script.
Interoperability facts that the tests pin: `sdk/testdata/identity_vectors.json`
holds key encodings, peer IDs and challenge signatures produced with
diff --git a/sdk/js/README.md b/sdk/js/README.md
index 43c55104..f9149278 100644
--- a/sdk/js/README.md
+++ b/sdk/js/README.md
@@ -35,7 +35,7 @@ const mesh = await AgentMesh.enroll({
console.log(mesh.peerId); // 12D3Koo...
// On the mesh: authenticated with a router, reachable through it, credential
-// kept fresh until close().
+// kept fresh, keys, bans and policy followed from the control plane until close().
const session = await mesh.join();
console.log(session.relayAddresses.map(String));
@@ -101,6 +101,9 @@ A plaintext `http://` control plane is accepted only on loopback. Pass
and the mesh policy rules from `GET /policies`.
- `src/serve.ts`: the `/sam/mcp/1.0.0` server, the `/libp2p-http` server
and client, and the service registry behind `session.serve()`.
+- `src/sync.ts`: the ban set and the control plane's gossip events;
+ `session.sync()` pulls keys, bans and router addresses as
+ `internal/node/controlplane_sync.go` does.
- `src/gen/`: generated from `api/sam.proto` and `api/datalog.go` by
`hack/gen-sdk-proto.sh`.
diff --git a/sdk/js/package-lock.json b/sdk/js/package-lock.json
index 1f18ed00..dbbe6f43 100644
--- a/sdk/js/package-lock.json
+++ b/sdk/js/package-lock.json
@@ -14,9 +14,11 @@
"@chainsafe/libp2p-yamux": "^8.0.1",
"@libp2p/circuit-relay-v2": "^4.2.13",
"@libp2p/crypto": "^5.1.23",
+ "@libp2p/gossipsub": "^17.1.2",
"@libp2p/identify": "^4.1.14",
"@libp2p/interface": "^3.3.0",
"@libp2p/kad-dht": "^16.4.5",
+ "@libp2p/peer-id": "^6.0.15",
"@libp2p/ping": "^3.1.13",
"@libp2p/tcp": "^11.0.28",
"@libp2p/tls": "^3.1.10",
@@ -219,6 +221,40 @@
"uint8arrays": "^6.0.0"
}
},
+ "node_modules/@libp2p/gossipsub": {
+ "version": "17.1.2",
+ "resolved": "http://airlock-proxy.uplink.goog:999/npm/artifact-foundry-prod/ah-3p-staging-npm/@libp2p/gossipsub/-/gossipsub-17.1.2.tgz",
+ "integrity": "sha512-XWTsNv7txlTNuHeOUfkv69aro6ioj5EKLo7plLtHbQ7NLb2rFurjxMQYgsBZ4zWF9hGRGMx9FqoJoT/zu/apiA==",
+ "license": "Apache-2.0 OR MIT",
+ "dependencies": {
+ "@libp2p/crypto": "^5.1.23",
+ "@libp2p/interface": "^3.3.0",
+ "@libp2p/interface-internal": "^3.1.13",
+ "@libp2p/peer-id": "^6.0.15",
+ "@libp2p/utils": "^7.4.1",
+ "@multiformats/multiaddr": "^13.0.3",
+ "denque": "^2.1.0",
+ "it-length-prefixed": "^11.0.1",
+ "it-pipe": "^3.0.1",
+ "it-pushable": "^3.2.3",
+ "multiformats": "^14.0.0",
+ "protons-runtime": "^7.0.0",
+ "uint8arraylist": "^3.0.2",
+ "uint8arrays": "^6.1.1"
+ },
+ "engines": {
+ "npm": ">=8.7.0"
+ }
+ },
+ "node_modules/@libp2p/gossipsub/node_modules/uint8arraylist": {
+ "version": "3.0.2",
+ "resolved": "http://airlock-proxy.uplink.goog:999/npm/artifact-foundry-prod/ah-3p-staging-npm/uint8arraylist/-/uint8arraylist-3.0.2.tgz",
+ "integrity": "sha512-LDVoq9BQaGJzGDUovEnoX6rpKCvnY/Jbtws4ikwnBzjRbq5qBAFpBZevUEbSmMM87aO0Sp+wOZy2ZXf5yODmXQ==",
+ "license": "Apache-2.0 OR MIT",
+ "dependencies": {
+ "uint8arrays": "^6.0.0"
+ }
+ },
"node_modules/@libp2p/identify": {
"version": "4.1.14",
"resolved": "http://airlock-proxy.uplink.goog:999/npm/artifact-foundry-prod/ah-3p-staging-npm/@libp2p/identify/-/identify-4.1.14.tgz",
@@ -1257,6 +1293,15 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
+ "node_modules/denque": {
+ "version": "2.1.0",
+ "resolved": "http://airlock-proxy.uplink.goog:999/npm/artifact-foundry-prod/ah-3p-staging-npm/denque/-/denque-2.1.0.tgz",
+ "integrity": "sha512-HVQE3AAb/pxF8fQAoiqpvg9i3evqug3hoiwakOyZAwJm+6vZehbkYXZ0l4JxS+I3QxM97v5aaRNhj8v5oBhekw==",
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=0.10"
+ }
+ },
"node_modules/depd": {
"version": "2.0.0",
"resolved": "http://airlock-proxy.uplink.goog:999/npm/artifact-foundry-prod/ah-3p-staging-npm/depd/-/depd-2.0.0.tgz",
diff --git a/sdk/js/package.json b/sdk/js/package.json
index ccf8834d..8a33ef53 100644
--- a/sdk/js/package.json
+++ b/sdk/js/package.json
@@ -34,9 +34,11 @@
"@chainsafe/libp2p-yamux": "^8.0.1",
"@libp2p/circuit-relay-v2": "^4.2.13",
"@libp2p/crypto": "^5.1.23",
+ "@libp2p/gossipsub": "^17.1.2",
"@libp2p/identify": "^4.1.14",
"@libp2p/interface": "^3.3.0",
"@libp2p/kad-dht": "^16.4.5",
+ "@libp2p/peer-id": "^6.0.15",
"@libp2p/ping": "^3.1.13",
"@libp2p/tcp": "^11.0.28",
"@libp2p/tls": "^3.1.10",
diff --git a/sdk/js/src/auth.ts b/sdk/js/src/auth.ts
index cb983865..ac1f266a 100644
--- a/sdk/js/src/auth.ts
+++ b/sdk/js/src/auth.ts
@@ -71,6 +71,8 @@ export interface AuthServerOptions {
/** This member's current biscuit, read per handshake so a refresh takes effect. */
ownBiscuit(): Uint8Array;
trustedKeys(): Uint8Array[];
+ /** Peers the control plane has banned; a banned peer's frame gets no answer. */
+ isBanned?(peerId: string): boolean;
/** Called with every peer that passes; the session keeps the admitted set. */
onAuthenticated?(peerId: string, verified: VerifiedBiscuit): void;
}
@@ -91,6 +93,10 @@ export function authStreamHandler(options: AuthServerOptions): StreamHandler {
try {
const lp = framed(stream);
const frame = fromBinary(AuthFrameSchema, (await lp.read({ signal })).subarray());
+ if (options.isBanned?.(peerId) === true) {
+ stream.log?.("auth handshake from %s refused: peer is revoked", peerId);
+ return;
+ }
let verified: VerifiedBiscuit;
try {
verified = await verifyPeerBiscuit(frame.biscuit, peerId, options.trustedKeys());
diff --git a/sdk/js/src/conformance-join.ts b/sdk/js/src/conformance-join.ts
index 4a8e793e..df1f5fc9 100644
--- a/sdk/js/src/conformance-join.ts
+++ b/sdk/js/src/conformance-join.ts
@@ -36,6 +36,9 @@
// "path": "/v1/models", "method": "GET", "body": "..."}
// call an HTTP service over the mesh
// {"cmd": "peers"} peers that authenticated to us
+// {"cmd": "sync"} pull keys, bans and routers from
+// the control plane now
+// {"cmd": "banned"} peers banned by the control plane
// {"cmd": "quit"} leave the mesh and exit
//
// Each command gets one JSON line back. Same environment as conformance.ts;
@@ -107,6 +110,22 @@ async function handle(session: MeshSession, command: Command): Promise<unknown>
}
case "peers":
return { cmd: "peers", authenticated_peers: [...session.authenticatedPeers.keys()].sort() };
+ case "sync": {
+ const result = await session.sync();
+ return {
+ cmd: "sync",
+ ok: result.errors.length === 0,
+ error: result.errors.join("; "),
+ keys_changed: result.keysChanged,
+ refreshed: result.refreshed,
+ trusted_keys: session.mesh.credential.controlPlaneKeys.map((k) => Buffer.from(k).toString("hex")),
+ biscuit: Buffer.from(session.mesh.credential.biscuit).toString("base64"),
+ banned: session.banned.peers(),
+ router_addresses: session.mesh.credential.routerAddresses,
+ };
+ }
+ case "banned":
+ return { cmd: "banned", ok: true, banned: session.banned.peers(), authenticated_peers: [...session.authenticatedPeers.keys()].sort() };
case "serve": {
const name = command.name ?? "";
if (command.type === "mcp") {
@@ -162,7 +181,8 @@ async function main(): Promise<void> {
const listenAddrs = (process.env.SAM_SDK_LISTEN_ADDRS ?? "").split(",").filter((a) => a !== "");
const mesh = await AgentMesh.enroll({ controlPlaneUrl, allowInsecure, stateDir, bootstrapTokenPath, pollIntervalMs: 200 });
- const session = await mesh.join({ listenAddrs, signal: AbortSignal.timeout(20_000) });
+ // The test drives every pull itself; only gossip events bring one forward.
+ const session = await mesh.join({ listenAddrs, signal: AbortSignal.timeout(20_000), controlPlaneSyncIntervalMs: 0, controlPlaneSyncJitterMs: 0 });
emit({
sdk: "js",
@@ -171,6 +191,7 @@ async function main(): Promise<void> {
relay_addresses: session.relayAddresses.map((ma) => ma.toString()),
direct_addresses: session.addresses.filter((ma) => !ma.toString().includes("/p2p-circuit")).map((ma) => ma.toString()),
biscuit: Buffer.from(mesh.credential.biscuit).toString("base64"),
+ trusted_keys: mesh.credential.controlPlaneKeys.map((k) => Buffer.from(k).toString("hex")),
});
for await (const line of createInterface({ input: process.stdin })) {
diff --git a/sdk/js/src/credential.ts b/sdk/js/src/credential.ts
index 0ed94fb6..edecd7cb 100644
--- a/sdk/js/src/credential.ts
+++ b/sdk/js/src/credential.ts
@@ -24,10 +24,23 @@ export interface MeshCredential {
expiration: number;
/** Every control plane signing key currently trusted (rotation keeps several valid). */
controlPlaneKeys: Uint8Array[];
+ /**
+ * The trusted set when the biscuit was issued. A key trusted now that was
+ * not in this set means a rotation happened since: the biscuit is signed
+ * by a retiring key and must be refreshed before that key leaves its
+ * grace period (sam-node's identityPredatesRotation).
+ */
+ issuedUnderKeys: Uint8Array[];
/** Router multiaddrs, `/p2p/<peer id>` suffixed, as handed out at enrollment. */
routerAddresses: string[];
}
+/** Whether a key trusted now was unknown when the credential was issued. */
+export function credentialPredatesRotation(c: MeshCredential): boolean {
+ const issued = new Set(c.issuedUnderKeys.map((k) => Buffer.from(k).toString("hex")));
+ return c.controlPlaneKeys.some((k) => !issued.has(Buffer.from(k).toString("hex")));
+}
+
/** Seconds of validity left on the biscuit; negative once expired. */
export function credentialTimeToLiveSeconds(c: MeshCredential, nowMs = Date.now()): number {
return c.expiration - Math.floor(nowMs / 1000);
@@ -52,6 +65,7 @@ interface CredentialJSON {
biscuit: string;
expiration: number;
control_plane_keys: string[];
+ issued_under_keys?: string[];
router_addresses: string[];
}
@@ -61,6 +75,7 @@ export function credentialToJSON(c: MeshCredential): string {
biscuit: Buffer.from(c.biscuit).toString("base64"),
expiration: c.expiration,
control_plane_keys: c.controlPlaneKeys.map((k) => Buffer.from(k).toString("base64")),
+ issued_under_keys: c.issuedUnderKeys.map((k) => Buffer.from(k).toString("base64")),
router_addresses: c.routerAddresses,
};
return JSON.stringify(out, null, 2) + "\n";
@@ -71,11 +86,14 @@ export function credentialFromJSON(text: string): MeshCredential {
if (typeof raw.control_plane_url !== "string" || typeof raw.biscuit !== "string" || typeof raw.expiration !== "number") {
throw new Error("malformed credential file");
}
+ const controlPlaneKeys = (raw.control_plane_keys ?? []).map((k) => new Uint8Array(Buffer.from(k, "base64")));
return {
controlPlaneUrl: raw.control_plane_url,
biscuit: new Uint8Array(Buffer.from(raw.biscuit, "base64")),
expiration: raw.expiration,
- controlPlaneKeys: (raw.control_plane_keys ?? []).map((k) => new Uint8Array(Buffer.from(k, "base64"))),
+ controlPlaneKeys,
+ // A file from before this field: the set known then is the best answer.
+ issuedUnderKeys: raw.issued_under_keys !== undefined ? raw.issued_under_keys.map((k) => new Uint8Array(Buffer.from(k, "base64"))) : controlPlaneKeys,
routerAddresses: raw.router_addresses ?? [],
};
}
diff --git a/sdk/js/src/host.ts b/sdk/js/src/host.ts
index a9df2ba8..70f4946f 100644
--- a/sdk/js/src/host.ts
+++ b/sdk/js/src/host.ts
@@ -20,8 +20,9 @@
import { yamux } from "@chainsafe/libp2p-yamux";
import { circuitRelayTransport } from "@libp2p/circuit-relay-v2";
import { privateKeyFromProtobuf } from "@libp2p/crypto/keys";
+import { gossipsub, type GossipSub } from "@libp2p/gossipsub";
import { identify } from "@libp2p/identify";
-import type { Libp2p } from "@libp2p/interface";
+import type { Libp2p, PeerId } from "@libp2p/interface";
import { kadDHT, passthroughMapper } from "@libp2p/kad-dht";
import { ping } from "@libp2p/ping";
import { tcp } from "@libp2p/tcp";
@@ -37,15 +38,31 @@ export interface MeshHostOptions {
* Empty by default: an agent is reached through a router's relay.
*/
listenAddrs?: string[];
+ /**
+ * Peers the control plane has banned. Consulted for every dial and every
+ * inbound connection, as sam-node's connection gater; the session keeps
+ * it current from /info and the gossip events.
+ */
+ banned?: { has(peerId: string): boolean };
}
-export async function createMeshHost(identity: Identity, options: MeshHostOptions = {}): Promise<Libp2p> {
+/** The services a mesh host runs; `services.pubsub` carries the control plane's events. */
+export type MeshHost = Libp2p<{ pubsub: GossipSub }>;
+
+export async function createMeshHost(identity: Identity, options: MeshHostOptions = {}): Promise<MeshHost> {
+ const banned = options.banned ?? { has: () => false };
+ const denyBanned = (peerId: PeerId) => banned.has(peerId.toString());
return createLibp2p({
privateKey: privateKeyFromProtobuf(identity.toLibp2pPrivateKey()),
addresses: { listen: options.listenAddrs ?? [] },
transports: [tcp(), circuitRelayTransport()],
connectionEncrypters: [tls()],
streamMuxers: [yamux()],
+ connectionGater: {
+ denyDialPeer: denyBanned,
+ denyInboundEncryptedConnection: denyBanned,
+ denyInboundRelayedConnection: (_relay, remotePeer) => denyBanned(remotePeer),
+ },
services: {
identify: identify(),
ping: ping(),
@@ -53,6 +70,10 @@ export async function createMeshHost(identity: Identity, options: MeshHostOption
// records. Peers keep their private addresses; a mesh member often
// is one, and the router relays to it.
dht: kadDHT({ protocol: DHT_PROTOCOL, clientMode: true, peerInfoMapper: passthroughMapper }),
+ // The control plane's events reach members through the routers.
+ // StrictSign, as every Go component pins it: the pubsub envelope is
+ // signed by the author, and the event inside by the control plane.
+ pubsub: gossipsub({ globalSignaturePolicy: "StrictSign", allowPublishToZeroTopicPeers: true, emitSelf: false }),
},
});
}
diff --git a/sdk/js/src/index.ts b/sdk/js/src/index.ts
index 0fa7eacc..37140837 100644
--- a/sdk/js/src/index.ts
+++ b/sdk/js/src/index.ts
@@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-export { AgentMesh, type AgentMeshOptions, type EnrollOptions } from "./mesh.ts";
+export { AgentMesh, type AgentMeshOptions, type ControlPlaneSync, type EnrollOptions } from "./mesh.ts";
export { Identity, peerIdFromPublicKey, libp2pPublicKey, verifyEd25519 } from "./identity.ts";
export {
ControlPlaneClient,
@@ -41,7 +41,7 @@ export { enrollChallenge, enrollStatusChallenge, refreshChallenge, registerChall
export { MeshSession, type AdmittedRouter, type DiscoveredProvider, type JoinOptions, type ToolCallResult } from "./session.ts";
export { BiscuitVerificationError, ROLE_ROUTER, requireRole, verifyPeerBiscuit, type VerifiedBiscuit } from "./biscuit.ts";
export { AUTH_HANDLER_OPTIONS, AUTH_PROTOCOL, MCP_PROTOCOL, AuthRejectedError, authenticateWithPeer, authStreamHandler } from "./auth.ts";
-export { createMeshHost, type MeshHostOptions } from "./host.ts";
+export { createMeshHost, type MeshHost, type MeshHostOptions } from "./host.ts";
export { DHT_PROTOCOL, parseServiceTarget, serviceCID, type ServiceType } from "./discovery.ts";
export { LabelsNotSatisfiedError, StreamTransport, openMCPSession, requireLabels, type MCPSession, type MCPSessionOptions } from "./mcp.ts";
export { AuthorizationError, authorizeCaller, type AuthorizeRequest, type ProviderAuthorizerOptions } from "./authorizer.ts";
@@ -63,3 +63,4 @@ export {
type ServiceSpec,
} from "./serve.ts";
export { BASELINE_DATALOG } from "./gen/datalog.ts";
+export { BanSet, EVENT_FRESHNESS_MS, GOSSIP_EVENTS_TOPIC, verifyMeshEvent } from "./sync.ts";
diff --git a/sdk/js/src/mesh.ts b/sdk/js/src/mesh.ts
index 2b7162dc..225987ef 100644
--- a/sdk/js/src/mesh.ts
+++ b/sdk/js/src/mesh.ts
@@ -15,7 +15,7 @@
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { ControlPlaneClient, ROLE_NODE, type Enrollment } from "./controlplane.ts";
-import { credentialFromJSON, credentialToJSON, encodeAuthFrame, type MeshCredential } from "./credential.ts";
+import { credentialFromJSON, credentialPredatesRotation, credentialToJSON, encodeAuthFrame, type MeshCredential } from "./credential.ts";
import { Identity } from "./identity.ts";
import { joinMesh, type JoinOptions, type MeshSession } from "./session.ts";
@@ -55,6 +55,20 @@ export interface EnrollOptions extends AgentMeshOptions {
pollIntervalMs?: number;
}
+/** What one pull from the control plane changed. */
+export interface ControlPlaneSync {
+ /** The trusted key set differs from before the pull. */
+ keysChanged: boolean;
+ /** The credential was re-issued because a rotation had happened since. */
+ refreshed: boolean;
+ /** The control plane's ban set, when /info answered. */
+ bannedPeerIds: string[] | undefined;
+ /** When /info was asked; a ban recorded later cannot be in the answer. */
+ fetchedAt: Date;
+ /** One entry per part that failed; empty when everything landed. */
+ errors: string[];
+}
+
/**
* A member of the mesh: an identity, the credential the control plane minted
* for it, and the client that keeps that credential fresh. join() puts it on
@@ -127,6 +141,7 @@ export class AgentMesh {
biscuit: enrollment.biscuit,
expiration: enrollment.expiration,
controlPlaneKeys,
+ issuedUnderKeys: controlPlaneKeys,
routerAddresses: enrollment.routerAddresses,
},
options.stateDir,
@@ -158,11 +173,71 @@ export class AgentMesh {
} catch {
// Keep the previous set; a failed /keys sync must not cost the new biscuit.
}
- this.#credential = { ...this.#credential, biscuit: result.biscuit, expiration: result.expiration, controlPlaneKeys };
+ this.#credential = { ...this.#credential, biscuit: result.biscuit, expiration: result.expiration, controlPlaneKeys, issuedUnderKeys: controlPlaneKeys };
await this.save();
return this.#credential;
}
+ /**
+ * Adopts a signing key announced by a KEY_ROTATION event, so peers whose
+ * credentials the new key signs verify before the next pull confirms it.
+ */
+ addTrustedKey(key: Uint8Array): boolean {
+ const hex = Buffer.from(key).toString("hex");
+ if (this.#credential.controlPlaneKeys.some((k) => Buffer.from(k).toString("hex") === hex)) {
+ return false;
+ }
+ this.#credential = { ...this.#credential, controlPlaneKeys: [...this.#credential.controlPlaneKeys, key] };
+ return true;
+ }
+
+ /**
+ * The member's pull from the control plane, as sam-node's SyncControlPlane:
+ * the signing keys (verified against the set already trusted, so whoever
+ * answers the URL cannot become the trust root), a credential refresh when
+ * a rotation happened since it was issued, and /info for the router
+ * addresses and the ban set. Each part is attempted even when another
+ * fails; the errors are reported together. Gossip events only bring this
+ * forward; they are never the only way state arrives.
+ */
+ async syncControlPlane(): Promise<ControlPlaneSync> {
+ const errors: string[] = [];
+ let keysChanged = false;
+ let refreshed = false;
+ try {
+ const keys = await this.controlPlane.keys(this.#credential.controlPlaneKeys);
+ if (keys.length === 0) {
+ throw new Error("/keys returned no keys");
+ }
+ keysChanged = !sameKeySet(keys, this.#credential.controlPlaneKeys);
+ this.#credential = { ...this.#credential, controlPlaneKeys: keys };
+ if (credentialPredatesRotation(this.#credential)) {
+ await this.refresh();
+ refreshed = true;
+ }
+ } catch (err) {
+ errors.push(`keys: ${err instanceof Error ? err.message : String(err)}`);
+ }
+
+ let bannedPeerIds: string[] | undefined;
+ // Taken before the request: a ban recorded after this instant cannot be
+ // in the answer, so its absence must not be read as an unban.
+ const fetchedAt = new Date();
+ try {
+ const info = await this.controlPlane.info();
+ if (info.routerAddresses.length > 0) {
+ this.#credential = { ...this.#credential, routerAddresses: info.routerAddresses };
+ }
+ bannedPeerIds = info.bannedPeerIds;
+ } catch (err) {
+ errors.push(`info: ${err instanceof Error ? err.message : String(err)}`);
+ }
+ if (keysChanged || bannedPeerIds !== undefined) {
+ await this.save();
+ }
+ return { keysChanged, refreshed, bannedPeerIds, fetchedAt, errors };
+ }
+
/**
* The frame that opens every stream to a peer: this member's biscuit plus
* the service it wants (e.g. "mcp://calculator") and the agent it speaks for.
@@ -199,6 +274,15 @@ function newClient(options: AgentMeshOptions): ControlPlaneClient {
});
}
+function sameKeySet(a: Uint8Array[], b: Uint8Array[]): boolean {
+ const hex = (keys: Uint8Array[]) =>
+ keys
+ .map((k) => Buffer.from(k).toString("hex"))
+ .sort()
+ .join(",");
+ return hex(a) === hex(b);
+}
+
function labelsOf(options: AgentMeshOptions): { labels?: Record<string, string> } {
return options.labels !== undefined ? { labels: options.labels } : {};
}
diff --git a/sdk/js/src/serve.ts b/sdk/js/src/serve.ts
index dddcb8ce..fe017c69 100644
--- a/sdk/js/src/serve.ts
+++ b/sdk/js/src/serve.ts
@@ -135,6 +135,8 @@ export function streamToNodeDuplex(stream: Stream, remotePeer: string): StreamSo
export interface ProviderOptions extends ProviderAuthorizerOptions {
/** This provider's current biscuit, for the mutual AuthResponse. */
ownBiscuit(): Uint8Array;
+ /** Peers the control plane has banned; refused before their token is looked at. */
+ isBanned?(peerId: string): boolean;
/** Called after a caller is authorized for a service, e.g. for the session's admitted set. */
onAuthorized?(peerId: string, verified: VerifiedBiscuit, targetService: string): void;
}
@@ -189,6 +191,10 @@ export function mcpStreamHandler(registry: ServiceRegistry, options: ProviderOpt
try {
const lp = lpStream(stream, { maxDataLength: MAX_AUTH_FRAME_BYTES });
const frame = fromBinary(AuthFrameSchema, (await lp.read({ signal })).subarray());
+ if (options.isBanned?.(peerId) === true) {
+ await refuse(stream, peerId, "peer is revoked", signal);
+ return;
+ }
let verified: VerifiedBiscuit;
try {
verified = await authorizeCaller({ biscuit: frame.biscuit, peerId, targetService: frame.targetService, protocol, agent: frame.agent }, options);
@@ -336,6 +342,10 @@ async function handleIngress(req: http.IncomingMessage, res: http.ServerResponse
}
const targetService = `${serviceType}://${serviceName}`;
+ if (options.isBanned?.(remotePeer) === true) {
+ reply(403, "Authorization failed");
+ return;
+ }
const agentHeader = req.headers[HEADER_SAM_AGENT];
let verified: VerifiedBiscuit;
try {
diff --git a/sdk/js/src/session.ts b/sdk/js/src/session.ts
index 631af062..f3f0ca61 100644
--- a/sdk/js/src/session.ts
+++ b/sdk/js/src/session.ts
@@ -12,14 +12,16 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-import type { Connection, Libp2p } from "@libp2p/interface";
+import type { Connection } from "@libp2p/interface";
+import { TopicValidatorResult } from "@libp2p/gossipsub";
+import { peerIdFromString } from "@libp2p/peer-id";
import { multiaddr, type Multiaddr } from "@multiformats/multiaddr";
import { AUTH_HANDLER_OPTIONS, AUTH_PROTOCOL, MCP_PROTOCOL, authenticateWithPeer, authStreamHandler } from "./auth.ts";
import { ROLE_ROUTER, requireRole, type VerifiedBiscuit } from "./biscuit.ts";
import { serviceCID, type ServiceType } from "./discovery.ts";
-import { createMeshHost, listenThroughRelay, type MeshHostOptions } from "./host.ts";
+import { createMeshHost, listenThroughRelay, type MeshHost, type MeshHostOptions } from "./host.ts";
import { openMCPSession, type MCPSession, type MCPSessionOptions } from "./mcp.ts";
-import type { AgentMesh } from "./mesh.ts";
+import type { AgentMesh, ControlPlaneSync } from "./mesh.ts";
import {
HTTP_PROTOCOL,
SERVE_HANDLER_OPTIONS,
@@ -33,6 +35,7 @@ import {
type ServedService,
type ServiceSpec,
} from "./serve.ts";
+import { BanSet, GOSSIP_EVENTS_TOPIC, MeshEvent_Type, verifyMeshEvent } from "./sync.ts";
export interface JoinOptions extends MeshHostOptions {
/**
@@ -49,6 +52,14 @@ export interface JoinOptions extends MeshHostOptions {
policySyncIntervalMs?: number;
/** How often published services are re-announced in the DHT. */
provideIntervalMs?: number;
+ /**
+ * How often keys, bans and router addresses are pulled from the control
+ * plane (sam-node's --control-plane-sync-interval). Gossip events bring a
+ * pull forward; 0 disables the loop.
+ */
+ controlPlaneSyncIntervalMs?: number;
+ /** Upper bound of the random delay before a pull an event triggered. */
+ controlPlaneSyncJitterMs?: number;
/** Bounds the whole join. */
signal?: AbortSignal;
}
@@ -84,6 +95,10 @@ const MIN_REFRESH_DELAY_MS = 2_000;
const DEFAULT_POLICY_SYNC_MS = 15 * 60 * 1000;
/** How often provider records are refreshed; go-libp2p-kad-dht expires them after 48h. */
const DEFAULT_PROVIDE_INTERVAL_MS = 10 * 60 * 1000;
+/** sam-node's --control-plane-sync-interval default, and its 2s first pull. */
+const DEFAULT_CONTROL_PLANE_SYNC_MS = 15 * 60 * 1000;
+const FIRST_CONTROL_PLANE_SYNC_MS = 2_000;
+const DEFAULT_CONTROL_PLANE_SYNC_JITTER_MS = 2_000;
/**
* A member that is on the mesh: a libp2p host authenticated with at least
@@ -92,33 +107,46 @@ const DEFAULT_PROVIDE_INTERVAL_MS = 10 * 60 * 1000;
*/
export class MeshSession {
readonly mesh: AgentMesh;
- readonly node: Libp2p;
+ readonly node: MeshHost;
readonly routers: AdmittedRouter[];
/** Peers that passed the inbound auth handshake, with their credential's expiration. */
readonly authenticatedPeers: Map<string, Date>;
+ /** Peers the control plane has banned; connections to and from them are refused. */
+ readonly banned: BanSet;
/** The services this member publishes. */
readonly services = new ServiceRegistry();
#refreshTimer: ReturnType<typeof setTimeout> | undefined;
#policyTimer: ReturnType<typeof setInterval> | undefined;
#provideTimer: ReturnType<typeof setInterval> | undefined;
+ #syncTimer: ReturnType<typeof setTimeout> | undefined;
+ #syncing: Promise<ControlPlaneSync> | undefined;
readonly #refreshLeadMs: number;
readonly #refreshRetryMs: number;
readonly #policySyncMs: number;
readonly #provideIntervalMs: number;
+ readonly #syncIntervalMs: number;
+ readonly #syncJitterMs: number;
#policyRules: string[] | undefined;
#serving = false;
#closed = false;
- constructor(mesh: AgentMesh, node: Libp2p, routers: AdmittedRouter[], authenticatedPeers: Map<string, Date>, options: JoinOptions) {
+ constructor(mesh: AgentMesh, node: MeshHost, routers: AdmittedRouter[], authenticatedPeers: Map<string, Date>, banned: BanSet, options: JoinOptions) {
this.mesh = mesh;
this.node = node;
this.routers = routers;
this.authenticatedPeers = authenticatedPeers;
+ this.banned = banned;
this.#refreshLeadMs = options.refreshLeadMs ?? DEFAULT_REFRESH_LEAD_MS;
this.#refreshRetryMs = options.refreshRetryMs ?? DEFAULT_REFRESH_RETRY_MS;
this.#policySyncMs = options.policySyncIntervalMs ?? DEFAULT_POLICY_SYNC_MS;
this.#provideIntervalMs = options.provideIntervalMs ?? DEFAULT_PROVIDE_INTERVAL_MS;
+ this.#syncIntervalMs = options.controlPlaneSyncIntervalMs ?? DEFAULT_CONTROL_PLANE_SYNC_MS;
+ this.#syncJitterMs = options.controlPlaneSyncJitterMs ?? DEFAULT_CONTROL_PLANE_SYNC_JITTER_MS;
this.#scheduleRefresh();
+ this.#listenForEvents();
+ if (this.#syncIntervalMs > 0) {
+ this.#scheduleSync(Math.min(FIRST_CONTROL_PLANE_SYNC_MS, this.#syncIntervalMs));
+ }
}
get peerId(): string {
@@ -138,9 +166,14 @@ export class MeshSession {
/**
* Connects to a peer by address; a `/p2p-circuit` address goes through
* the named relay. Returns the connection, reused if one is already open.
+ * A banned peer is refused here and by the connection gater.
*/
connect(addr: string | Multiaddr, signal?: AbortSignal): Promise<Connection> {
const ma = typeof addr === "string" ? multiaddr(addr) : addr;
+ const target = ma.getComponents().findLast((c) => c.name === "p2p")?.value;
+ if (target !== undefined && this.banned.has(target)) {
+ return Promise.reject(new Error(`peer ${target} is banned by the control plane`));
+ }
return this.node.dial(ma, signal !== undefined ? { signal } : {});
}
@@ -228,6 +261,111 @@ export class MeshSession {
this.#scheduleRefresh();
}
+ /**
+ * Pulls keys, bans and router addresses from the control plane now, and
+ * the mesh policy when serving, then applies them: a newly banned peer is
+ * hung up on and dropped from the admitted set. Concurrent calls share
+ * one pull. Errors of individual parts are in the result, not thrown.
+ */
+ sync(): Promise<ControlPlaneSync> {
+ this.#syncing ??= this.#syncOnce().finally(() => {
+ this.#syncing = undefined;
+ });
+ return this.#syncing;
+ }
+
+ async #syncOnce(): Promise<ControlPlaneSync> {
+ const result = await this.mesh.syncControlPlane();
+ if (result.bannedPeerIds !== undefined) {
+ const { banned } = this.banned.reconcile(result.bannedPeerIds, result.fetchedAt);
+ await Promise.all(banned.map((peerId) => this.#evict(peerId)));
+ }
+ if (this.#serving) {
+ try {
+ await this.syncPolicy();
+ } catch (err) {
+ result.errors.push(`policy: ${err instanceof Error ? err.message : String(err)}`);
+ }
+ }
+ return result;
+ }
+
+ /** Asks for a pull soon, after a random delay so a fleet told at once does not pull at once. */
+ triggerSync(): void {
+ if (this.#closed) {
+ return;
+ }
+ this.#scheduleSync(Math.floor(Math.random() * (this.#syncJitterMs + 1)));
+ }
+
+ #scheduleSync(delayMs: number): void {
+ clearTimeout(this.#syncTimer);
+ this.#syncTimer = setTimeout(() => {
+ this.sync()
+ .catch(() => {})
+ .finally(() => {
+ if (!this.#closed && this.#syncIntervalMs > 0) {
+ // Stretched by up to a tenth so a fleet started together does not pull together.
+ this.#scheduleSync(this.#syncIntervalMs + Math.floor(Math.random() * (this.#syncIntervalMs / 10 + 1)));
+ }
+ });
+ }, delayMs);
+ this.#syncTimer.unref?.();
+ }
+
+ /** Drops a banned peer: its admission and its connections. */
+ async #evict(peerId: string): Promise<void> {
+ this.authenticatedPeers.delete(peerId);
+ try {
+ await this.node.hangUp(peerIdFromString(peerId));
+ } catch {
+ // Not connected, or already gone.
+ }
+ }
+
+ /**
+ * The control plane's gossip events, relayed by the routers. The topic
+ * validator drops anything not signed by a trusted control plane key, so
+ * a peer whose libp2p key signed the envelope still cannot get an
+ * unsigned event through; a stale event is ignored, not penalized.
+ */
+ #listenForEvents(): void {
+ const pubsub = this.node.services.pubsub;
+ pubsub.topicValidators.set(GOSSIP_EVENTS_TOPIC, (_peer, message) => {
+ if (message.type !== "signed") {
+ return TopicValidatorResult.Reject;
+ }
+ return verifyMeshEvent(message.data, this.mesh.credential.controlPlaneKeys) !== undefined ? TopicValidatorResult.Accept : TopicValidatorResult.Reject;
+ });
+ pubsub.addEventListener("message", (evt) => {
+ if (evt.detail.topic !== GOSSIP_EVENTS_TOPIC) {
+ return;
+ }
+ const event = verifyMeshEvent(evt.detail.data, this.mesh.credential.controlPlaneKeys);
+ if (event === undefined) {
+ return;
+ }
+ switch (event.type) {
+ case MeshEvent_Type.BANNED:
+ // Not persisted: a restarted member picks the ban back up from /info.
+ if (this.banned.add(event.peerId, Number(event.timestamp))) {
+ void this.#evict(event.peerId);
+ }
+ break;
+ case MeshEvent_Type.KEY_ROTATION:
+ if (event.newPublicKey.length === 32) {
+ this.mesh.addTrustedKey(event.newPublicKey);
+ }
+ this.triggerSync();
+ break;
+ case MeshEvent_Type.POLICY_UPDATE:
+ this.triggerSync();
+ break;
+ }
+ });
+ pubsub.subscribe(GOSSIP_EVENTS_TOPIC);
+ }
+
/**
* The mesh policy rules this member evaluates for callers, as the control
* plane rendered them (PolicyConfigGetResponse.datalog_rules). Empty until
@@ -265,6 +403,7 @@ export class MeshSession {
trustedKeys: () => this.mesh.credential.controlPlaneKeys,
ownBiscuit: () => this.mesh.credential.biscuit,
policyRules: () => this.policyRules,
+ isBanned: (peerId) => this.banned.has(peerId),
onAuthorized: (peerId, verified) => this.authenticatedPeers.set(peerId, verified.expiration),
};
await this.node.handle(MCP_PROTOCOL, mcpStreamHandler(this.services, providerOptions, MCP_PROTOCOL), SERVE_HANDLER_OPTIONS);
@@ -337,6 +476,7 @@ export class MeshSession {
async close(): Promise<void> {
this.#closed = true;
clearTimeout(this.#refreshTimer);
+ clearTimeout(this.#syncTimer);
clearInterval(this.#policyTimer);
clearInterval(this.#provideTimer);
await this.node.stop();
@@ -350,7 +490,8 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom
throw new Error("credential lists no router addresses; the control plane had no active router at enrollment");
}
- const node = await createMeshHost(mesh.identity, options);
+ const banned = new BanSet();
+ const node = await createMeshHost(mesh.identity, { ...options, banned });
const admitted: AdmittedRouter[] = [];
const authenticatedPeers = new Map<string, Date>();
try {
@@ -359,6 +500,7 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom
authStreamHandler({
ownBiscuit: () => mesh.credential.biscuit,
trustedKeys: () => mesh.credential.controlPlaneKeys,
+ isBanned: (peerId) => banned.has(peerId),
onAuthenticated: (peerId, verified) => authenticatedPeers.set(peerId, verified.expiration),
}),
AUTH_HANDLER_OPTIONS,
@@ -394,5 +536,5 @@ export async function joinMesh(mesh: AgentMesh, options: JoinOptions = {}): Prom
throw err;
}
- return new MeshSession(mesh, node, admitted, authenticatedPeers, options);
+ return new MeshSession(mesh, node, admitted, authenticatedPeers, banned, options);
}
diff --git a/sdk/js/src/sync.test.ts b/sdk/js/src/sync.test.ts
new file mode 100644
index 00000000..15f6594b
--- /dev/null
+++ b/sdk/js/src/sync.test.ts
@@ -0,0 +1,286 @@
+// 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.
+
+// What a joined member keeps in step with the control plane: a fake control
+// plane behind fetch rotates its key and bans a peer; the member learns both
+// from a pull, refreshes its credential under the new key, and refuses the
+// banned peer at the gate and at the handshake. The real control plane and
+// router are exercised by tests/integration/sdk_mesh_test.go.
+
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { circuitRelayServer, circuitRelayTransport } from "@libp2p/circuit-relay-v2";
+import { privateKeyFromProtobuf } from "@libp2p/crypto/keys";
+import { identify } from "@libp2p/identify";
+import type { Libp2p } from "@libp2p/interface";
+import { tcp } from "@libp2p/tcp";
+import { tls } from "@libp2p/tls";
+import { createLibp2p } from "libp2p";
+import assert from "node:assert/strict";
+import { after, before, test } from "node:test";
+import { AUTH_PROTOCOL, authenticateWithPeer, authStreamHandler } from "./auth.ts";
+import { ROLE_ROUTER, loadBiscuit, verifyPeerBiscuit } from "./biscuit.ts";
+import { ROLE_NODE } from "./controlplane.ts";
+import { credentialPredatesRotation } from "./credential.ts";
+import {
+ AuthFrameSchema,
+ BootstrapEnrollRequestSchema,
+ BootstrapEnrollResponseSchema,
+ ControlPlaneInfoResponseSchema,
+ EnrollmentStatus,
+ KeysResponseSchema,
+ MeshEvent_Type,
+ MeshEventSchema,
+ TokenRefreshResponseSchema,
+} from "./gen/sam_pb.ts";
+import { Identity } from "./identity.ts";
+import { AgentMesh } from "./mesh.ts";
+import { BanSet, EVENT_FRESHNESS_MS, verifyMeshEvent } from "./sync.ts";
+
+type Wasm = Awaited<ReturnType<typeof loadBiscuit>>;
+
+let wasm: Wasm;
+let router: Libp2p;
+let routerAddr: string;
+
+/** One ed25519 key usable both as a biscuit root and for plain signatures. */
+class SigningKey {
+ readonly biscuit: InstanceType<Wasm["KeyPair"]>;
+ readonly identity: Identity;
+ constructor() {
+ this.biscuit = new wasm.KeyPair(wasm.SignatureAlgorithm.Ed25519);
+ this.identity = Identity.fromSeed(new Uint8Array(Buffer.from(this.biscuit.getPrivateKey().toString().replace(/^ed25519-private\//, ""), "hex")));
+ }
+ get pub(): Uint8Array {
+ return this.identity.publicKeyRaw;
+ }
+ mint(peerId: string, role: string): Uint8Array {
+ const b = wasm.Biscuit.builder();
+ b.addFact(wasm.Fact.fromString(`node(${JSON.stringify(peerId)})`));
+ b.addFact(wasm.Fact.fromString("expiration(2035-01-01T00:00:00Z)"));
+ b.addFact(wasm.Fact.fromString(`role(${JSON.stringify(role)})`));
+ return b.build(this.biscuit.getPrivateKey()).toBytes();
+ }
+}
+
+/** A control plane whose key set, ban set and issuing key the test changes. */
+class FakeControlPlane {
+ keys: SigningKey[];
+ banned: string[] = [];
+ refreshes = 0;
+ constructor(initial: SigningKey) {
+ this.keys = [initial];
+ }
+ /** The key credentials are minted with: the newest. */
+ get current(): SigningKey {
+ return this.keys[this.keys.length - 1] as SigningKey;
+ }
+ get fetch(): typeof fetch {
+ return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+ const req = new Request(input, init);
+ const path = new URL(req.url).pathname;
+ const proto = (bytes: Uint8Array) => new Response(Buffer.from(bytes), { status: 200, headers: { "Content-Type": "application/x-protobuf" } });
+ if (req.method === "POST" && path === "/enroll") {
+ const enroll = fromBinary(BootstrapEnrollRequestSchema, new Uint8Array(await req.arrayBuffer()));
+ return proto(
+ toBinary(
+ BootstrapEnrollResponseSchema,
+ create(BootstrapEnrollResponseSchema, {
+ status: EnrollmentStatus.APPROVED,
+ biscuitToken: this.current.mint(enroll.peerId, ROLE_NODE),
+ controlPlanePublicKey: this.current.pub,
+ routerAddresses: [routerAddr],
+ expiration: BigInt(Math.floor(Date.now() / 1000) + 3600),
+ }),
+ ),
+ );
+ }
+ if (req.method === "GET" && path === "/keys") {
+ // Signed as api.VerifyKeysResponse expects: each key over the set with signatures cleared.
+ const unsigned = create(KeysResponseSchema, { publicKeys: this.keys.map((k) => k.pub), timestamp: BigInt(Date.now()) });
+ const payload = toBinary(KeysResponseSchema, unsigned);
+ return proto(toBinary(KeysResponseSchema, create(KeysResponseSchema, { ...unsigned, signatures: this.keys.map((k) => k.identity.sign(payload)) })));
+ }
+ if (req.method === "GET" && path === "/info") {
+ return proto(toBinary(ControlPlaneInfoResponseSchema, create(ControlPlaneInfoResponseSchema, { routerAddresses: [routerAddr], bannedPeerIds: this.banned })));
+ }
+ if (req.method === "POST" && path === "/refresh") {
+ this.refreshes++;
+ // The peer is whoever the presented biscuit is bound to; every valid key is tried.
+ const presented = new Uint8Array(Buffer.from((req.headers.get("Authorization") ?? "").replace(/^Bearer /, ""), "base64"));
+ let peerId: string | undefined;
+ for (const key of this.keys) {
+ try {
+ const token = wasm.Biscuit.fromBytes(presented, wasm.PublicKey.fromBytes(key.pub, wasm.SignatureAlgorithm.Ed25519));
+ const b = new wasm.AuthorizerBuilder();
+ b.addPolicy(wasm.Policy.fromString("allow if true"));
+ const facts = b.buildAuthenticated(token).query(wasm.Rule.fromString("p($p) <- node($p)"));
+ peerId = facts[0]?.terms()[0] as string;
+ break;
+ } catch {
+ // try the next key
+ }
+ }
+ if (peerId === undefined) {
+ return new Response("unverifiable biscuit", { status: 401 });
+ }
+ return proto(
+ toBinary(
+ TokenRefreshResponseSchema,
+ create(TokenRefreshResponseSchema, { biscuitToken: this.current.mint(peerId, ROLE_NODE), expiresAt: BigInt(Math.floor(Date.now() / 1000) + 7200) }),
+ ),
+ );
+ }
+ return new Response(`no route for ${req.method} ${path}`, { status: 404 });
+ }) as typeof fetch;
+ }
+}
+
+let cp: FakeControlPlane;
+
+before(async () => {
+ wasm = await loadBiscuit();
+ cp = new FakeControlPlane(new SigningKey());
+ router = await createLibp2p({
+ addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] },
+ transports: [tcp()],
+ connectionEncrypters: [tls()],
+ streamMuxers: [yamux()],
+ services: { identify: identify(), relay: circuitRelayServer() },
+ });
+ const routerBiscuit = cp.current.mint(router.peerId.toString(), ROLE_ROUTER);
+ await router.handle(AUTH_PROTOCOL, authStreamHandler({ ownBiscuit: () => routerBiscuit, trustedKeys: () => cp.keys.map((k) => k.pub) }));
+ routerAddr = router.getMultiaddrs()[0]!.toString();
+});
+
+after(async () => {
+ await router.stop();
+});
+
+test("a ban learned after the answer was requested survives an answer that omits it", () => {
+ const bans = new BanSet();
+ const t0 = new Date("2026-09-24T10:00:00Z");
+ const t1 = new Date(t0.getTime() + 1000);
+ assert.deepEqual(bans.reconcile(["A", "B"], t0), { banned: ["A", "B"], unbanned: [] });
+ // A gossip event bans C after t1's request went out; t1's answer cannot speak to it.
+ assert.ok(bans.add("C", t1.getTime() + 500));
+ assert.deepEqual(bans.reconcile(["A"], t1), { banned: [], unbanned: ["B"] });
+ assert.deepEqual(bans.peers(), ["A", "C"]);
+ // A later answer without C lifts it.
+ assert.deepEqual(bans.reconcile(["A"], new Date(t1.getTime() + 2000)), { banned: [], unbanned: ["C"] });
+ assert.ok(!bans.add("A", 1), "an existing ban is not re-added");
+});
+
+test("a mesh event verifies only under a trusted key and only when fresh", () => {
+ const key = new SigningKey();
+ const sign = (event: ReturnType<typeof create<typeof MeshEventSchema>>) => {
+ const unsigned = toBinary(MeshEventSchema, { ...event, signature: new Uint8Array() });
+ return toBinary(MeshEventSchema, { ...event, signature: key.identity.sign(unsigned) });
+ };
+ const now = new Date();
+ const banned = sign(create(MeshEventSchema, { type: MeshEvent_Type.BANNED, peerId: "12D3KooWx", timestamp: BigInt(now.getTime()) }));
+ assert.equal(verifyMeshEvent(banned, [key.pub], now)?.peerId, "12D3KooWx");
+ assert.equal(verifyMeshEvent(banned, [new SigningKey().pub], now), undefined, "untrusted key");
+ const tampered = new Uint8Array(banned);
+ tampered[tampered.length - 1] = (tampered[tampered.length - 1] ?? 0) ^ 1;
+ assert.equal(verifyMeshEvent(tampered, [key.pub], now), undefined, "tampered signature");
+ const stale = sign(create(MeshEventSchema, { type: MeshEvent_Type.BANNED, peerId: "12D3KooWx", timestamp: BigInt(now.getTime() - EVENT_FRESHNESS_MS - 1) }));
+ assert.equal(verifyMeshEvent(stale, [key.pub], now), undefined, "stale");
+ assert.equal(verifyMeshEvent(new Uint8Array([1, 2, 3]), [key.pub], now), undefined, "garbage");
+});
+
+test("a pull learns a key rotation and refreshes the credential under the new key", async () => {
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });
+ const session = await mesh.join({ refreshLeadMs: 0, controlPlaneSyncIntervalMs: 0 });
+ try {
+ const issuer = cp.current;
+ assert.equal(mesh.credential.controlPlaneKeys.length, 1);
+
+ // Nothing changed: a pull is a no-op that spends no refresh.
+ let result = await session.sync();
+ assert.deepEqual(result.errors, []);
+ assert.equal(result.keysChanged, false);
+ assert.equal(result.refreshed, false);
+ assert.equal(cp.refreshes, 0);
+
+ // The control plane rotates: a new key joins the set and mints from now on.
+ cp.keys.push(new SigningKey());
+ result = await session.sync();
+ assert.deepEqual(result.errors, []);
+ assert.equal(result.keysChanged, true);
+ assert.equal(result.refreshed, true, "credential predating the rotation was not refreshed");
+ assert.equal(cp.refreshes, 1);
+ assert.equal(mesh.credential.controlPlaneKeys.length, 2);
+ assert.ok(!credentialPredatesRotation(mesh.credential));
+ // The new credential is signed by the new key and no longer by the retiring one.
+ const verified = await verifyPeerBiscuit(mesh.credential.biscuit, mesh.peerId, [cp.current.pub]);
+ assert.equal(verified.peerId, mesh.peerId);
+ await assert.rejects(verifyPeerBiscuit(mesh.credential.biscuit, mesh.peerId, [issuer.pub]));
+
+ // The retiring key leaves the set: the member follows without another refresh.
+ cp.keys.shift();
+ result = await session.sync();
+ assert.equal(result.keysChanged, true);
+ assert.equal(result.refreshed, false);
+ assert.equal(mesh.credential.controlPlaneKeys.length, 1);
+ // The router's credential was minted under the first key; keep it valid for the next test.
+ cp.keys.unshift(issuer);
+ } finally {
+ await session.close();
+ }
+});
+
+test("a banned peer is hung up on and refused at the gate and the handshake", async () => {
+ const mesh = await AgentMesh.enroll({ controlPlaneUrl: "http://127.0.0.1:1", bootstrapToken: "sbt", fetch: cp.fetch });
+ const session = await mesh.join({ refreshLeadMs: 0, controlPlaneSyncIntervalMs: 0 });
+ const peerIdentity = Identity.generate();
+ const peerBiscuit = cp.current.mint(peerIdentity.peerId, ROLE_NODE);
+ const peer = await createLibp2p({
+ privateKey: privateKeyFromProtobuf(peerIdentity.toLibp2pPrivateKey()),
+ transports: [tcp(), circuitRelayTransport()],
+ connectionEncrypters: [tls()],
+ streamMuxers: [yamux()],
+ services: { identify: identify() },
+ });
+ try {
+ const relayed = session.relayAddresses[0];
+ assert.ok(relayed !== undefined, "no relayed address");
+ const frame = toBinary(AuthFrameSchema, create(AuthFrameSchema, { biscuit: peerBiscuit }));
+ const conn = await peer.dial(relayed);
+ await authenticateWithPeer(conn, frame, [cp.current.pub]);
+ assert.ok(session.authenticatedPeers.has(peerIdentity.peerId));
+
+ // The control plane bans the peer; the next pull evicts it.
+ cp.banned = [peerIdentity.peerId];
+ const result = await session.sync();
+ assert.deepEqual(result.errors, []);
+ assert.deepEqual(session.banned.peers(), [peerIdentity.peerId]);
+ assert.ok(!session.authenticatedPeers.has(peerIdentity.peerId), "admission survived the ban");
+ await new Promise((r) => setTimeout(r, 200));
+ assert.equal(session.node.getConnections(peer.peerId).length, 0, "connection survived the ban");
+
+ // Its token still verifies, and it is still refused: a new connection at the gate ...
+ await assert.rejects(peer.dial(relayed).then((c) => authenticateWithPeer(c, frame, [cp.current.pub])));
+ // ... and outbound, before any dial.
+ await assert.rejects(session.connect(`${routerAddr}/p2p-circuit/p2p/${peerIdentity.peerId}`), /banned/);
+
+ // Lifted by the control plane: the next pull unbans it.
+ cp.banned = [];
+ await session.sync();
+ assert.deepEqual(session.banned.peers(), []);
+ } finally {
+ await peer.stop();
+ await session.close();
+ }
+});
diff --git a/sdk/js/src/sync.ts b/sdk/js/src/sync.ts
new file mode 100644
index 00000000..a56e0f64
--- /dev/null
+++ b/sdk/js/src/sync.ts
@@ -0,0 +1,109 @@
+// 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.
+
+// What a member keeps in step with the control plane while it runs, as
+// sam-node's controlplane_sync.go: the ban set, reconciled from /info, and
+// the gossip events that bring the next pull forward.
+
+import { fromBinary, toBinary } from "@bufbuild/protobuf";
+import { verifyEd25519 } from "./identity.ts";
+import { MeshEvent_Type, MeshEventSchema, type MeshEvent } from "./gen/sam_pb.ts";
+
+/** The GossipSub topic the control plane publishes mesh events on (api.GossipEvents). */
+export const GOSSIP_EVENTS_TOPIC = "/sam/mesh/events/v1";
+
+/** How far an event's timestamp may be from now; older or later ones are ignored. */
+export const EVENT_FRESHNESS_MS = 5 * 60 * 1000;
+
+/**
+ * The peers the control plane has banned, with when each ban was learned.
+ * A ban recorded at or after the instant a /info answer was requested is
+ * kept when that answer omits it: the answer predates the ban and cannot
+ * speak to it.
+ */
+export class BanSet {
+ readonly #bannedAt = new Map<string, number>();
+
+ has(peerId: string): boolean {
+ return this.#bannedAt.has(peerId);
+ }
+
+ get size(): number {
+ return this.#bannedAt.size;
+ }
+
+ peers(): string[] {
+ return [...this.#bannedAt.keys()].sort();
+ }
+
+ /** Records a ban; returns false when the ban was already known. */
+ add(peerId: string, atMs: number): boolean {
+ if (this.#bannedAt.has(peerId)) {
+ return false;
+ }
+ this.#bannedAt.set(peerId, atMs);
+ return true;
+ }
+
+ /**
+ * Makes the set match the control plane's ban set as of fetchedAt.
+ * Returns the peers newly banned and the peers whose ban was lifted.
+ */
+ reconcile(bannedPeerIds: string[], fetchedAt: Date): { banned: string[]; unbanned: string[] } {
+ const fetchedAtMs = fetchedAt.getTime();
+ const current = new Set(bannedPeerIds);
+ const unbanned: string[] = [];
+ for (const [peerId, at] of this.#bannedAt) {
+ if (current.has(peerId) || at >= fetchedAtMs) {
+ continue;
+ }
+ this.#bannedAt.delete(peerId);
+ unbanned.push(peerId);
+ }
+ const banned: string[] = [];
+ for (const peerId of current) {
+ if (this.add(peerId, fetchedAtMs)) {
+ banned.push(peerId);
+ }
+ }
+ return { banned, unbanned };
+ }
+}
+
+/**
+ * Verifies a MeshEvent as sam-node's verifyEvent does: the signature covers
+ * the deterministic encoding of the event with the signature cleared, under
+ * any trusted control plane key. Returns the event, or undefined when it
+ * does not verify or is not fresh.
+ */
+export function verifyMeshEvent(data: Uint8Array, trustedKeys: Uint8Array[], now: Date = new Date()): MeshEvent | undefined {
+ let event: MeshEvent;
+ try {
+ event = fromBinary(MeshEventSchema, data);
+ } catch {
+ return undefined;
+ }
+ const signature = event.signature;
+ const unsigned = toBinary(MeshEventSchema, { ...event, signature: new Uint8Array() });
+ if (!trustedKeys.some((key) => verifyEd25519(key, unsigned, signature))) {
+ return undefined;
+ }
+ const skew = Math.abs(now.getTime() - Number(event.timestamp));
+ if (skew > EVENT_FRESHNESS_MS) {
+ return undefined;
+ }
+ return event;
+}
+
+export { MeshEvent_Type };
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 95988c3d..4a499cd4 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -37,7 +37,8 @@ print(mesh.peer_id) # 12D3Koo...
async def main():
# On the mesh: authenticated with a router, reachable through it,
- # credential kept fresh for as long as the block is open.
+ # credential kept fresh, keys, bans and policy followed from the control
+ # plane for as long as the block is open.
async with mesh.join() as session:
print(session.relay_addresses)
# Reach another member (directly or through a router) and verify it.
@@ -115,6 +116,9 @@ A plaintext `http://` control plane is accepted only on loopback. Pass
- `agent_mesh.serve`: the `/sam/mcp/1.0.0` server, the `/libp2p-http`
server and client (`h11` on the stream), and the service registry behind
`session.serve()`.
+- `agent_mesh.sync`: the ban set and the control plane's gossip events;
+ `session.sync()` pulls keys, bans and router addresses as
+ `internal/node/controlplane_sync.go` does.
- `agent_mesh._proto`, `agent_mesh._gen`: generated from `api/sam.proto`,
`sdk/python/proto/circuit.proto` and `api/datalog.go` by
`hack/gen-sdk-proto.sh`.
diff --git a/sdk/python/src/agent_mesh/__init__.py b/sdk/python/src/agent_mesh/__init__.py
index eb8f766b..8837e426 100644
--- a/sdk/python/src/agent_mesh/__init__.py
+++ b/sdk/python/src/agent_mesh/__init__.py
@@ -33,7 +33,7 @@ from .credential import MeshCredential, decode_auth_response, encode_auth_frame
from .discovery import DHT_PROTOCOL, DiscoveredProvider, find_providers, parse_service_target, provide, service_key
from .identity import Identity, libp2p_public_key, peer_id_from_public_key, verify_ed25519
from .mcp_client import LabelsNotSatisfiedError, ToolCallResult, open_mcp_session, require_labels
-from .mesh import AgentMesh
+from .mesh import AgentMesh, ControlPlaneSync
from .relay import dial_through_relay, reserve_relay
from .serve import (
HTTP_PROTOCOL,
@@ -49,6 +49,7 @@ from .serve import (
mcp_stream_handler,
)
from .session import AdmittedRouter, MeshSession
+from .sync import GOSSIP_EVENTS_TOPIC, BanSet, verify_mesh_event
__version__ = "0.1.0"
@@ -60,13 +61,16 @@ __all__ = [
"AuthorizationError",
"AuthorizeRequest",
"BASELINE_DATALOG",
+ "BanSet",
"BiscuitVerificationError",
"ControlPlaneClient",
"ControlPlaneError",
+ "ControlPlaneSync",
"DHT_PROTOCOL",
"DiscoveredProvider",
"Enrollment",
"EnrollmentRejectedError",
+ "GOSSIP_EVENTS_TOPIC",
"HTTP_PROTOCOL",
"HTTPHandler",
"HTTPRequest",
@@ -113,5 +117,6 @@ __all__ = [
"validate_control_plane_url",
"verify_ed25519",
"verify_keys_response",
+ "verify_mesh_event",
"verify_peer_biscuit",
]
diff --git a/sdk/python/src/agent_mesh/auth.py b/sdk/python/src/agent_mesh/auth.py
index 4c832c28..50111128 100644
--- a/sdk/python/src/agent_mesh/auth.py
+++ b/sdk/python/src/agent_mesh/auth.py
@@ -78,17 +78,22 @@ def auth_stream_handler(
own_biscuit: Callable[[], bytes],
trusted_keys: Callable[[], Sequence[bytes]],
on_authenticated: Optional[Callable[[str, VerifiedBiscuit], None]] = None,
+ is_banned: Optional[Callable[[str], bool]] = None,
) -> Callable[[INetStream], "trio.lowlevel.Awaitable[None]"]:
"""Server side of /sam/auth/1.0.0, mirroring sam-node's HandleAuthHandshake:
verify the caller's biscuit against the control plane keys and its
- connection peer ID, then answer with our own. A failed verification gets no
- answer, only a closed stream, as on the Go side."""
+ connection peer ID, then answer with our own. A failed verification, or a
+ peer the control plane banned, gets no answer, only a closed stream, as on
+ the Go side."""
async def handle(stream: INetStream) -> None:
peer_id = str(stream.muxed_conn.peer_id)
try:
with trio.fail_after(AUTH_HANDSHAKE_TIMEOUT):
frame = pb.AuthFrame.FromString(await _read_frame(stream))
+ if is_banned is not None and is_banned(peer_id):
+ logger.warning("auth handshake from %s refused: peer is revoked", peer_id)
+ return
try:
verified = verify_peer_biscuit(frame.biscuit, peer_id, trusted_keys())
except BiscuitVerificationError as err:
diff --git a/sdk/python/src/agent_mesh/conformance_join.py b/sdk/python/src/agent_mesh/conformance_join.py
index 521b10b9..94c06e8a 100644
--- a/sdk/python/src/agent_mesh/conformance_join.py
+++ b/sdk/python/src/agent_mesh/conformance_join.py
@@ -35,6 +35,9 @@ then takes JSON commands on stdin, one per line, until stdin closes:
"path": "/v1/models", "method": "GET", "body": "..."}
call an HTTP service over the mesh
{"cmd": "peers"} peers that authenticated to us
+ {"cmd": "sync"} pull keys, bans and routers from
+ the control plane now
+ {"cmd": "banned"} peers banned by the control plane
{"cmd": "quit"} leave the mesh and exit
Each command gets one JSON line back. Same environment as conformance.py; the
@@ -100,6 +103,21 @@ async def _handle(session: MeshSession, command: dict) -> dict:
return {"cmd": cmd, "ok": True, "is_error": result.is_error, "text": result.text}
if cmd == "peers":
return {"cmd": cmd, "authenticated_peers": sorted(session.authenticated_peers)}
+ if cmd == "sync":
+ result = await session.sync()
+ return {
+ "cmd": cmd,
+ "ok": not result.errors,
+ "error": "; ".join(result.errors),
+ "keys_changed": result.keys_changed,
+ "refreshed": result.refreshed,
+ "trusted_keys": [k.hex() for k in session.mesh.credential.control_plane_keys],
+ "biscuit": base64.b64encode(session.mesh.credential.biscuit).decode(),
+ "banned": session.banned.peers(),
+ "router_addresses": list(session.mesh.credential.router_addresses),
+ }
+ if cmd == "banned":
+ return {"cmd": cmd, "ok": True, "banned": session.banned.peers(), "authenticated_peers": sorted(session.authenticated_peers)}
if cmd == "serve":
name = command.get("name", "")
service_type = command.get("type")
@@ -151,6 +169,9 @@ async def _handle(session: MeshSession, command: dict) -> dict:
async def main() -> None:
# stdout carries the protocol lines only; every log goes to stderr.
logging.basicConfig(stream=sys.stderr, level=logging.WARNING, force=True)
+ # py-libp2p's pubsub tries meshsub with every new peer and the host logs
+ # an error for each one that does not run pubsub; that is expected here.
+ logging.getLogger("libp2p.host.basic_host").setLevel(logging.CRITICAL)
control_plane_url = _require_env("SAM_CONTROL_PLANE_URL")
bootstrap_token_path = _require_env("SAM_BOOTSTRAP_TOKEN_PATH")
state_dir = _require_env("SAM_SDK_STATE_DIR")
@@ -164,7 +185,8 @@ async def main() -> None:
allow_insecure=allow_insecure,
poll_interval=0.2,
)
- async with mesh.join(listen_addrs=listen) as session:
+ # The test drives every pull itself; only gossip events bring one forward.
+ async with mesh.join(listen_addrs=listen, control_plane_sync_interval=0, control_plane_sync_jitter=0) as session:
_emit(
{
"sdk": "python",
@@ -173,6 +195,7 @@ async def main() -> None:
"relay_addresses": session.relay_addresses,
"direct_addresses": [str(a) for a in session.host.get_addrs()],
"biscuit": base64.b64encode(mesh.credential.biscuit).decode(),
+ "trusted_keys": [k.hex() for k in mesh.credential.control_plane_keys],
}
)
while True:
diff --git a/sdk/python/src/agent_mesh/credential.py b/sdk/python/src/agent_mesh/credential.py
index f192e902..b5929b0a 100644
--- a/sdk/python/src/agent_mesh/credential.py
+++ b/sdk/python/src/agent_mesh/credential.py
@@ -33,6 +33,11 @@ class MeshCredential:
expiration: int
# Every control plane signing key currently trusted (rotation keeps several valid).
control_plane_keys: list[bytes] = field(default_factory=list)
+ # The trusted set when the biscuit was issued. A key trusted now that was
+ # not in this set means a rotation happened since: the biscuit is signed by
+ # a retiring key and must be refreshed before that key leaves its grace
+ # period (sam-node's identityPredatesRotation).
+ issued_under_keys: list[bytes] = field(default_factory=list)
# Router multiaddrs, `/p2p/<peer id>` suffixed, as handed out at enrollment.
router_addresses: list[str] = field(default_factory=list)
@@ -40,6 +45,11 @@ class MeshCredential:
"""Seconds of validity left on the biscuit; negative once expired."""
return self.expiration - int(time.time() if now is None else now)
+ def predates_rotation(self) -> bool:
+ """Whether a key trusted now was unknown when the credential was issued."""
+ issued = {bytes(k) for k in self.issued_under_keys}
+ return any(bytes(k) not in issued for k in self.control_plane_keys)
+
def to_json(self) -> str:
return json.dumps(
{
@@ -47,6 +57,7 @@ class MeshCredential:
"biscuit": base64.b64encode(self.biscuit).decode(),
"expiration": self.expiration,
"control_plane_keys": [base64.b64encode(k).decode() for k in self.control_plane_keys],
+ "issued_under_keys": [base64.b64encode(k).decode() for k in self.issued_under_keys],
"router_addresses": list(self.router_addresses),
},
indent=2,
@@ -56,11 +67,14 @@ class MeshCredential:
def from_json(cls, text: str) -> "MeshCredential":
raw = json.loads(text)
try:
+ control_plane_keys = [base64.b64decode(k) for k in raw.get("control_plane_keys", [])]
return cls(
control_plane_url=str(raw["control_plane_url"]),
biscuit=base64.b64decode(raw["biscuit"]),
expiration=int(raw["expiration"]),
- control_plane_keys=[base64.b64decode(k) for k in raw.get("control_plane_keys", [])],
+ control_plane_keys=control_plane_keys,
+ # A file from before this field: the set known then is the best answer.
+ issued_under_keys=[base64.b64decode(k) for k in raw["issued_under_keys"]] if "issued_under_keys" in raw else control_plane_keys,
router_addresses=[str(a) for a in raw.get("router_addresses", [])],
)
except (KeyError, TypeError, ValueError) as err:
diff --git a/sdk/python/src/agent_mesh/mesh.py b/sdk/python/src/agent_mesh/mesh.py
index 3a86bcfb..eddeb506 100644
--- a/sdk/python/src/agent_mesh/mesh.py
+++ b/sdk/python/src/agent_mesh/mesh.py
@@ -16,7 +16,8 @@ from __future__ import annotations
import os
import threading
-from dataclasses import replace
+import time
+from dataclasses import dataclass, field, replace
from pathlib import Path
from typing import Mapping, Optional
@@ -28,6 +29,22 @@ _IDENTITY_FILE = "identity.key"
_CREDENTIAL_FILE = "credential.json"
+@dataclass(frozen=True)
+class ControlPlaneSync:
+ """What one pull from the control plane changed."""
+
+ # The trusted key set differs from before the pull.
+ keys_changed: bool
+ # The credential was re-issued because a rotation had happened since.
+ refreshed: bool
+ # The control plane's ban set, when /info answered.
+ banned_peer_ids: Optional[list[str]]
+ # When /info was asked (unix seconds); a ban recorded later cannot be in the answer.
+ fetched_at: float
+ # One entry per part that failed; empty when everything landed.
+ errors: list[str] = field(default_factory=list)
+
+
class AgentMesh:
"""A member of the mesh: an identity, the credential the control plane
minted for it, and the client that keeps that credential fresh. join()
@@ -102,6 +119,7 @@ class AgentMesh:
biscuit=enrollment.biscuit,
expiration=enrollment.expiration,
control_plane_keys=control_plane_keys,
+ issued_under_keys=list(control_plane_keys),
router_addresses=list(enrollment.router_addresses),
),
state,
@@ -138,11 +156,61 @@ class AgentMesh:
except Exception: # noqa: BLE001 - a failed /keys sync must not cost the new biscuit
pass
self._credential = replace(
- self._credential, biscuit=result.biscuit, expiration=result.expiration, control_plane_keys=control_plane_keys
+ self._credential,
+ biscuit=result.biscuit,
+ expiration=result.expiration,
+ control_plane_keys=control_plane_keys,
+ issued_under_keys=list(control_plane_keys),
)
self.save()
return self._credential
+ def add_trusted_key(self, key: bytes) -> bool:
+ """Adopts a signing key announced by a KEY_ROTATION event, so peers whose
+ credentials the new key signs verify before the next pull confirms it."""
+ if any(bytes(k) == bytes(key) for k in self._credential.control_plane_keys):
+ return False
+ self._credential = replace(self._credential, control_plane_keys=[*self._credential.control_plane_keys, bytes(key)])
+ return True
+
+ def sync_control_plane(self) -> ControlPlaneSync:
+ """The member's pull from the control plane, as sam-node's SyncControlPlane:
+ the signing keys (verified against the set already trusted, so whoever
+ answers the URL cannot become the trust root), a credential refresh when
+ a rotation happened since it was issued, and /info for the router
+ addresses and the ban set. Each part is attempted even when another
+ fails; the errors are reported together. Gossip events only bring this
+ forward; they are never the only way state arrives."""
+ errors: list[str] = []
+ keys_changed = False
+ refreshed = False
+ try:
+ keys = self.control_plane.keys(self._credential.control_plane_keys)
+ if not keys:
+ raise ValueError("/keys returned no keys")
+ keys_changed = {bytes(k) for k in keys} != {bytes(k) for k in self._credential.control_plane_keys}
+ self._credential = replace(self._credential, control_plane_keys=list(keys))
+ if self._credential.predates_rotation():
+ self.refresh()
+ refreshed = True
+ except Exception as err: # noqa: BLE001 - reported, the other parts still run
+ errors.append(f"keys: {err}")
+
+ banned_peer_ids: Optional[list[str]] = None
+ # Taken before the request: a ban recorded after this instant cannot be
+ # in the answer, so its absence must not be read as an unban.
+ fetched_at = time.time()
+ try:
+ info = self.control_plane.info()
+ if info.router_addresses:
+ self._credential = replace(self._credential, router_addresses=list(info.router_addresses))
+ banned_peer_ids = list(info.banned_peer_ids)
+ except Exception as err: # noqa: BLE001
+ errors.append(f"info: {err}")
+ if keys_changed or banned_peer_ids is not None:
+ self.save()
+ return ControlPlaneSync(keys_changed=keys_changed, refreshed=refreshed, banned_peer_ids=banned_peer_ids, fetched_at=fetched_at, errors=errors)
+
def auth_frame(self, target_service: str = "", agent: str = "") -> bytes:
"""The frame that opens every stream to a peer: this member's biscuit plus
the service it wants (e.g. "mcp://calculator") and the agent it speaks for."""
diff --git a/sdk/python/src/agent_mesh/serve.py b/sdk/python/src/agent_mesh/serve.py
index 6ad66c46..cfa8e499 100644
--- a/sdk/python/src/agent_mesh/serve.py
+++ b/sdk/python/src/agent_mesh/serve.py
@@ -124,6 +124,8 @@ class ProviderOptions:
own_biscuit: Callable[[], bytes]
# Called after a caller is authorized for a service, e.g. for the session's admitted set.
on_authorized: Optional[Callable[[str, VerifiedBiscuit, str], None]] = None
+ # Peers the control plane has banned; refused before their token is looked at.
+ is_banned: Optional[Callable[[str], bool]] = None
class ServiceRegistry:
@@ -189,6 +191,10 @@ def mcp_stream_handler(registry: ServiceRegistry, options: ProviderOptions, prot
await stream.close()
return
frame = pb.AuthFrame.FromString(data)
+ if options.is_banned is not None and options.is_banned(peer_id):
+ await _refuse(stream, peer_id, "peer is revoked")
+ await stream.close()
+ return
try:
verified = await trio.to_thread.run_sync(
authorize_caller,
@@ -368,6 +374,8 @@ async def _handle_ingress(
return plain(400, "Invalid X-Sam-Biscuit encoding")
target_service = f"{service_type}://{service_name}"
+ if options.is_banned is not None and options.is_banned(peer_id):
+ return plain(403, "Authorization failed")
try:
verified = await trio.to_thread.run_sync(
authorize_caller,
diff --git a/sdk/python/src/agent_mesh/session.py b/sdk/python/src/agent_mesh/session.py
index fb8cfceb..82db4291 100644
--- a/sdk/python/src/agent_mesh/session.py
+++ b/sdk/python/src/agent_mesh/session.py
@@ -15,6 +15,7 @@
from __future__ import annotations
import logging
+import random
import time
from contextlib import asynccontextmanager
from dataclasses import dataclass, field
@@ -24,11 +25,19 @@ from typing import TYPE_CHECKING, Any, AsyncIterator, Mapping, Optional, Sequenc
import multiaddr
import trio
from libp2p.abc import IHost
+from libp2p.custom_types import TProtocol
from libp2p.peer.id import ID
from libp2p.peer.peerinfo import info_from_p2p_addr
+from libp2p.pubsub.gossipsub import PROTOCOL_ID as GOSSIPSUB_V10
+from libp2p.pubsub.gossipsub import PROTOCOL_ID_V11 as GOSSIPSUB_V11
+from libp2p.pubsub.gossipsub import PROTOCOL_ID_V12 as GOSSIPSUB_V12
+from libp2p.pubsub.gossipsub import GossipSub
+from libp2p.pubsub.pubsub import Pubsub
+from libp2p.tools.anyio_service import background_trio_service
from mcp import ClientSession
from ._proto import circuit_pb2 as circuit
+from ._proto import sam_pb2 as pb
from .auth import AUTH_PROTOCOL, MCP_PROTOCOL, auth_stream_handler, authenticate_with_peer
from .authorizer import ProviderAuthorizerOptions
from .biscuit import ROLE_ROUTER, VerifiedBiscuit, require_role
@@ -46,9 +55,10 @@ from .serve import (
http_request_over_stream,
mcp_stream_handler,
)
+from .sync import GOSSIP_EVENTS_TOPIC, BanSet, verify_mesh_event
if TYPE_CHECKING:
- from .mesh import AgentMesh
+ from .mesh import AgentMesh, ControlPlaneSync
logger = logging.getLogger("agent_mesh")
@@ -59,6 +69,10 @@ MIN_REFRESH_DELAY = 2.0
DEFAULT_POLICY_SYNC = 15 * 60.0
# How often provider records are refreshed; go-libp2p-kad-dht expires them after 48h.
DEFAULT_PROVIDE_INTERVAL = 10 * 60.0
+# sam-node's --control-plane-sync-interval default, and its 2s first pull.
+DEFAULT_CONTROL_PLANE_SYNC = 15 * 60.0
+FIRST_CONTROL_PLANE_SYNC = 2.0
+DEFAULT_CONTROL_PLANE_SYNC_JITTER = 2.0
@dataclass(frozen=True)
@@ -80,13 +94,19 @@ class MeshSession:
routers: list[AdmittedRouter]
# Peers that passed the inbound auth handshake, with their credential's expiration.
authenticated_peers: dict[str, datetime] = field(default_factory=dict)
+ # Peers the control plane has banned; connections to and from them are refused.
+ banned: BanSet = field(default_factory=BanSet)
# The services this member publishes.
services: ServiceRegistry = field(default_factory=ServiceRegistry)
policy_sync_interval: float = DEFAULT_POLICY_SYNC
provide_interval: float = DEFAULT_PROVIDE_INTERVAL
+ control_plane_sync_interval: float = DEFAULT_CONTROL_PLANE_SYNC
+ control_plane_sync_jitter: float = DEFAULT_CONTROL_PLANE_SYNC_JITTER
_nursery: Optional[trio.Nursery] = field(default=None, repr=False)
_policy_rules: Optional[list[str]] = field(default=None, repr=False)
_serving: bool = field(default=False, repr=False)
+ _sync_lock: trio.Lock = field(default_factory=trio.Lock, repr=False)
+ _sync_trigger: trio.Event = field(default_factory=trio.Event, repr=False)
@property
def peer_id(self) -> str:
@@ -112,10 +132,11 @@ class MeshSession:
async def connect(self, addr: str | multiaddr.Multiaddr) -> ID:
"""Connects to a peer by address, through a relay when the address says
- `/p2p-circuit`, and returns its peer ID."""
+ `/p2p-circuit`, and returns its peer ID. A banned peer is refused."""
ma = multiaddr.Multiaddr(str(addr))
if "/p2p-circuit" in str(ma):
relay_addr, target = split_circuit_address(ma)
+ self._refuse_banned(target)
relay = info_from_p2p_addr(relay_addr)
if relay.peer_id not in self.host.get_connected_peers():
await self.host.connect(relay)
@@ -123,9 +144,14 @@ class MeshSession:
await dial_through_relay(self.host, relay.peer_id, target)
return target
info = info_from_p2p_addr(ma)
+ self._refuse_banned(info.peer_id)
await self.host.connect(info)
return info.peer_id
+ def _refuse_banned(self, peer_id: ID) -> None:
+ if str(peer_id) in self.banned:
+ raise PermissionError(f"peer {peer_id} is banned by the control plane")
+
async def authenticate(self, addr: str | multiaddr.Multiaddr) -> VerifiedBiscuit:
"""Connects to a peer and runs the mutual auth handshake, returning the
peer's verified credential."""
@@ -187,6 +213,86 @@ class MeshSession:
"""Re-reads the mesh policy from the control plane."""
self._policy_rules = await trio.to_thread.run_sync(self.mesh.control_plane.policy_rules, self.mesh.credential.biscuit)
+ async def sync(self) -> "ControlPlaneSync":
+ """Pulls keys, bans and router addresses from the control plane now, and
+ the mesh policy when serving, then applies them: a newly banned peer is
+ disconnected and dropped from the admitted set. Concurrent calls run
+ one after the other. Errors of individual parts are in the result."""
+ async with self._sync_lock:
+ result = await trio.to_thread.run_sync(self.mesh.sync_control_plane)
+ if result.banned_peer_ids is not None:
+ newly_banned, _ = self.banned.reconcile(result.banned_peer_ids, result.fetched_at)
+ for peer_id in newly_banned:
+ await self._evict(peer_id)
+ if self._serving:
+ try:
+ await self.sync_policy()
+ except Exception as err: # noqa: BLE001 - the last good policy stays in force
+ result.errors.append(f"policy: {err}")
+ return result
+
+ def trigger_sync(self) -> None:
+ """Asks for a pull soon, after a random delay so a fleet told at once does not pull at once."""
+ self._sync_trigger.set()
+
+ async def _evict(self, peer_id: str) -> None:
+ """Drops a banned peer: its admission and its connections."""
+ self.authenticated_peers.pop(peer_id, None)
+ try:
+ await self.host.disconnect(ID.from_base58(peer_id))
+ except Exception: # noqa: BLE001 - not connected, or already gone
+ pass
+
+ async def _sync_loop(self) -> None:
+ """Pulls once shortly after join, then every interval and whenever
+ triggered; each periodic wait is stretched by up to a tenth and each
+ trigger delayed by up to the jitter, as sam-node's loop does."""
+ delay = min(FIRST_CONTROL_PLANE_SYNC, self.control_plane_sync_interval) if self.control_plane_sync_interval > 0 else None
+ while True:
+ triggered = False
+ with trio.move_on_after(delay) if delay is not None else trio.CancelScope():
+ await self._sync_trigger.wait()
+ triggered = True
+ self._sync_trigger = trio.Event()
+ if triggered and self.control_plane_sync_jitter > 0:
+ await trio.sleep(random.uniform(0, self.control_plane_sync_jitter)) # noqa: S311 - jitter, not security
+ try:
+ result = await self.sync()
+ if result.errors:
+ logger.warning("control plane sync: %s", "; ".join(result.errors))
+ except Exception as err: # noqa: BLE001
+ logger.warning("control plane sync failed: %s", err)
+ if self.control_plane_sync_interval > 0:
+ delay = self.control_plane_sync_interval * random.uniform(1.0, 1.1) # noqa: S311
+
+ async def _events_loop(self, pubsub: Pubsub) -> None:
+ """The control plane's gossip events, relayed by the routers. The topic
+ validator drops anything not signed by a trusted control plane key, so
+ a peer whose libp2p key signed the envelope still cannot get an
+ unsigned event through."""
+
+ def validate(_peer: ID, message) -> bool: # type: ignore[no-untyped-def]
+ return verify_mesh_event(bytes(message.data), self.mesh.credential.control_plane_keys) is not None
+
+ pubsub.set_topic_validator(GOSSIP_EVENTS_TOPIC, validate, False)
+ subscription = await pubsub.subscribe(GOSSIP_EVENTS_TOPIC)
+ while True:
+ message = await subscription.get()
+ event = verify_mesh_event(bytes(message.data), self.mesh.credential.control_plane_keys)
+ if event is None:
+ continue
+ if event.type == pb.MeshEvent.BANNED:
+ # Not persisted: a restarted member picks the ban back up from /info.
+ if self.banned.add(event.peer_id, event.timestamp):
+ logger.info("peer %s banned by the control plane", event.peer_id)
+ await self._evict(event.peer_id)
+ elif event.type == pb.MeshEvent.KEY_ROTATION:
+ if len(event.new_public_key) == 32:
+ self.mesh.add_trusted_key(bytes(event.new_public_key))
+ self.trigger_sync()
+ elif event.type == pb.MeshEvent.POLICY_UPDATE:
+ self.trigger_sync()
+
async def request(
self,
addr: str | multiaddr.Multiaddr,
@@ -222,6 +328,7 @@ class MeshSession:
),
own_biscuit=lambda: self.mesh.credential.biscuit,
on_authorized=lambda peer, verified, _target: self.authenticated_peers.__setitem__(peer, verified.expiration),
+ is_banned=lambda peer: peer in self.banned,
)
self.host.set_stream_handler(MCP_PROTOCOL, mcp_stream_handler(self.services, options, str(MCP_PROTOCOL)))
self.host.set_stream_handler(HTTP_PROTOCOL, http_ingress_handler(self.services, options))
@@ -299,6 +406,8 @@ async def join_mesh(
refresh_retry: float = DEFAULT_REFRESH_RETRY,
policy_sync_interval: float = DEFAULT_POLICY_SYNC,
provide_interval: float = DEFAULT_PROVIDE_INTERVAL,
+ control_plane_sync_interval: float = DEFAULT_CONTROL_PLANE_SYNC,
+ control_plane_sync_jitter: float = DEFAULT_CONTROL_PLANE_SYNC_JITTER,
) -> AsyncIterator[MeshSession]:
"""Implements AgentMesh.join(); lives here to keep mesh.py free of libp2p."""
router_addrs = [multiaddr.Multiaddr(a) for a in mesh.credential.router_addresses]
@@ -307,31 +416,44 @@ async def join_mesh(
host, listen = create_mesh_host(mesh.identity, listen_addrs)
authenticated: dict[str, datetime] = {}
+ banned = BanSet()
host.set_stream_handler(
AUTH_PROTOCOL,
auth_stream_handler(
own_biscuit=lambda: mesh.credential.biscuit,
trusted_keys=lambda: mesh.credential.control_plane_keys,
on_authenticated=lambda peer, verified: authenticated.__setitem__(peer, verified.expiration),
+ is_banned=lambda peer: peer in banned,
),
)
host.set_stream_handler(STOP_PROTOCOL, stop_stream_handler(host))
+ # Built before any connection: Pubsub learns of peers through a notifee it
+ # registers here. StrictSign, as every Go component pins it.
+ gossipsub = GossipSub(protocols=[GOSSIPSUB_V12, GOSSIPSUB_V11, GOSSIPSUB_V10], degree=6, degree_low=4, degree_high=12)
+ pubsub = Pubsub(host, gossipsub, strict_signing=True)
try:
- async with host.run(listen_addrs=listen):
+ async with host.run(listen_addrs=listen), background_trio_service(pubsub), background_trio_service(gossipsub):
+ await pubsub.wait_until_ready()
admitted = await _admit(host, mesh, router_addrs, reserve)
async with trio.open_nursery() as nursery:
nursery.start_soon(_refresh_loop, mesh, refresh_lead, refresh_retry)
+ session = MeshSession(
+ mesh=mesh,
+ host=host,
+ routers=admitted,
+ authenticated_peers=authenticated,
+ banned=banned,
+ policy_sync_interval=policy_sync_interval,
+ provide_interval=provide_interval,
+ control_plane_sync_interval=control_plane_sync_interval,
+ control_plane_sync_jitter=control_plane_sync_jitter,
+ _nursery=nursery,
+ )
+ nursery.start_soon(session._events_loop, pubsub) # noqa: SLF001
+ nursery.start_soon(session._sync_loop) # noqa: SLF001
try:
- yield MeshSession(
- mesh=mesh,
- host=host,
- routers=admitted,
- authenticated_peers=authenticated,
- policy_sync_interval=policy_sync_interval,
- provide_interval=provide_interval,
- _nursery=nursery,
- )
+ yield session
finally:
nursery.cancel_scope.cancel()
except BaseExceptionGroup as group:
diff --git a/sdk/python/src/agent_mesh/sync.py b/sdk/python/src/agent_mesh/sync.py
new file mode 100644
index 00000000..104ecc2d
--- /dev/null
+++ b/sdk/python/src/agent_mesh/sync.py
@@ -0,0 +1,90 @@
+# 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.
+
+"""What a member keeps in step with the control plane while it runs, as
+sam-node's controlplane_sync.go: the ban set, reconciled from /info, and the
+gossip events that bring the next pull forward."""
+
+from __future__ import annotations
+
+import time
+from typing import Optional, Sequence
+
+from ._proto import sam_pb2 as pb
+from .identity import verify_ed25519
+
+# The GossipSub topic the control plane publishes mesh events on (api.GossipEvents).
+GOSSIP_EVENTS_TOPIC = "/sam/mesh/events/v1"
+
+# How far an event's timestamp may be from now; older or later ones are ignored.
+EVENT_FRESHNESS_MS = 5 * 60 * 1000
+
+
+class BanSet:
+ """The peers the control plane has banned, with when each ban was learned
+ (unix milliseconds). A ban recorded at or after the instant a /info answer
+ was requested is kept when that answer omits it: the answer predates the
+ ban and cannot speak to it."""
+
+ def __init__(self) -> None:
+ self._banned_at: dict[str, int] = {}
+
+ def __contains__(self, peer_id: str) -> bool:
+ return peer_id in self._banned_at
+
+ def __len__(self) -> int:
+ return len(self._banned_at)
+
+ def peers(self) -> list[str]:
+ return sorted(self._banned_at)
+
+ def add(self, peer_id: str, at_ms: int) -> bool:
+ """Records a ban; returns False when the ban was already known."""
+ if peer_id in self._banned_at:
+ return False
+ self._banned_at[peer_id] = at_ms
+ return True
+
+ def reconcile(self, banned_peer_ids: Sequence[str], fetched_at: float) -> tuple[list[str], list[str]]:
+ """Makes the set match the control plane's ban set as of fetched_at
+ (unix seconds). Returns (newly banned, unbanned)."""
+ fetched_at_ms = int(fetched_at * 1000)
+ current = set(banned_peer_ids)
+ unbanned = [p for p, at in self._banned_at.items() if p not in current and at < fetched_at_ms]
+ for p in unbanned:
+ del self._banned_at[p]
+ banned = [p for p in current if self.add(p, fetched_at_ms)]
+ return banned, unbanned
+
+
+def verify_mesh_event(data: bytes, trusted_keys: Sequence[bytes], now_ms: Optional[int] = None) -> Optional[pb.MeshEvent]:
+ """Verifies a MeshEvent as sam-node's verifyEvent does: the signature covers
+ the deterministic encoding of the event with the signature cleared, under
+ any trusted control plane key. Returns the event, or None when it does not
+ verify or is not fresh."""
+ try:
+ event = pb.MeshEvent.FromString(data)
+ except Exception: # noqa: BLE001 - undecodable is unverifiable
+ return None
+ signature = bytes(event.signature)
+ unsigned = pb.MeshEvent()
+ unsigned.CopyFrom(event)
+ unsigned.ClearField("signature")
+ payload = unsigned.SerializeToString(deterministic=True)
+ if not any(verify_ed25519(key, payload, signature) for key in trusted_keys):
+ return None
+ now_ms = int(time.time() * 1000) if now_ms is None else now_ms
+ if abs(now_ms - event.timestamp) > EVENT_FRESHNESS_MS:
+ return None
+ return event
diff --git a/sdk/python/tests/test_sync.py b/sdk/python/tests/test_sync.py
new file mode 100644
index 00000000..e33ce4d7
--- /dev/null
+++ b/sdk/python/tests/test_sync.py
@@ -0,0 +1,249 @@
+# 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.
+
+"""What a joined member keeps in step with the control plane: a fake control
+plane behind the transport hook rotates its key and bans a peer; the member
+learns both from a pull, refreshes its credential under the new key, and
+refuses the banned peer. The real control plane and router are exercised by
+tests/integration/sdk_mesh_test.go."""
+
+import base64
+import time
+import urllib.parse
+
+import biscuit_auth as ba
+import multiaddr
+import pytest
+import trio
+from libp2p.peer.peerinfo import info_from_p2p_addr
+
+from agent_mesh._proto import sam_pb2 as pb
+from agent_mesh.auth import AUTH_PROTOCOL, auth_stream_handler, authenticate_with_peer
+from agent_mesh.biscuit import ROLE_ROUTER, verify_peer_biscuit
+from agent_mesh.controlplane import ROLE_NODE
+from agent_mesh.identity import Identity
+from agent_mesh.mesh import AgentMesh
+from agent_mesh.relay import HOP_PROTOCOL as RELAY_HOP_PROTOCOL
+from agent_mesh.sync import EVENT_FRESHNESS_MS, BanSet, verify_mesh_event
+
+from .test_session import hop_handler, libp2p_host
+
+
+class SigningKey:
+ """One ed25519 key usable both as a biscuit root and for plain signatures."""
+
+ def __init__(self) -> None:
+ self.biscuit = ba.KeyPair()
+ self.identity = Identity.from_seed(self.biscuit.private_key.to_bytes())
+
+ @property
+ def pub(self) -> bytes:
+ return self.identity.public_key_raw
+
+ def mint(self, peer_id: str, role: str) -> bytes:
+ return ba.BiscuitBuilder("node({p}); expiration(2035-01-01T00:00:00Z); role({r});", {"p": peer_id, "r": role}).build(self.biscuit.private_key).to_bytes()
+
+
+class FakeControlPlane:
+ """A control plane whose key set, ban set and issuing key the test changes."""
+
+ def __init__(self, initial: SigningKey, router_addr: str) -> None:
+ self.keys = [initial]
+ self.banned: list[str] = []
+ self.refreshes = 0
+ self.router_addr = router_addr
+
+ @property
+ def current(self) -> SigningKey:
+ return self.keys[-1]
+
+ def transport(self, method, url, headers, body): # type: ignore[no-untyped-def]
+ path = urllib.parse.urlsplit(url).path
+ if (method, path) == ("POST", "/enroll"):
+ req = pb.BootstrapEnrollRequest.FromString(body)
+ return 200, pb.BootstrapEnrollResponse(
+ status=pb.ENROLLMENT_STATUS_APPROVED,
+ biscuit_token=self.current.mint(req.peer_id, ROLE_NODE),
+ control_plane_public_key=self.current.pub,
+ router_addresses=[self.router_addr],
+ expiration=int(time.time()) + 3600,
+ ).SerializeToString()
+ if (method, path) == ("GET", "/keys"):
+ unsigned = pb.KeysResponse(public_keys=[k.pub for k in self.keys], timestamp=int(time.time() * 1000))
+ payload = unsigned.SerializeToString(deterministic=True)
+ return 200, pb.KeysResponse(public_keys=[k.pub for k in self.keys], timestamp=unsigned.timestamp, signatures=[k.identity.sign(payload) for k in self.keys]).SerializeToString()
+ if (method, path) == ("GET", "/info"):
+ return 200, pb.ControlPlaneInfoResponse(router_addresses=[self.router_addr], banned_peer_ids=self.banned).SerializeToString()
+ if (method, path) == ("POST", "/refresh"):
+ self.refreshes += 1
+ presented = base64.b64decode(headers["Authorization"].removeprefix("Bearer "))
+ for key in self.keys:
+ try:
+ verified = verify_peer_biscuit_any(presented, key.pub)
+ except Exception: # noqa: BLE001 - try the next key
+ continue
+ return 200, pb.TokenRefreshResponse(biscuit_token=self.current.mint(verified, ROLE_NODE), expires_at=int(time.time()) + 7200).SerializeToString()
+ return 401, b"unverifiable biscuit"
+ return 404, f"no route for {method} {path}".encode()
+
+
+def verify_peer_biscuit_any(biscuit: bytes, key: bytes) -> str:
+ """The peer a biscuit is bound to, if key signed it."""
+ token = ba.Biscuit.from_bytes(biscuit, ba.PublicKey.from_bytes(key, ba.Algorithm.Ed25519))
+ b = ba.AuthorizerBuilder()
+ b.add_policy(ba.Policy("allow if true"))
+ return b.build(token).query(ba.Rule("p($p) <- node($p)"))[0].terms[0]
+
+
+async def start_router(nursery, cp_keys): # type: ignore[no-untyped-def]
+ identity = Identity.generate()
+ router = libp2p_host(identity)
+ started = trio.Event()
+ box = []
+
+ async def run():
+ async with router.run(listen_addrs=[multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/0")]):
+ addr = f"{router.get_addrs()[0]}"
+ router.set_stream_handler(RELAY_HOP_PROTOCOL, hop_handler(addr, True))
+ box.append(addr)
+ started.set()
+ await trio.sleep_forever()
+
+ nursery.start_soon(run)
+ await started.wait()
+ cp = FakeControlPlane(cp_keys, box[0])
+ router_biscuit = cp.current.mint(identity.peer_id, ROLE_ROUTER)
+ router.set_stream_handler(AUTH_PROTOCOL, auth_stream_handler(lambda: router_biscuit, lambda: [k.pub for k in cp.keys]))
+ return router, cp
+
+
+def test_ban_learned_after_the_answer_was_requested_survives_an_answer_that_omits_it():
+ bans = BanSet()
+ t0 = 1_800_000_000.0
+ t1 = t0 + 1
+ banned, unbanned = bans.reconcile(["A", "B"], t0)
+ assert (sorted(banned), unbanned) == (["A", "B"], [])
+ # A gossip event bans C after t1's request went out; t1's answer cannot speak to it.
+ assert bans.add("C", int(t1 * 1000) + 500)
+ assert bans.reconcile(["A"], t1) == ([], ["B"])
+ assert bans.peers() == ["A", "C"]
+ assert bans.reconcile(["A"], t1 + 2) == ([], ["C"])
+ assert not bans.add("A", 1)
+
+
+def test_mesh_event_verifies_only_under_a_trusted_key_and_only_when_fresh():
+ key = SigningKey()
+
+ def sign(event: pb.MeshEvent) -> bytes:
+ event.ClearField("signature")
+ event.signature = key.identity.sign(event.SerializeToString(deterministic=True))
+ return event.SerializeToString(deterministic=True)
+
+ now_ms = int(time.time() * 1000)
+ banned = sign(pb.MeshEvent(type=pb.MeshEvent.BANNED, peer_id="12D3KooWx", timestamp=now_ms))
+ assert verify_mesh_event(banned, [key.pub], now_ms).peer_id == "12D3KooWx"
+ assert verify_mesh_event(banned, [SigningKey().pub], now_ms) is None
+ tampered = bytearray(banned)
+ tampered[-1] ^= 1
+ assert verify_mesh_event(bytes(tampered), [key.pub], now_ms) is None
+ stale = sign(pb.MeshEvent(type=pb.MeshEvent.BANNED, peer_id="12D3KooWx", timestamp=now_ms - EVENT_FRESHNESS_MS - 1))
+ assert verify_mesh_event(stale, [key.pub], now_ms) is None
+ assert verify_mesh_event(b"\x01\x02\x03", [key.pub], now_ms) is None
+
+
+def test_pull_learns_a_key_rotation_and_refreshes_the_credential():
+ async def main():
+ async with trio.open_nursery() as nursery:
+ _router, cp = await start_router(nursery, SigningKey())
+ mesh = AgentMesh.enroll("http://127.0.0.1:1", bootstrap_token="sbt", transport=cp.transport)
+ async with mesh.join(refresh_lead=0, control_plane_sync_interval=0) as session:
+ issuer = cp.current
+ assert len(mesh.credential.control_plane_keys) == 1
+
+ # Nothing changed: a pull is a no-op that spends no refresh.
+ result = await session.sync()
+ assert result.errors == []
+ assert not result.keys_changed and not result.refreshed
+ assert cp.refreshes == 0
+
+ # The control plane rotates: a new key joins the set and mints from now on.
+ cp.keys.append(SigningKey())
+ result = await session.sync()
+ assert result.errors == []
+ assert result.keys_changed and result.refreshed, "credential predating the rotation was not refreshed"
+ assert cp.refreshes == 1
+ assert len(mesh.credential.control_plane_keys) == 2
+ assert not mesh.credential.predates_rotation()
+ # The new credential is signed by the new key and no longer by the retiring one.
+ assert verify_peer_biscuit(mesh.credential.biscuit, mesh.peer_id, [cp.current.pub]).peer_id == mesh.peer_id
+ with pytest.raises(Exception):
+ verify_peer_biscuit(mesh.credential.biscuit, mesh.peer_id, [issuer.pub])
+
+ # The retiring key leaves the set: the member follows without another refresh.
+ cp.keys.pop(0)
+ result = await session.sync()
+ assert result.keys_changed and not result.refreshed
+ assert len(mesh.credential.control_plane_keys) == 1
+ nursery.cancel_scope.cancel()
+
+ async def with_timeout():
+ with trio.fail_after(30):
+ await main()
+
+ trio.run(with_timeout)
+
+
+def test_banned_peer_is_disconnected_and_refused():
+ async def main():
+ async with trio.open_nursery() as nursery:
+ _router, cp = await start_router(nursery, SigningKey())
+ mesh = AgentMesh.enroll("http://127.0.0.1:1", bootstrap_token="sbt", transport=cp.transport)
+ async with mesh.join(listen_addrs=["/ip4/127.0.0.1/tcp/0"], refresh_lead=0, control_plane_sync_interval=0) as session:
+ peer_identity = Identity.generate()
+ peer = libp2p_host(peer_identity)
+ frame = pb.AuthFrame(biscuit=cp.current.mint(peer_identity.peer_id, ROLE_NODE)).SerializeToString()
+ async with peer.run(listen_addrs=[]):
+ member_addr = multiaddr.Multiaddr(f"{session.host.get_addrs()[0]}")
+ await peer.connect(info_from_p2p_addr(member_addr))
+ await authenticate_with_peer(peer, session.host.get_id(), frame, [cp.current.pub])
+ assert peer_identity.peer_id in session.authenticated_peers
+
+ # The control plane bans the peer; the next pull evicts it.
+ cp.banned = [peer_identity.peer_id]
+ result = await session.sync()
+ assert result.errors == []
+ assert session.banned.peers() == [peer_identity.peer_id]
+ assert peer_identity.peer_id not in session.authenticated_peers
+ await trio.sleep(0.2)
+ assert peer.get_id() not in session.host.get_connected_peers()
+
+ # Its token still verifies, and it is still refused at the handshake ...
+ await peer.connect(info_from_p2p_addr(member_addr))
+ with pytest.raises(Exception):
+ await authenticate_with_peer(peer, session.host.get_id(), frame, [cp.current.pub])
+ # ... and outbound, before any dial.
+ with pytest.raises(PermissionError, match="banned"):
+ await session.connect(f"{cp.router_addr}/p2p-circuit/p2p/{peer_identity.peer_id}")
+
+ # Lifted by the control plane: the next pull unbans it.
+ cp.banned = []
+ await session.sync()
+ assert session.banned.peers() == []
+ nursery.cancel_scope.cancel()
+
+ async def with_timeout():
+ with trio.fail_after(30):
+ await main()
+
+ trio.run(with_timeout)
diff --git a/site/content/docs/guides/native-sdks.md b/site/content/docs/guides/native-sdks.md
new file mode 100644
index 00000000..94dec5b9
--- /dev/null
+++ b/site/content/docs/guides/native-sdks.md
@@ -0,0 +1,196 @@
+---
+title: "Native SDKs"
+linkTitle: "Native SDKs"
+weight: 6
+---
+
+An agent written in JavaScript or Python can be a mesh member itself, with no
+`sam-node` beside it. The SDKs under `sdk/` speak the same protocols the Go
+components speak: they enroll with the control plane, join through a router,
+find services in the mesh DHT, call MCP tools and inference or A2A endpoints,
+and publish services of their own, authorizing every caller with the same
+Datalog a `sam-node` evaluates.
+
+This guide shows the whole journey with each SDK. It assumes a running mesh:
+a control plane, at least one router, and a bootstrap token minted for the
+agent (see [Headless enrollment](../headless-enrollment/)).
+
+## Install
+
+```bash
+npm install @agent-mesh/sdk # Node.js 22 or later
+pip install agent-mesh # Python 3.11 or later
+```
+
+Both packages are published from the repository's release workflow, at the
+version of the release tag. The Python package runs on trio; under asyncio,
+use it through `anyio` with the trio backend.
+
+## Enroll and join
+
+Read the bootstrap token from a file or the environment. Do not put it on a
+command line; it would sit in `ps` output and shell history. The state
+directory keeps the identity key and the credential across restarts, so an
+agent enrolls once and resumes with `load` afterwards.
+
+JavaScript:
+
+```ts
+import { AgentMesh } from "@agent-mesh/sdk";
+
+const mesh = await AgentMesh.enroll({
+ controlPlaneUrl: "https://hub.sam-mesh.dev",
+ bootstrapTokenPath: "/run/secrets/sam-bootstrap-token",
+ stateDir: `${process.env.HOME}/.config/sam-mesh/reviewer`,
+});
+const session = await mesh.join();
+console.log(session.peerId, session.relayAddresses.map(String));
+```
+
+Python:
+
+```python
+import trio
+from agent_mesh import AgentMesh
+
+mesh = AgentMesh.enroll(
+ "https://hub.sam-mesh.dev",
+ bootstrap_token_path="/run/secrets/sam-bootstrap-token",
+ state_dir="~/.config/sam-mesh/reviewer",
+)
+
+async def main():
+ async with mesh.join() as session:
+ print(session.peer_id, session.relay_addresses)
+ ...
+
+trio.run(main)
+```
+
+`join` connects to the routers named in the credential, runs the
+`/sam/auth/1.0.0` handshake with each, requires the router role on the
+credential the router answers with, and reserves a relay slot so other
+members reach the agent through the router. While the session is open the
+SDK keeps the credential fresh, pulls keys, bans and router addresses from
+the control plane on `sam-node`'s interval, and listens to the control
+plane's gossip events, so a ban or a key rotation reaches the agent within
+seconds.
+
+## Call services
+
+Discovery is a DHT lookup by service type and name. A provider found there is
+only a peer that announced itself; the call verifies its credential before
+sending anything.
+
+```ts
+const [provider] = await session.discover("mcp", "calc");
+const addr = `${session.routers[0].addr}/p2p-circuit/p2p/${provider.peerId}`;
+const tools = await session.listTools(addr, "mcp://calc");
+const result = await session.callTool(addr, "mcp://calc", "add", { a: 1, b: 2 }, { requiredLabels: { region: "eu" } });
+console.log(result.text);
+
+const models = await session.request(addr, "inference://llm", "/v1/models");
+console.log(models.status, models.text());
+```
+
+```python
+provider = (await session.discover("mcp", "calc"))[0]
+addr = f"{session.routers[0].addr}/p2p-circuit/p2p/{provider.peer_id}"
+tools = await session.list_tools(addr, "mcp://calc")
+result = await session.call_tool(addr, "mcp://calc", "add", {"a": 1, "b": 2}, required_labels={"region": "eu"})
+print(result.text)
+
+models = await session.request(addr, "inference://llm", "/v1/models")
+print(models.status, models.text)
+```
+
+`requiredLabels` refuses a provider whose control-plane-attested labels do not
+carry the requested values, the way `sam-node`'s label gate does.
+`request` speaks `/libp2p-http` for inference and A2A services, one request
+per stream, the way `sam-node`'s egress proxy does for
+`/sam/<peer>/<type>/<name>/<path>`.
+
+## Publish services
+
+`serve` registers a service, announces it in the DHT and reports it to the
+control plane's catalog. The first call fetches the mesh policy. From then on
+every caller is authorized before anything reaches your code or your backend:
+its credential must be signed by a trusted control plane key, bound to the
+connection's peer, unexpired, and its role must be granted the service by the
+mesh policy, evaluated on the same Datalog text a `sam-node` evaluates.
+
+An MCP service takes a factory for an MCP server, one per session:
+
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+await session.serve({
+ type: "mcp",
+ name: "echo",
+ createServer: () => {
+ const server = new McpServer({ name: "echo", version: "1.0.0" });
+ server.tool("echo", { text: z.string() }, async ({ text }) => ({ content: [{ type: "text", text }] }));
+ return server;
+ },
+});
+```
+
+```python
+from agent_mesh import MCPService
+from mcp.server.mcpserver import MCPServer
+
+def create_server() -> MCPServer:
+ server = MCPServer("echo")
+
+ @server.tool()
+ def echo(text: str) -> str:
+ return text
+
+ return server
+
+await session.serve(MCPService(name="echo", create_server=create_server))
+```
+
+An inference or A2A service forwards authorized requests to a local URL or to
+a handler in the process. The caller's biscuit never reaches the backend;
+`X-Peer-Id` names the verified caller.
+
+```ts
+await session.serve({ type: "inference", name: "llm", target: "http://127.0.0.1:8000" });
+await session.serve({
+ type: "a2a",
+ name: "reviewer",
+ target: (request, caller) => new Response(`hello ${caller.peerId}`),
+});
+```
+
+```python
+from agent_mesh import HTTPRequest, HTTPResponse, HTTPService, VerifiedBiscuit
+
+await session.serve(HTTPService(type="inference", name="llm", target="http://127.0.0.1:8000"))
+
+async def card(request: HTTPRequest, caller: VerifiedBiscuit) -> HTTPResponse:
+ return HTTPResponse(status=200, body=f"hello {caller.peer_id}".encode())
+
+await session.serve(HTTPService(type="a2a", name="reviewer", target=card))
+```
+
+The mesh policy decides who may call. A role must be granted the service
+(`allowed_services: ["mcp://echo"]`, or a pattern) and a target that matches
+the agent's identity, exactly as for a service behind a `sam-node`; see
+[Mesh policy](../../reference/policy/). A caller whose role grants nothing
+receives `AuthResponse{success: false}` on the MCP stream and `403` on the
+HTTP path.
+
+## What the SDKs do not do
+
+- They do not run a sidecar API or a sandbox. An agent that needs the egress
+ policy enforcement of `sam-box` runs beside a `sam-node`.
+- They do not serve the DHT. A member is a DHT client; the routers hold the
+ records.
+- They do not run in a browser. Node.js and CPython only, until the transport
+ to routers from a browser is designed.
+
+The wire contract, the interoperability facts the tests pin, and the plan are
+in [`sdk/README.md`](https://github.com/google/sam/blob/main/sdk/README.md).
diff --git a/tests/integration/sdk_mesh_test.go b/tests/integration/sdk_mesh_test.go
index 8615336d..15c977e5 100644
--- a/tests/integration/sdk_mesh_test.go
+++ b/tests/integration/sdk_mesh_test.go
@@ -20,6 +20,7 @@ import (
"context"
"crypto/ed25519"
"encoding/base64"
+ "encoding/hex"
"encoding/json"
"fmt"
"io"
@@ -40,6 +41,7 @@ import (
"github.com/google/sam/internal/storage"
"github.com/libp2p/go-libp2p"
libp2phttp "github.com/libp2p/go-libp2p-http"
+ "github.com/libp2p/go-libp2p/core/crypto"
"github.com/libp2p/go-libp2p/core/host"
"github.com/libp2p/go-libp2p/core/network"
"github.com/libp2p/go-libp2p/core/peer"
@@ -166,6 +168,15 @@ func TestNativeSDKsMesh(t *testing.T) {
_, portStr, _ := net.SplitHostPort(srv.Addr())
cpPort, _ := strconv.Atoi(portStr)
+ // Bans and rotations reach the mesh as gossip events through the routers,
+ // as the sam-control-plane binary publishes them.
+ publisher, err := controlplane.NewMeshPublisher(context.Background(), store, 500*time.Millisecond)
+ if err != nil {
+ t.Fatalf("failed to start mesh event publisher: %v", err)
+ }
+ t.Cleanup(func() { _ = publisher.Close() })
+ srv.SetMeshAdapter(publisher)
+
// The router enrolls through OIDC with group "routers" and the node with
// user mock-user. Every member holds the node role, which may reach any
// service on any target; the SDK members get it from their bootstrap
@@ -437,6 +448,127 @@ bindings:
t.Errorf("%s admitted peers %v lack %s (%s)", m.name, peers, other.name, other.report.PeerID)
}
}
+ }
+
+ // Control plane state reaches the members while they run. A ban travels
+ // as a gossip event through the router and is enforced without a pull;
+ // a key rotation lands with the next pull, and a credential that
+ // predates it is refreshed under the new key.
+ t.Run("ban-and-rotation", func(t *testing.T) {
+ // An enrolled peer the control plane can ban: a node record, admitted
+ // by every member over the router.
+ outcast := newAdmittedGoPeer(t, ctx, cpPriv, routerAddr)
+ outcastBiscuit := goHostBiscuit(t, cpPriv, outcast.ID())
+ outcastPub, err := crypto.MarshalPublicKey(outcast.Peerstore().PubKey(outcast.ID()))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := store.EnrollNode(ctx, &storage.EnrolledNode{
+ PeerID: outcast.ID().String(),
+ PublicKey: outcastPub,
+ Biscuit: outcastBiscuit,
+ Role: api.RoleNode,
+ EnrollmentType: "BOOTSTRAP",
+ EnrolledAt: time.Now(),
+ ExpiresAt: time.Now().Add(time.Hour),
+ }); err != nil {
+ t.Fatalf("failed to enroll the outcast: %v", err)
+ }
+ for _, m := range members {
+ sdkPeer, _ := peer.Decode(m.report.PeerID)
+ dialCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+ if err := outcast.Connect(dialCtx, peer.AddrInfo{ID: sdkPeer, Addrs: []multiaddr.Multiaddr{multiaddr.StringCast(m.report.RelayAddresses[0])}}); err != nil {
+ cancel()
+ t.Fatalf("outcast could not reach %s: %v", m.name, err)
+ }
+ cancel()
+ authHandshake(t, ctx, outcast, sdkPeer, outcastBiscuit)
+ if !contains(m.peers(t), outcast.ID().String()) {
+ t.Fatalf("%s did not admit the outcast before the ban", m.name)
+ }
+ }
+
+ // The operator bans it. The event goes control plane -> router -> members.
+ revokeBody, _ := proto.Marshal(&api.TokenRevokeRequest{PeerId: outcast.ID().String()})
+ req, _ := http.NewRequest(http.MethodPost, baseURL+"/admin/revoke", bytes.NewReader(revokeBody))
+ req.Header.Set("Authorization", "Bearer "+adminToken)
+ req.Header.Set("Content-Type", "application/x-protobuf")
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatalf("POST /admin/revoke: %v", err)
+ }
+ _ = resp.Body.Close()
+ if resp.StatusCode != http.StatusOK {
+ t.Fatalf("POST /admin/revoke: %s", resp.Status)
+ }
+ for _, m := range members {
+ state := m.bannedUntil(t, outcast.ID().String(), 10*time.Second)
+ if contains(state.AuthenticatedPeers, outcast.ID().String()) {
+ t.Errorf("%s kept the outcast admitted after the ban", m.name)
+ }
+ // Its credential still verifies; it is refused all the same.
+ sdkPeer, _ := peer.Decode(m.report.PeerID)
+ if err := tryAuthHandshake(ctx, outcast, sdkPeer, multiaddr.StringCast(m.report.RelayAddresses[0]), outcastBiscuit); err == nil {
+ t.Errorf("%s admitted the banned outcast again", m.name)
+ }
+ // A pull agrees with the event and does not lift the ban.
+ if res := m.sync(t); !contains(res.Banned, outcast.ID().String()) {
+ t.Errorf("%s: /info does not list the outcast as banned after the pull: %+v", m.name, res)
+ }
+ }
+
+ // The control plane rotates its signing key; the retiring key stays
+ // valid for its grace period, and the rotation is announced as the
+ // sam-control-plane binary announces it. A member learns the new key
+ // from the event or from its next pull, and since its credential
+ // predates the rotation, refreshes it under the new key.
+ newPub, newPriv, err := ed25519.GenerateKey(nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if err := store.RotateKeys(ctx, newPriv, newPub, time.Hour); err != nil {
+ t.Fatalf("RotateKeys: %v", err)
+ }
+ if err := publisher.PublishEvent(ctx, api.MeshEvent_KEY_ROTATION, "", newPub); err != nil {
+ t.Fatalf("publish KEY_ROTATION: %v", err)
+ }
+ for _, m := range members {
+ // Idempotent: the event may already have brought a pull forward.
+ res := m.sync(t)
+ if !contains(res.TrustedKeys, hex.EncodeToString(newPub)) || !contains(res.TrustedKeys, hex.EncodeToString(cpPub)) {
+ t.Fatalf("%s trusts %v after the rotation, want both keys", m.name, res.TrustedKeys)
+ }
+ if res.Biscuit == m.report.Biscuit {
+ t.Fatalf("%s still holds the credential minted before the rotation", m.name)
+ }
+ fresh, err := base64.StdEncoding.DecodeString(res.Biscuit)
+ if err != nil {
+ t.Fatal(err)
+ }
+ sdkPeer, _ := peer.Decode(m.report.PeerID)
+ if _, err := identity.VerifyBiscuitAndGetExpiry(fresh, sdkPeer, []ed25519.PublicKey{newPub}, 5*time.Second); err != nil {
+ t.Fatalf("%s refreshed credential does not verify under the new key: %v", m.name, err)
+ }
+ if _, err := identity.VerifyBiscuitAndGetExpiry(fresh, sdkPeer, []ed25519.PublicKey{cpPub}, 5*time.Second); err == nil {
+ t.Fatalf("%s refreshed credential still verifies under the retiring key", m.name)
+ }
+ // The mesh keeps working under the new credential: the sam-node
+ // learned the key from the same event.
+ deadline := time.Now().Add(10 * time.Second)
+ for {
+ cred := m.authRaw(t, samNode.p2pAddr)
+ if cred.OK && cred.PeerID == samNode.peerID.String() {
+ break
+ }
+ if time.Now().After(deadline) {
+ t.Fatalf("%s could not authenticate with the node under its refreshed credential: %+v", m.name, cred)
+ }
+ time.Sleep(200 * time.Millisecond)
+ }
+ }
+ })
+
+ for _, m := range members {
m.quit(t)
}
}
@@ -547,6 +679,57 @@ func (m *sdkMember) peers(t *testing.T) []string {
return res.AuthenticatedPeers
}
+// sdkBanned answers a {"cmd":"banned"} command.
+type sdkBanned struct {
+ Banned []string `json:"banned"`
+ AuthenticatedPeers []string `json:"authenticated_peers"`
+}
+
+// bannedUntil polls the member's ban set, without asking it to pull, until
+// wantPeer is in it: this is how long a gossip event takes to land.
+func (m *sdkMember) bannedUntil(t *testing.T, wantPeer string, timeout time.Duration) sdkBanned {
+ t.Helper()
+ deadline := time.Now().Add(timeout)
+ for {
+ var res sdkBanned
+ if line := m.send(t, map[string]string{"cmd": "banned"}); json.Unmarshal(line, &res) != nil {
+ t.Fatalf("%s member: banned answered %q", m.name, line)
+ }
+ if contains(res.Banned, wantPeer) {
+ return res
+ }
+ if time.Now().After(deadline) {
+ t.Fatalf("%s member never learned the ban of %s from the gossip event; banned=%v\nstderr:\n%s", m.name, wantPeer, res.Banned, m.stderr.String())
+ }
+ time.Sleep(200 * time.Millisecond)
+ }
+}
+
+// sdkSyncResult answers a {"cmd":"sync"} command.
+type sdkSyncResult struct {
+ OK bool `json:"ok"`
+ Error string `json:"error"`
+ KeysChanged bool `json:"keys_changed"`
+ Refreshed bool `json:"refreshed"`
+ TrustedKeys []string `json:"trusted_keys"`
+ Biscuit string `json:"biscuit"`
+ Banned []string `json:"banned"`
+ RouterAddresses []string `json:"router_addresses"`
+}
+
+// sync asks the member to pull from the control plane now; every part must land.
+func (m *sdkMember) sync(t *testing.T) sdkSyncResult {
+ t.Helper()
+ var res sdkSyncResult
+ if line := m.send(t, map[string]string{"cmd": "sync"}); json.Unmarshal(line, &res) != nil {
+ t.Fatalf("%s member: sync answered %q", m.name, line)
+ }
+ if !res.OK {
+ t.Fatalf("%s member: sync failed: %s", m.name, res.Error)
+ }
+ return res
+}
+
// sdkProvider is one entry of a {"cmd":"discover"} answer.
type sdkProvider struct {
PeerID string `json:"peer_id"`
@@ -874,6 +1057,39 @@ func authHandshake(t *testing.T, ctx context.Context, h host.Host, target peer.I
return resp.Biscuit
}
+// tryAuthHandshake reconnects to target through addr if needed and runs the
+// client side of /sam/auth/1.0.0, returning the error a refusal produces: a
+// connection the gate denies, or a stream closed without an answer.
+func tryAuthHandshake(ctx context.Context, h host.Host, target peer.ID, addr multiaddr.Multiaddr, biscuit []byte) error {
+ dialCtx, cancel := context.WithTimeout(network.WithAllowLimitedConn(ctx, "auth"), 10*time.Second)
+ defer cancel()
+ if err := h.Connect(dialCtx, peer.AddrInfo{ID: target, Addrs: []multiaddr.Multiaddr{addr}}); err != nil {
+ return err
+ }
+ s, err := h.NewStream(dialCtx, target, api.AuthProtocolID)
+ if err != nil {
+ return err
+ }
+ defer func() { _ = s.Close() }()
+ _ = s.SetDeadline(time.Now().Add(5 * time.Second))
+ frame, _ := proto.Marshal(&api.AuthFrame{Biscuit: biscuit})
+ if err := msgio.NewVarintWriter(s).WriteMsg(frame); err != nil {
+ return err
+ }
+ msg, err := msgio.NewVarintReaderSize(s, 64*1024).ReadMsg()
+ if err != nil {
+ return err
+ }
+ var resp api.AuthResponse
+ if err := proto.Unmarshal(msg, &resp); err != nil {
+ return err
+ }
+ if !resp.Success {
+ return fmt.Errorf("refused: %s", resp.Error)
+ }
+ return nil
+}
+
// refuseForgedFrame checks that target answers a frame it cannot verify
// with a closed stream and nothing else, as sam-node does.
func refuseForgedFrame(t *testing.T, ctx context.Context, h host.Host, target peer.ID) {