@agentmesh-p2p/sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @agentmesh-p2p/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native JavaScript SDK for joining an Agent Mesh from inside the agent
+process. It replaces the `agentmesh-node` sidecar for agents written for Node.js
+or running in a browser page:
+the agent enrolls with the control plane, joins the mesh through a router,
+finds services and calls them, answers A2A requests for the agent itself,
+and follows the control plane's keys, bans and policy while it runs. It
+publishes no service; a tool or a model others should find by name runs
+behind a `agentmesh-node`.
+
+Guide: [google.github.io/agentmesh/docs/guides/native-sdks](https://google.github.io/agentmesh/docs/guides/native-sdks/),
+from an empty machine to two programs on a mesh.
+Source: [github.com/google/agentmesh/tree/main/sdk/js](https://github.com/google/agentmesh/tree/main/sdk/js).
+
+## Install
+
+```bash
+npm install @agentmesh-p2p/sdk @modelcontextprotocol/sdk zod
+```
+
+Requires Node.js 22.18 or later. In a browser, bundle it with the page
+(the package's `browser` field selects the browser files); the guide's
+[In a browser](https://google.github.io/agentmesh/docs/guides/native-sdks/#in-a-browser)
+section has the details and an example page.
+
+## Use
+
+Both programs below are in
+[`examples/`](https://github.com/google/agentmesh/tree/main/sdk/js/examples) and
+run against a real mesh in the repository's tests. They read the mesh from
+`AGENTMESH_CONTROL_PLANE_URL` and the enrollment token from
+`AGENTMESH_BOOTSTRAP_TOKEN_PATH`; the guide shows how to get both from `agentmesh-one`
+or from the operator of an existing mesh.
+
+Find a service and call it:
+
+<!-- embed: sdk/js/examples/call.ts -->
+```ts
+// Calls something on the mesh: a tool of an MCP service or a path of an
+// inference or A2A service someone published, found by name, or an agent that
+// published nothing, reached by its peer ID.
+//
+//   node call.js mcp://everything echo '{"message": "hi"}'
+//   node call.js inference://ollama /v1/models
+//   node call.js 12D3KooW... a2a://agent /card
+//
+// AGENTMESH_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// AGENTMESH_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// AGENTMESH_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in AGENTMESH_STATE_DIR; later runs resume from there without it.
+import { homedir } from "node:os";
+import { AgentMesh, type DiscoveredProvider } from "@agentmesh-p2p/sdk";
+
+let argv = process.argv.slice(2);
+// A first argument that is not a service target is the peer ID of an agent.
+let peerId: string | undefined;
+if (argv[0] !== undefined && !argv[0].includes("://")) {
+  [peerId, ...argv] = argv as [string, ...string[]];
+}
+const [service = peerId !== undefined ? "a2a://agent" : "mcp://everything", toolOrPath = peerId !== undefined ? "/card" : "echo", args = '{"message": "hi"}'] = argv;
+
+const mesh = await AgentMesh.enroll({
+  controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
+  bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
+  jwtPath: process.env.AGENTMESH_JWT_PATH,
+  stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/caller`,
+  // A plaintext http:// control plane is otherwise accepted only on loopback.
+  allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
+});
+const session = await mesh.join();
+console.log(`on the mesh as ${session.peerId}`);
+
+// The peer to call: an agent named by ID, or a provider of a published service.
+let provider: DiscoveredProvider = { peerId: peerId ?? "", addrs: [] };
+if (peerId !== undefined) {
+  // An agent is not in the discovery table; the SDK finds the path to its
+  // peer ID through the routers.
+  await session.connect(peerId);
+} else {
+  const providers = await session.discover(service);
+  if (providers.length === 0) {
+    throw new Error(`no member of the mesh serves ${service}`);
+  }
+  // A provider record can outlive its member; the first that answers is used.
+  let reached = false;
+  for (const candidate of providers) {
+    try {
+      await session.connect(candidate);
+      provider = candidate;
+      reached = true;
+      break;
+    } catch (err) {
+      console.error(`${candidate.peerId}: ${(err as Error).message}`);
+    }
+  }
+  if (!reached) {
+    throw new Error(`no provider of ${service} is reachable`);
+  }
+}
+console.log(`${service} is served by ${provider.peerId}`);
+
+if (service.startsWith("mcp://")) {
+  const tools = await session.listTools(provider, service);
+  console.log(`tools: ${tools.map((t) => t.name).join(", ")}`);
+  const result = await session.callTool(provider, service, toolOrPath, JSON.parse(args));
+  console.log(result.text.join("\n"));
+} else {
+  const response = await session.request(provider, service, toolOrPath);
+  console.log(response.status, response.text());
+}
+
+await session.close();
+```
+<!-- /embed -->
+
+Be an agent others can call. Nothing is published; a caller reaches the
+agent by its peer ID, the one it prints, through a router:
+
+<!-- embed: sdk/js/examples/agent.ts -->
+```ts
+// An agent on the mesh: joins, then answers A2A requests from other members
+// until stopped. It publishes nothing. There is no service name to look up; a
+// caller reaches the agent by its peer ID, through a router, as a2a://agent.
+// The mesh policy decides which members may call; the SDK turns the others
+// away before anything reaches this code.
+//
+//   node agent.js                        # answered by the handler below
+//   node agent.js http://127.0.0.1:9999  # forwarded to an A2A server beside it
+//
+// AGENTMESH_CONTROL_PLANE_URL names the mesh. The first run enrolls with the file
+// AGENTMESH_BOOTSTRAP_TOKEN_PATH (a token the mesh operator gave you) or
+// AGENTMESH_JWT_PATH (a workload identity token your platform issues, such as a
+// Kubernetes projected service account token), and keeps the identity and
+// credential in AGENTMESH_STATE_DIR; later runs resume from there, as the same
+// peer, without it.
+import { homedir } from "node:os";
+import { AgentMesh } from "@agentmesh-p2p/sdk";
+
+const [backendURL] = process.argv.slice(2);
+
+const mesh = await AgentMesh.enroll({
+  controlPlaneUrl: process.env.AGENTMESH_CONTROL_PLANE_URL ?? "https://mesh.example.com",
+  bootstrapTokenPath: process.env.AGENTMESH_BOOTSTRAP_TOKEN_PATH,
+  jwtPath: process.env.AGENTMESH_JWT_PATH,
+  stateDir: process.env.AGENTMESH_STATE_DIR ?? `${homedir()}/.config/agentmesh/agent`,
+  // A plaintext http:// control plane is otherwise accepted only on loopback.
+  allowInsecure: process.env.AGENTMESH_INSECURE_CONTROL_PLANE === "true",
+});
+const session = await mesh.join();
+
+// Answers every path with who was asked and who asked; a real agent runs an
+// A2A server here, or beside this process at backendURL.
+const target = await session.acceptA2A(
+  backendURL !== undefined
+    ? { url: backendURL }
+    : { handler: (request, caller) => Response.json({ name: "agent", path: new URL(request.url).pathname, caller: caller.peerId }) },
+);
+console.log(`accepting ${target} as ${session.peerId}`);
+
+const stop = () => void session.close().then(() => process.exit(0));
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+```
+<!-- /embed -->
+
+`enroll` reuses the identity and credential saved in `stateDir` when they
+are still valid for that control plane, and needs exactly one of
+`bootstrapTokenPath`, `bootstrapToken`, `jwtPath` or `jwt` (a token string or
+a `() => string | Promise<string>` callback invoked at enrollment and on every
+refresh) otherwise. Read tokens from a file, a callback or the environment; do
+not put them on a command line. `labels` are attested at enrollment;
+`join({ egressRequireLabels })` is the floor every peer the session calls must
+attest, all of it, held for the session.
+
+A plaintext `http://` control plane is accepted only on loopback. Pass
+`allowInsecure: true` for a network you trust.
+
+## License
+
+Apache-2.0. Issues and contributions at
+[github.com/google/agentmesh](https://github.com/google/agentmesh).

package/dist/auth.d.ts

@@ -0,0 +1,66 @@
+import type { Connection, StreamHandler } from "@libp2p/interface";
+import { type VerifiedBiscuit } from "./biscuit.ts";
+import { RouterGoAway_Reason, type RouterGoAway } from "./gen/agentmesh_pb.ts";
+export declare const AUTH_PROTOCOL = "/mesh/auth/1.0.0";
+export declare const MCP_PROTOCOL = "/mesh/mcp/1.0.0";
+export declare const GOAWAY_PROTOCOL = "/mesh/goaway/1.0.0";
+/** The first frame on a stream is capped, as msgio.NewVarintReaderSize(s, 64 KiB). */
+export declare const MAX_AUTH_FRAME_BYTES: number;
+/** How long either side waits for the other's frame. */
+export declare const AUTH_HANDSHAKE_TIMEOUT_MS = 10000;
+/** The go-away message on /mesh/goaway/1.0.0 is capped at 1 KiB, with a 5s read timeout. */
+export declare const MAX_GOAWAY_MESSAGE_BYTES = 1024;
+export declare const GOAWAY_STREAM_TIMEOUT_MS = 5000;
+/** Default duration a router is shunned when retry_after is unset or non-positive (5 minutes). */
+export declare const ROUTER_SHUN_DURATION_MS: number;
+/** Maximum duration a router go-away retry_after can shun a router (1 hour). */
+export declare const GOAWAY_MAX_RETRY_AFTER_MS: number;
+export declare class AuthRejectedError extends Error {
+    constructor(peerId: string, reason: string);
+}
+/**
+ * Client side: presents frame on a new /mesh/auth/1.0.0 stream and returns
+ * the peer's verified credential. trustedKeys are the control plane keys.
+ */
+export declare function authenticateWithPeer(conn: Connection, frame: Uint8Array, trustedKeys: Uint8Array[]): Promise<VerifiedBiscuit>;
+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;
+}
+/** Options for libp2p.handle() so the handshake also runs over relayed connections. */
+export declare const AUTH_HANDLER_OPTIONS: {
+    runOnLimitedConnection: boolean;
+};
+/**
+ * Server side of /mesh/auth/1.0.0, mirroring agentmesh-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.
+ */
+export declare function authStreamHandler(options: AuthServerOptions): StreamHandler;
+/** Returns the canonical proto enum name for a RouterGoAway_Reason value. */
+export declare function goAwayReasonName(reason: RouterGoAway_Reason): string;
+/**
+ * Computes the shun duration in milliseconds from a RouterGoAway message:
+ * defaults to ROUTER_SHUN_DURATION_MS (5m) when retry_after <= 0, capped at
+ * GOAWAY_MAX_RETRY_AFTER_MS (1h).
+ */
+export declare function clampGoAwayRetryAfterMs(msg: RouterGoAway): number;
+export interface GoAwayServerOptions {
+    /** Whether peerId is currently a router this member holds. */
+    isHeldRouter(peerId: string): boolean;
+    /** Called once a held router's RouterGoAway message has been read and the stream closed. */
+    onGoAway(peerId: string, msg: RouterGoAway, retryAfterMs: number): void | Promise<void>;
+}
+/**
+ * Server side of /mesh/goaway/1.0.0, mirroring agentmesh-node's HandleGoAway:
+ * reads one varint-prefixed RouterGoAway message (1024 B cap, 5s timeout) only
+ * from a router the member currently holds, closes the stream, and notifies
+ * the session to shun the router and top up from the catalog.
+ */
+export declare function goAwayStreamHandler(options: GoAwayServerOptions): StreamHandler;

package/dist/auth.js

@@ -0,0 +1,164 @@
+// 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.
+// The /mesh/auth/1.0.0 handshake, both sides. One varint-length-prefixed
+// AuthFrame, one AuthResponse back; go-msgio framing on the Go side is
+// the same unsigned varint prefix lpStream uses.
+import { create, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { lpStream } from "@libp2p/utils";
+import { BiscuitVerificationError, verifyPeerBiscuit } from "./biscuit.js";
+import { decodeAuthResponse } from "./credential.js";
+import { AuthFrameSchema, AuthResponseSchema, RouterGoAwaySchema, RouterGoAway_Reason, } from "./gen/agentmesh_pb.js";
+export const AUTH_PROTOCOL = "/mesh/auth/1.0.0";
+export const MCP_PROTOCOL = "/mesh/mcp/1.0.0";
+export const GOAWAY_PROTOCOL = "/mesh/goaway/1.0.0";
+/** The first frame on a stream is capped, as msgio.NewVarintReaderSize(s, 64 KiB). */
+export const MAX_AUTH_FRAME_BYTES = 64 * 1024;
+/** How long either side waits for the other's frame. */
+export const AUTH_HANDSHAKE_TIMEOUT_MS = 10_000;
+/** The go-away message on /mesh/goaway/1.0.0 is capped at 1 KiB, with a 5s read timeout. */
+export const MAX_GOAWAY_MESSAGE_BYTES = 1024;
+export const GOAWAY_STREAM_TIMEOUT_MS = 5_000;
+/** Default duration a router is shunned when retry_after is unset or non-positive (5 minutes). */
+export const ROUTER_SHUN_DURATION_MS = 5 * 60_000;
+/** Maximum duration a router go-away retry_after can shun a router (1 hour). */
+export const GOAWAY_MAX_RETRY_AFTER_MS = 60 * 60_000;
+export class AuthRejectedError extends Error {
+    constructor(peerId, reason) {
+        super(`peer ${peerId} rejected the auth handshake: ${reason}`);
+        this.name = "AuthRejectedError";
+    }
+}
+function framed(stream) {
+    return lpStream(stream, { maxDataLength: MAX_AUTH_FRAME_BYTES });
+}
+/**
+ * Client side: presents frame on a new /mesh/auth/1.0.0 stream and returns
+ * the peer's verified credential. trustedKeys are the control plane keys.
+ */
+export async function authenticateWithPeer(conn, frame, trustedKeys) {
+    const signal = AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS);
+    // A peer behind a router is reached over a relayed, limited connection.
+    const stream = await conn.newStream(AUTH_PROTOCOL, { signal, runOnLimitedConnection: true });
+    try {
+        const lp = framed(stream);
+        await lp.write(frame, { signal });
+        const resp = decodeAuthResponse((await lp.read({ signal })).subarray());
+        if (!resp.success) {
+            throw new AuthRejectedError(conn.remotePeer.toString(), resp.error || "no reason given");
+        }
+        if (resp.biscuit.length === 0) {
+            throw new AuthRejectedError(conn.remotePeer.toString(), "empty credential in the mutual response");
+        }
+        // Discovery names whoever answered; only this says the peer is enrolled.
+        return await verifyPeerBiscuit(resp.biscuit, conn.remotePeer.toString(), trustedKeys);
+    }
+    finally {
+        await stream.close().catch(() => stream.abort(new Error("auth stream close failed")));
+    }
+}
+/** Options for libp2p.handle() so the handshake also runs over relayed connections. */
+export const AUTH_HANDLER_OPTIONS = { runOnLimitedConnection: true };
+/**
+ * Server side of /mesh/auth/1.0.0, mirroring agentmesh-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.
+ */
+export function authStreamHandler(options) {
+    return async (stream, connection) => {
+        const peerId = connection.remotePeer.toString();
+        const signal = AbortSignal.timeout(AUTH_HANDSHAKE_TIMEOUT_MS);
+        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;
+            try {
+                verified = await verifyPeerBiscuit(frame.biscuit, peerId, options.trustedKeys());
+            }
+            catch (err) {
+                if (err instanceof BiscuitVerificationError) {
+                    stream.log?.("auth handshake from %s refused: %s", peerId, err.message);
+                    return;
+                }
+                throw err;
+            }
+            options.onAuthenticated?.(peerId, verified);
+            await lp.write(toBinary(AuthResponseSchema, create(AuthResponseSchema, { success: true, biscuit: options.ownBiscuit() })), { signal });
+        }
+        finally {
+            await stream.close().catch(() => stream.abort(new Error("auth stream close failed")));
+        }
+    };
+}
+/** Returns the canonical proto enum name for a RouterGoAway_Reason value. */
+export function goAwayReasonName(reason) {
+    switch (reason) {
+        case RouterGoAway_Reason.DRAINING:
+            return "DRAINING";
+        case RouterGoAway_Reason.OVERLOADED:
+            return "OVERLOADED";
+        default:
+            return "REASON_UNSPECIFIED";
+    }
+}
+/**
+ * Computes the shun duration in milliseconds from a RouterGoAway message:
+ * defaults to ROUTER_SHUN_DURATION_MS (5m) when retry_after <= 0, capped at
+ * GOAWAY_MAX_RETRY_AFTER_MS (1h).
+ */
+export function clampGoAwayRetryAfterMs(msg) {
+    let ms = 0;
+    if (msg.retryAfter !== undefined) {
+        ms = Number(msg.retryAfter.seconds) * 1000 + Math.floor(msg.retryAfter.nanos / 1_000_000);
+    }
+    if (ms <= 0) {
+        return ROUTER_SHUN_DURATION_MS;
+    }
+    if (ms > GOAWAY_MAX_RETRY_AFTER_MS) {
+        return GOAWAY_MAX_RETRY_AFTER_MS;
+    }
+    return ms;
+}
+/**
+ * Server side of /mesh/goaway/1.0.0, mirroring agentmesh-node's HandleGoAway:
+ * reads one varint-prefixed RouterGoAway message (1024 B cap, 5s timeout) only
+ * from a router the member currently holds, closes the stream, and notifies
+ * the session to shun the router and top up from the catalog.
+ */
+export function goAwayStreamHandler(options) {
+    return async (stream, connection) => {
+        const peerId = connection.remotePeer.toString();
+        if (!options.isHeldRouter(peerId)) {
+            stream.abort(new Error(`ignoring go-away from unattached peer ${peerId}`));
+            return;
+        }
+        const signal = AbortSignal.timeout(GOAWAY_STREAM_TIMEOUT_MS);
+        let msg;
+        try {
+            const lp = lpStream(stream, { maxDataLength: MAX_GOAWAY_MESSAGE_BYTES });
+            msg = fromBinary(RouterGoAwaySchema, (await lp.read({ signal })).subarray());
+        }
+        catch (err) {
+            stream.abort(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        await stream.close().catch(() => stream.abort(new Error("goaway stream close failed")));
+        const retryAfterMs = clampGoAwayRetryAfterMs(msg);
+        await options.onGoAway(peerId, msg, retryAfterMs);
+    };
+}

package/dist/authorizer.d.ts

@@ -0,0 +1,41 @@
+import { type VerifiedBiscuit } from "./biscuit.ts";
+/** What a caller asks for, as agentmesh-node's RequestContext. */
+export interface AuthorizeRequest {
+    /** The caller's biscuit, as it arrived in the AuthFrame or X-Mesh-Biscuit. */
+    biscuit: Uint8Array;
+    /** The peer at the other end of the authenticated connection. */
+    peerId: string;
+    /** "mcp://<name>", or "" for the protocol itself (the provider's own catalog). */
+    targetService: string;
+    /** The stream protocol; names the service when targetService is "". */
+    protocol: string;
+    /**
+     * The HTTP method and the path as the backend sees it, when the request is
+     * HTTP. Both are injected together; a request without them (a stream that
+     * carries no HTTP request) does not match a grant narrowed by
+     * PolicyRole.http.
+     */
+    method?: string;
+    path?: string;
+    /** The MCP tool name when evaluating a specific MCP tools/call invocation. */
+    mcpTool?: string;
+}
+export interface ProviderAuthorizerOptions {
+    /** Control plane keys, read per request so a rotation takes effect. */
+    trustedKeys(): Uint8Array[];
+    /** This provider's own biscuit; its identity facts are what target grants match. */
+    ownBiscuit(): Uint8Array;
+    /** The mesh policy as PolicyConfigGetResponse.datalog_rules. */
+    policyRules(): string[];
+    now?(): Date;
+}
+export declare class AuthorizationError extends Error {
+    constructor(peerId: string, reason: string);
+}
+/**
+ * Authorizes one request from a caller. Returns the caller's verified
+ * credential when every check holds and a policy allows; throws
+ * AuthorizationError otherwise. Every trusted key is tried, as
+ * VerifyBiscuitToken does.
+ */
+export declare function authorizeCaller(req: AuthorizeRequest, options: ProviderAuthorizerOptions): Promise<VerifiedBiscuit>;

package/dist/authorizer.js

@@ -0,0 +1,201 @@
+// 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.
+// The provider-side authorizer, mirroring internal/node.(*AgentMeshNode).Authorize.
+// Every piece of Datalog it evaluates is text: the baseline generated from
+// api/datalog.go (gen/datalog.ts) and the mesh policy rules the control
+// plane renders (GET /policies). Nothing here derives rules from roles.
+import { AUTHORIZER_LIMITS, BiscuitVerificationError, loadBiscuit, verifyPeerBiscuit, withinLimits } from "./biscuit.js";
+import { parseServiceTarget } from "./discovery.js";
+import { BASELINE_DATALOG } from "./gen/datalog.js";
+import { evaluateTaskRules, isSafeRequestHTTPPath } from "./tar.js";
+export class AuthorizationError extends Error {
+    constructor(peerId, reason) {
+        super(`caller ${peerId} is not authorized: ${reason}`);
+        this.name = "AuthorizationError";
+    }
+}
+// biscuit-wasm throws plain objects ({ FailedLogic: ... }, { RunLimit: ... }).
+function describe(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+function timeFact(now) {
+    return `${BASELINE_DATALOG.fact_time}(${now.toISOString().replace(/\.\d{3}Z$/, "Z")})`;
+}
+/**
+ * Authorizes one request from a caller. Returns the caller's verified
+ * credential when every check holds and a policy allows; throws
+ * AuthorizationError otherwise. Every trusted key is tried, as
+ * VerifyBiscuitToken does.
+ */
+export async function authorizeCaller(req, options) {
+    const wasm = await loadBiscuit();
+    const now = options.now?.() ?? new Date();
+    const keys = options.trustedKeys();
+    if (keys.length === 0) {
+        throw new AuthorizationError(req.peerId, "no trusted control plane key");
+    }
+    // Signature under a trusted key, authority block + tar_block chain, expiry and binding
+    // to the connection peer: RequireAuthorityRequestBinding and EnforceExpiration.
+    let caller;
+    try {
+        caller = await verifyPeerBiscuit(req.biscuit, req.peerId, keys, now, { allowDelegated: true });
+    }
+    catch (err) {
+        throw new AuthorizationError(req.peerId, describe(err));
+    }
+    const token = wasm.Biscuit.fromBytes(req.biscuit, wasm.PublicKey.fromBytes(caller.verifyingKey, wasm.SignatureAlgorithm.Ed25519));
+    const b = new wasm.AuthorizerBuilder();
+    const fact = (source, params = {}) => {
+        const f = wasm.Fact.fromString(source);
+        for (const [k, v] of Object.entries(params)) {
+            f.set(k, v);
+        }
+        b.addFact(f);
+    };
+    // The action: service(type, name). An empty target is the protocol itself
+    // in the system namespace, as agentmesh-node scopes its own catalog.
+    let svcType;
+    let svcName;
+    if (req.targetService === "") {
+        svcType = BASELINE_DATALOG.system_namespace;
+        svcName = req.protocol;
+    }
+    else {
+        let parsed;
+        try {
+            parsed = parseServiceTarget(req.targetService);
+        }
+        catch (err) {
+            throw new AuthorizationError(req.peerId, describe(err));
+        }
+        svcType = parsed.type;
+        svcName = parsed.name;
+    }
+    fact(`${BASELINE_DATALOG.fact_service}({t}, {n})`, { t: svcType, n: svcName });
+    fact(`${BASELINE_DATALOG.fact_connection_peer_id}({p})`, { p: req.peerId });
+    fact(timeFact(now));
+    // The request as the wire carried it, never as the caller describes it.
+    if (req.method !== undefined) {
+        if (req.method !== "CONNECT" && req.path !== undefined && req.path !== "" && !isSafeRequestHTTPPath(req.path)) {
+            throw new AuthorizationError(req.peerId, `invalid HTTP path ${JSON.stringify(req.path)}`);
+        }
+        fact(`${BASELINE_DATALOG.fact_method}({m})`, { m: req.method });
+        fact(`${BASELINE_DATALOG.fact_path}({p})`, { p: req.path ?? "" });
+    }
+    b.addCheck(wasm.Check.fromString(BASELINE_DATALOG.replay_check));
+    b.addCheck(wasm.Check.fromString(BASELINE_DATALOG.time_check));
+    // This provider's identity as target_fact facts, so the caller's target
+    // grants have something to match (injectIdentityFacts).
+    for (const f of await identityTargetFacts(options.ownBiscuit(), keys, now)) {
+        b.addFact(f);
+    }
+    b.addCheck(wasm.Check.fromString(BASELINE_DATALOG.target_check));
+    for (const p of BASELINE_DATALOG.policies) {
+        b.addPolicy(wasm.Policy.fromString(p));
+    }
+    for (const r of BASELINE_DATALOG.rules) {
+        b.addRule(wasm.Rule.fromString(r));
+    }
+    for (const r of BASELINE_DATALOG.http_rules) {
+        b.addRule(wasm.Rule.fromString(r));
+    }
+    for (const r of options.policyRules()) {
+        b.addRule(wasm.Rule.fromString(r));
+    }
+    const authorizer = b.buildAuthenticated(token);
+    try {
+        withinLimits(() => authorizer.authorizeWithLimits(AUTHORIZER_LIMITS));
+    }
+    catch (err) {
+        throw new AuthorizationError(req.peerId, describe(err));
+    }
+    if (caller.taskRules.length > 0) {
+        const mcpTool = req.mcpTool ?? "";
+        try {
+            evaluateTaskRules(caller.taskRules, {
+                serviceType: svcType,
+                serviceName: svcName,
+                hasHttp: req.method !== undefined,
+                method: req.method ?? "",
+                path: req.path ?? "",
+                mcpTool,
+                allowMCPStreamInit: req.method === undefined && mcpTool === "" && req.protocol === "/mesh/mcp/1.0.0",
+            }, now);
+        }
+        catch (err) {
+            throw new AuthorizationError(req.peerId, describe(err));
+        }
+    }
+    return caller;
+}
+/**
+ * Evaluates this provider's own biscuit and returns its identity as
+ * target_fact facts, one per target_fact rule of the baseline.
+ */
+async function identityTargetFacts(ownBiscuit, keys, now) {
+    const wasm = await loadBiscuit();
+    if (ownBiscuit.length === 0) {
+        return [];
+    }
+    let own;
+    try {
+        own = await verifyPeerBiscuit(ownBiscuit, await boundPeer(ownBiscuit, keys), keys, now);
+    }
+    catch (err) {
+        throw new BiscuitVerificationError(`own credential does not verify: ${describe(err)}`, { cause: err });
+    }
+    const token = wasm.Biscuit.fromBytes(ownBiscuit, wasm.PublicKey.fromBytes(own.verifyingKey, wasm.SignatureAlgorithm.Ed25519));
+    const b = new wasm.AuthorizerBuilder();
+    b.addFact(wasm.Fact.fromString(timeFact(now)));
+    b.addPolicy(wasm.Policy.fromString(BASELINE_DATALOG.allow_if_true));
+    const authorizer = b.buildAuthenticated(token);
+    withinLimits(() => authorizer.authorizeWithLimits(AUTHORIZER_LIMITS));
+    const facts = [];
+    for (const r of BASELINE_DATALOG.target_fact_rules) {
+        facts.push(...withinLimits(() => authorizer.queryWithLimits(wasm.Rule.fromString(r), AUTHORIZER_LIMITS)));
+    }
+    return facts;
+}
+/** The peer a biscuit binds itself to: its node() fact. */
+async function boundPeer(biscuit, keys) {
+    const wasm = await loadBiscuit();
+    let lastErr;
+    for (const key of keys) {
+        try {
+            const token = wasm.Biscuit.fromBytes(biscuit, wasm.PublicKey.fromBytes(key, wasm.SignatureAlgorithm.Ed25519));
+            const b = new wasm.AuthorizerBuilder();
+            b.addPolicy(wasm.Policy.fromString(BASELINE_DATALOG.allow_if_true));
+            const authorizer = b.buildAuthenticated(token);
+            const bound = withinLimits(() => authorizer.queryWithLimits(wasm.Rule.fromString("p($p) <- node($p)"), AUTHORIZER_LIMITS))
+                .map((f) => f.terms()[0])
+                .find((t) => typeof t === "string");
+            if (bound === undefined) {
+                throw new Error("biscuit carries no node() fact");
+            }
+            return bound;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw new BiscuitVerificationError(`biscuit is not signed by a trusted control plane key: ${describe(lastErr)}`);
+}

package/dist/base58.d.ts

@@ -0,0 +1,2 @@
+export declare function encodeBase58(bytes: Uint8Array): string;
+export declare function decodeBase58(text: string): Uint8Array;