@agentmesh-p2p/sdk 0.0.0-stage → 0.1.0

package/dist/conformance-join.js

@@ -0,0 +1,257 @@
+// 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.
+// Mesh member driven by tests/integration/sdk_mesh_test.go: enrolls, joins
+// the mesh through a real router, prints one JSON line describing the
+// session, then takes JSON commands on stdin, one per line, until stdin
+// closes:
+//
+//   {"cmd": "auth", "addr": "<multiaddr>"}  connect (through a relay when the
+//                                            address says /p2p-circuit) and
+//                                            run the auth handshake
+//   {"cmd": "discover", "type": "mcp", "name": "calc"}
+//                                            DHT lookup for a service's providers
+//   {"cmd": "tools", "addr": "<multiaddr>", "service": "mcp://calc",
+//    "required_labels": {"region": "eu"}}   list a provider's tools; the labels,
+//                                            if given, must be on its credential
+//   {"cmd": "call", "addr": "<multiaddr>", "service": "mcp://calc",
+//    "tool": "add", "args": {...}, "required_labels": {...}}
+//                                            call one tool
+//   {"cmd": "accept", "name": "agent", "target": "<url>"}
+//                                            accept A2A requests for this
+//                                            member's agent; without target,
+//                                            a handler in this process answers
+//   {"cmd": "http", "addr": "<multiaddr>", "service": "a2a://agent",
+//    "path": "/card", "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;
+// the Python SDK ships the same runner (python -m agent_mesh.conformance_join).
+import { createInterface } from "node:readline";
+import { DEFAULT_A2A_NAME } from "./libp2p-http.js";
+import { AgentMesh } from "./mesh.js";
+function requireEnv(name) {
+    const v = process.env[name];
+    if (!v) {
+        throw new Error(`${name} is required`);
+    }
+    return v;
+}
+function emit(obj) {
+    process.stdout.write(JSON.stringify(obj) + "\n");
+}
+/**
+ * Labels from an environment variable written "k=v,k2=v2"; a pair without
+ * "=" is refused (parseRequiredLabels), so a typo never switches a floor off.
+ */
+function labelsFromEnv(name) {
+    const out = {};
+    for (const pair of (process.env[name] ?? "").split(",")) {
+        if (pair.trim() === "") {
+            continue;
+        }
+        const eq = pair.indexOf("=");
+        if (eq === -1) {
+            throw new Error(`${name}: invalid label ${JSON.stringify(pair.trim())}: expected key=value`);
+        }
+        out[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+    }
+    return out;
+}
+function failure(cmd, err) {
+    return { cmd, ok: false, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) };
+}
+function requiredLabelsOf(command) {
+    return command.required_labels !== undefined ? { requiredLabels: command.required_labels } : {};
+}
+async function handle(session, command) {
+    try {
+        switch (command.cmd) {
+            case "auth": {
+                const timeoutMs = command.timeout_ms !== undefined ? Number(command.timeout_ms) : 15_000;
+                const verified = await session.authenticate(command.addr ?? "", AbortSignal.timeout(timeoutMs));
+                return {
+                    cmd: "auth",
+                    ok: true,
+                    peer_id: verified.peerId,
+                    roles: verified.roles,
+                    labels: verified.labels,
+                    expiration: Math.floor(verified.expiration.getTime() / 1000),
+                };
+            }
+            case "discover": {
+                const providers = await session.discover((command.type ?? "mcp"), command.name);
+                return { cmd: "discover", ok: true, providers: providers.map((p) => ({ peer_id: p.peerId, addrs: p.addrs })) };
+            }
+            case "tools": {
+                const tools = await session.listTools(command.addr ?? "", command.service ?? "", { signal: AbortSignal.timeout(15_000), ...requiredLabelsOf(command) });
+                return { cmd: "tools", ok: true, tools: tools.map((t) => t.name) };
+            }
+            case "call": {
+                const result = await session.callTool(command.addr ?? "", command.service ?? "", command.tool ?? "", command.args ?? {}, {
+                    signal: AbortSignal.timeout(15_000),
+                    ...requiredLabelsOf(command),
+                });
+                return { cmd: "call", ok: true, is_error: result.isError, text: result.text };
+            }
+            case "peers":
+                return { cmd: "peers", authenticated_peers: [...session.authenticatedPeers.keys()].sort() };
+            case "routers":
+                return {
+                    cmd: "routers",
+                    ok: true,
+                    routers: session.routers.map((r) => r.peerId),
+                    relay_addresses: session.relayAddresses.map((ma) => ma.toString()),
+                    go_away_received: Object.fromEntries(session.goAwayReceived),
+                };
+            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 "accept": {
+                const spec = command.target !== undefined
+                    ? { url: command.target }
+                    : {
+                        handler: (request, caller) => new Response(JSON.stringify({ sdk: "js", peer: caller.peerId, method: request.method, path: new URL(request.url).pathname }), {
+                            headers: { "content-type": "application/json" },
+                        }),
+                    };
+                spec.name = command.name ?? DEFAULT_A2A_NAME;
+                const service = await session.acceptA2A(spec);
+                return { cmd: "accept", ok: true, service };
+            }
+            case "http": {
+                const res = await session.request(command.addr ?? "", command.service ?? "", command.path ?? "/", {
+                    method: command.method ?? "GET",
+                    ...(command.headers !== undefined ? { headers: command.headers } : {}),
+                    ...(command.body !== undefined ? { body: command.body } : {}),
+                    signal: AbortSignal.timeout(15_000),
+                });
+                return { cmd: "http", ok: true, status: res.status, headers: res.headers, body: res.text() };
+            }
+            default:
+                return failure(command.cmd, new Error(`unknown command ${JSON.stringify(command.cmd)}`));
+        }
+    }
+    catch (err) {
+        return failure(command.cmd, err);
+    }
+}
+async function main() {
+    const controlPlaneUrl = requireEnv("AGENTMESH_CONTROL_PLANE_URL");
+    // Enrollment is with a bootstrap token or a platform JWT, as the examples
+    // offer; a JWT file is read again at every refresh.
+    const bootstrapTokenPath = process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH;
+    const jwtPath = process.env.AGENTMESH_JWT_PATH;
+    if ((bootstrapTokenPath === undefined) === (jwtPath === undefined)) {
+        throw new Error("exactly one of AGENTMESH_BOOTSTRAP_TOKEN_PATH or AGENTMESH_JWT_PATH is required");
+    }
+    const stateDir = requireEnv("AGENTMESH_SDK_STATE_DIR");
+    const allowInsecure = process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "1";
+    const listenAddrs = (process.env.AGENTMESH_SDK_LISTEN_ADDRS ?? "").split(",").filter((a) => a !== "");
+    // Labels this member declares at enrollment; the policy's allowed_labels
+    // decide whether the control plane attests them. AGENTMESH_SDK_EGRESS_REQUIRE_LABELS
+    // is the floor every provider this member calls must attest.
+    const labels = labelsFromEnv("AGENTMESH_SDK_LABELS");
+    const egressRequireLabels = labelsFromEnv("AGENTMESH_SDK_EGRESS_REQUIRE_LABELS");
+    const routerSelector = labelsFromEnv("AGENTMESH_SDK_ROUTER_SELECTOR");
+    const routerPrefer = labelsFromEnv("AGENTMESH_SDK_ROUTER_PREFER");
+    const routerCount = process.env.AGENTMESH_SDK_ROUTER_COUNT;
+    const redialBackoffs = (process.env.AGENTMESH_SDK_REDIAL_BACKOFF_SECONDS ?? "")
+        .split(",")
+        .filter((s) => s.trim() !== "")
+        .map((s) => Number(s.trim()) * 1000);
+    // AGENTMESH_SDK_RELAY_CHECK_SECONDS shortens how often the relay reservation is
+    // checked, so a test that moves a router sees the member follow it within
+    // its budget.
+    const relayCheck = process.env.AGENTMESH_SDK_RELAY_CHECK_SECONDS;
+    const relayOptions = relayCheck !== undefined && relayCheck !== "" ? { relayCheckIntervalMs: Number(relayCheck) * 1000 } : {};
+    const mesh = await AgentMesh.enroll({
+        controlPlaneUrl,
+        allowInsecure,
+        stateDir,
+        bootstrapTokenPath,
+        jwtPath,
+        pollIntervalMs: 200,
+        ...(Object.keys(labels).length > 0 ? { labels } : {}),
+    });
+    // The test drives every pull itself; only gossip events bring one forward.
+    // AGENTMESH_SDK_ROUTERS, peer IDs, joins through those routers only, so the test
+    // can put two members on different routers.
+    const only = new Set((process.env.AGENTMESH_SDK_ROUTERS ?? "").split(",").filter((id) => id !== ""));
+    const routerAddresses = only.size === 0 ? undefined : mesh.credential.routerAddresses.filter((a) => [...only].some((id) => a.endsWith(`/p2p/${id}`)));
+    const session = await mesh.join({
+        listenAddrs,
+        ...(routerAddresses !== undefined ? { routerAddresses } : {}),
+        ...(routerCount !== undefined && routerCount !== "" ? { routers: Number(routerCount) } : {}),
+        ...(Object.keys(routerSelector).length > 0 ? { routerSelector } : {}),
+        ...(Object.keys(routerPrefer).length > 0 ? { routerPrefer } : {}),
+        ...(redialBackoffs.length > 0 ? { routerRedialBackoffsMs: redialBackoffs } : {}),
+        ...(Object.keys(egressRequireLabels).length > 0 ? { egressRequireLabels } : {}),
+        ...relayOptions,
+        signal: AbortSignal.timeout(20_000),
+        controlPlaneSyncIntervalMs: 0,
+        controlPlaneSyncJitterMs: 0,
+    });
+    emit({
+        sdk: "js",
+        peer_id: session.peerId,
+        routers: session.routers.map((r) => ({ peer_id: r.peerId, addr: r.addr.toString(), roles: r.credential.roles })),
+        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 })) {
+        if (line.trim() === "") {
+            continue;
+        }
+        let command;
+        try {
+            command = JSON.parse(line);
+        }
+        catch (err) {
+            emit({ ok: false, error: `not JSON: ${err instanceof Error ? err.message : String(err)}` });
+            continue;
+        }
+        if (command.cmd === "quit") {
+            emit({ cmd: "quit", ok: true });
+            break;
+        }
+        emit(await handle(session, command));
+    }
+    // Leaving must not depend on every peer closing its side promptly.
+    await Promise.race([session.close(), new Promise((resolve) => setTimeout(resolve, 5_000).unref())]);
+    process.exit(0);
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/conformance.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/conformance.js

