Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk: follow the control plane and publish, milestone 5
Antonio Ojea0b16a9e09776
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 3c9c27aa..2e60d005 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -35,3 +35,49 @@ jobs:args: release --cleanenv: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.shnew file mode 100755index 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.mdindex 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: itfinds a service in the DHT and calls it through the router, verifying theprovider 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, eachpinned 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 Nodeduplex and runs Node's HTTP server and client on it; the Python SDKdrives `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 controlplane'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 9seconds 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 therunners `sdk/js/src/conformance-join.ts` and`sdk/python/src/agent_mesh/conformance_join.py`: each joins, prints what itholds, 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 withdiff --git a/sdk/js/README.md b/sdk/js/README.mdindex 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. Passand the mesh policy rules from `GET /policies`.- `src/serve.ts`: the `/sam/mcp/1.0.0` server, the `/libp2p-http` serverand 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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, registerChallexport { 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.tsindex 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.tsindex 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): StreamSoexport 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: ProviderOpttry {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.tsindex 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 = {}): Promthrow 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 = {}): PromauthStreamHandler({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 = {}): Promthrow 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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__.pyindex 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_framefrom .discovery import DHT_PROTOCOL, DiscoveredProvider, find_providers, parse_service_target, provide, service_keyfrom .identity import Identity, libp2p_public_key, peer_id_from_public_key, verify_ed25519from .mcp_client import LabelsNotSatisfiedError, ToolCallResult, open_mcp_session, require_labels-from .mesh import AgentMesh+from .mesh import AgentMesh, ControlPlaneSyncfrom .relay import dial_through_relay, reserve_relayfrom .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.pyindex 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)+ returntry: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.pyindex 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 exitEach 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.pyindex 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.pyindex 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 annotationsimport osimport threading-from dataclasses import replace+import time+from dataclasses import dataclass, field, replacefrom pathlib import Pathfrom 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 planeminted 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 biscuitpassself._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 plusthe 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.pyindex 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]] = Noneclass ServiceRegistry:@@ -189,6 +191,10 @@ def mcp_stream_handler(registry: ServiceRegistry, options: ProviderOptions, protawait stream.close()returnframe = 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()+ returntry: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.pyindex 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 annotationsimport logging+import randomimport timefrom contextlib import asynccontextmanagerfrom dataclasses import dataclass, field@@ -24,11 +25,19 @@ from typing import TYPE_CHECKING, Any, AsyncIterator, Mapping, Optional, Sequencimport multiaddrimport triofrom libp2p.abc import IHost+from libp2p.custom_types import TProtocolfrom libp2p.peer.id import IDfrom 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_servicefrom mcp import ClientSessionfrom ._proto import circuit_pb2 as circuit+from ._proto import sam_pb2 as pbfrom .auth import AUTH_PROTOCOL, MCP_PROTOCOL, auth_stream_handler, authenticate_with_peerfrom .authorizer import ProviderAuthorizerOptionsfrom .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_eventif TYPE_CHECKING:- from .mesh import AgentMesh+ from .mesh import AgentMesh, ControlPlaneSynclogger = logging.getLogger("agent_mesh")@@ -59,6 +69,10 @@ MIN_REFRESH_DELAY = 2.0DEFAULT_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_SYNCprovide_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)@propertydef 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 targetinfo = 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 thepeer'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: SLF001try:- yield MeshSession(- mesh=mesh,- host=host,- routers=admitted,- authenticated_peers=authenticated,- policy_sync_interval=policy_sync_interval,- provide_interval=provide_interval,- _nursery=nursery,- )+ yield sessionfinally: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.pynew file mode 100644index 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 eventdiff --git a/sdk/python/tests/test_sync.py b/sdk/python/tests/test_sync.pynew file mode 100644index 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.mdnew file mode 100644index 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.goindex 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.Ireturn 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) {