@@ -0,0 +1,60 @@
+// 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.
+// Conformance runner driven by tests/integration/sdk_enroll_test.go: enrolls
+// against a real control plane, refreshes, reloads from disk and reports
+// what it holds as JSON on stdout for the Go side to verify. The Python SDK
+// ships the same runner (python -m agent_mesh.conformance) with the same
+// environment and output, so one Go test checks both.
+//
+//   AGENTMESH_CONTROL_PLANE_URL      base URL of the control plane
+//   AGENTMESH_BOOTSTRAP_TOKEN_PATH   file holding a bootstrap token
+//   AGENTMESH_SDK_STATE_DIR          directory for identity and credential
+//   AGENTMESH_INSECURE_CONTROL_PLANE "1" to accept plaintext http:// off loopback
+import { AgentMesh } from "./mesh.js";
+const hex = (b) => Buffer.from(b).toString("hex");
+const b64 = (b) => Buffer.from(b).toString("base64");
+function requireEnv(name) {
+    const v = process.env[name];
+    if (!v) {
+        throw new Error(`${name} is required`);
+    }
+    return v;
+}
+async function main() {
+    const controlPlaneUrl = requireEnv("AGENTMESH_CONTROL_PLANE_URL");
+    const bootstrapTokenPath = requireEnv("AGENTMESH_BOOTSTRAP_TOKEN_PATH");
+    const stateDir = requireEnv("AGENTMESH_SDK_STATE_DIR");
+    const allowInsecure = process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "1";
+    const mesh = await AgentMesh.enroll({ controlPlaneUrl, allowInsecure, stateDir, bootstrapTokenPath, pollIntervalMs: 200 });
+    const enrolled = mesh.credential;
+    const reloaded = await AgentMesh.load({ allowInsecure, stateDir });
+    const refreshed = await reloaded.refresh();
+    process.stdout.write(JSON.stringify({
+        sdk: "js",
+        peer_id: mesh.peerId,
+        public_key: hex(mesh.identity.publicKeyRaw),
+        biscuit: b64(enrolled.biscuit),
+        expiration: enrolled.expiration,
+        control_plane_keys: enrolled.controlPlaneKeys.map(hex),
+        router_addresses: enrolled.routerAddresses,
+        reloaded_peer_id: reloaded.peerId,
+        refreshed_biscuit: b64(refreshed.biscuit),
+        refreshed_expiration: refreshed.expiration,
+        auth_frame: b64(reloaded.authFrame("mcp://echo")),
+    }) + "\n");
+}
+main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/controlplane.d.ts

@@ -0,0 +1,123 @@
+import { type ControlPlaneInfoResponse, type KeysResponse } from "./gen/agentmesh_pb.ts";
+import type { Identity } from "./identity.ts";
+export declare const PROTOBUF_CONTENT_TYPE = "application/x-protobuf";
+export declare const HEADER_CHALLENGE_TIMESTAMP = "X-Mesh-Challenge-Ts";
+export declare const HEADER_CHALLENGE_SIGNATURE = "X-Mesh-Challenge-Sig";
+export declare const STALE_CHALLENGE_TIMESTAMP_MESSAGE = "stale or invalid challenge timestamp";
+/** The role a plain mesh member enrolls with (api.RoleNode). */
+export declare const ROLE_NODE = "mesh:role:node";
+/** How far a signed /keys response's timestamp may drift from our clock. */
+export declare const KEYS_RESPONSE_FRESHNESS_MS: number;
+/** A non-2xx answer from the control plane. */
+export declare class ControlPlaneError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(path: string, status: number, body: string);
+}
+/** The control plane answered, and the answer is a refusal. */
+export declare class EnrollmentRejectedError extends Error {
+    constructor(message: string);
+}
+/**
+ * The /keys answer is signed by no key this member trusts: every key it
+ * holds has left the control plane's set, so its credential cannot be
+ * verified or refreshed either.
+ */
+export declare class KeysNotTrustedError extends Error {
+    constructor();
+}
+/** Plaintext http:// to a host that is not loopback; see api.ValidateControlPlaneTransport. */
+export declare class InsecureControlPlaneURLError extends Error {
+    constructor(url: string);
+}
+export interface ControlPlaneClientOptions {
+    /** Base URL, e.g. https://mesh.example.com. */
+    url: string;
+    /** Accept plaintext http:// to a non-loopback host. Off by default. */
+    allowInsecure?: boolean;
+    /** Per-request timeout. */
+    timeoutMs?: number;
+    /** Injection point for tests. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Injection point for clock-skew tests; returns unix milliseconds. Defaults to Date.now. */
+    now?: () => number;
+}
+/** What an approved enrollment hands the caller. */
+export interface Enrollment {
+    biscuit: Uint8Array;
+    /** Unix seconds at which the biscuit expires. */
+    expiration: number;
+    controlPlanePublicKey: Uint8Array;
+    routerAddresses: string[];
+}
+export interface EnrollBootstrapParams {
+    identity: Identity;
+    bootstrapToken: string;
+    /** Must equal the role the bootstrap token was minted for. Defaults to ROLE_NODE. */
+    role?: string;
+    labels?: Record<string, string>;
+    /** Overrides the control plane's suggested poll interval while pending. */
+    pollIntervalMs?: number;
+    /** Bounds the wait for an operator to approve a pending enrollment. */
+    signal?: AbortSignal;
+}
+export interface RegisterParams {
+    identity: Identity;
+    jwt: string;
+    role?: string;
+    labels?: Record<string, string>;
+}
+export interface RefreshParams {
+    identity: Identity;
+    /** The biscuit currently held; only the last one issued is redeemable. */
+    biscuit: Uint8Array;
+    /** Optional fresh platform/OIDC JWT for continuous attestation on refresh. */
+    jwt?: string | undefined;
+}
+export interface PolicyRulesParams {
+    identity: Identity;
+    biscuit: Uint8Array;
+}
+export interface RefreshResult {
+    biscuit: Uint8Array;
+    /** Unix seconds. */
+    expiration: number;
+}
+/** Mirrors api.ValidateControlPlaneTransport: https, or http to loopback only. */
+export declare function validateControlPlaneURL(rawUrl: string, allowInsecure?: boolean): URL;
+/**
+ * Returns the key set if it is fresh and at least one listed key is already
+ * trusted and its signature verifies. Mirrors api.VerifyKeysResponse.
+ */
+export declare function verifyKeysResponse(resp: KeysResponse, trusted: Uint8Array[], nowMs?: number): Uint8Array[];
+export declare class ControlPlaneClient {
+    #private;
+    readonly url: URL;
+    constructor(options: ControlPlaneClientOptions);
+    /** GET /info: OIDC settings, router addresses and the ban list. Unauthenticated. */
+    info(): Promise<ControlPlaneInfoResponse>;
+    /**
+     * GET /keys: every signing key the control plane currently trusts,
+     * verified against a key the caller already trusts (the enrollment key).
+     */
+    keys(trusted: Uint8Array[]): Promise<Uint8Array[]>;
+    /**
+     * POST /enroll with a bootstrap token, then GET /enroll/status until an
+     * operator approves the request if the mesh is not on auto-approve.
+     */
+    enrollBootstrap(params: EnrollBootstrapParams): Promise<Enrollment>;
+    /** POST /register with an OIDC ID token. */
+    register(params: RegisterParams): Promise<Enrollment>;
+    /**
+     * POST /refresh: trades the biscuit for a fresh one. The old one is
+     * spent by this call; callers must persist the result before using it.
+     */
+    refresh(params: RefreshParams): Promise<RefreshResult>;
+    /**
+     * GET /policies: the mesh policy as the Datalog rules a provider adds to
+     * its authorizer, one per entry, rendered by the control plane. The text
+     * is the contract; nothing here derives rules from roles and bindings.
+     */
+    policyRules(identity: Identity, biscuit: Uint8Array): Promise<string[]>;
+    policyRules(params: PolicyRulesParams): Promise<string[]>;
+}