@agentmesh-p2p/sdk 0.0.0-stage → 0.1.0

package/dist/libp2p-http.js

@@ -0,0 +1,581 @@
+// 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.
+import { AUTH_HANDSHAKE_TIMEOUT_MS } from "./auth.js";
+import { AuthorizationError, authorizeCaller } from "./authorizer.js";
+import { fromBase64, toBase64 } from "./bytes.js";
+import { ByteReader, HTTPParseError, LAST_CHUNK, bodyStream, encodeChunk, encodeRequestHead, encodeResponseHead, readBody, readRequestHead, readResponseHead, requestBodyFraming, responseBodyFraming, sendAll, streamSource, } from "./http1.js";
+import { canonicalPeerId } from "./identity.js";
+/** go-libp2p-http's protocol: plain HTTP/1.1 on a stream, one request per stream. */
+export const HTTP_PROTOCOL = "/libp2p-http";
+/** Headers of the mesh HTTP datapath (api/network.go). */
+export const HEADER_MESH_BISCUIT = "x-mesh-biscuit";
+export const HEADER_PEER_ID = "x-peer-id";
+export const HEADER_MESH_NO_TRAILING_SLASH = "x-mesh-no-trailing-slash";
+/** Options for libp2p.handle() so the agent is reachable over relayed connections. */
+export const HTTP_HANDLER_OPTIONS = { runOnLimitedConnection: true };
+/** The service name an agent answers under unless it picks another. */
+export const DEFAULT_A2A_NAME = "agent";
+/**
+ * The path prefix of a mesh URL, http://mesh/mesh/<peer-id>/<type>/<name>/<path>:
+ * the shape of agentmesh-node's egress proxy and of an agent card rewritten for the
+ * mesh, by agentmesh-node or by this SDK. The host is ignored; the peer ID is in the
+ * path because URL parsers lowercase the host and a peer ID is case-sensitive.
+ */
+export const MESH_PATH_PREFIX = "/mesh/";
+/** The well-known agent card location (A2A spec / RFC 8615). */
+export const AGENT_CARD_PATH = ".well-known/agent-card.json";
+const MAX_AGENT_CARD_BYTES = 1 << 20;
+/** Largest request body the ingress reads whole for a handler or url target. */
+export const MAX_INGRESS_BODY_BYTES = 8 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 60_000;
+export function a2aEndpoint(spec) {
+    const name = spec.name ?? DEFAULT_A2A_NAME;
+    const given = [spec.url, spec.handler, spec.listener].filter((t) => t !== undefined).length;
+    if (given !== 1) {
+        throw new Error("an A2A endpoint is exactly one of url, handler or listener");
+    }
+    const target = spec.url !== undefined ? { url: spec.url } : spec.handler !== undefined ? { handler: spec.handler } : { listener: spec.listener };
+    return { name, service: `a2a://${name}`, target };
+}
+// A URL parser reads %2e as a dot too (WHATWG URL, path state), and %2f/%5c/\
+// as path separators on some backends, so the check rejects those and dot segments.
+function hasDotSegment(path) {
+    if (!path.startsWith("/") || path.includes("#")) {
+        return true;
+    }
+    for (let i = 0; i < path.length; i++) {
+        const code = path.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f || path[i] === "\\" || path[i] === '"') {
+            return true;
+        }
+        if (path[i] === "%" && i + 2 < path.length) {
+            const hex = path.slice(i + 1, i + 3).toLowerCase();
+            if (hex === "2f" || hex === "5c" || hex === "00") {
+                return true;
+            }
+        }
+    }
+    return path.split("/").some((seg) => {
+        const s = seg.replace(/%2e/gi, ".");
+        return s === "." || s === "..";
+    });
+}
+/**
+ * Server-side admission of /libp2p-http, as agentmesh-node's StartIngressServer:
+ * the path is /<type>/<name>[/<upstream>], the caller's biscuit is
+ * X-Mesh-Biscuit, and the request is authorized for <type>://<name> before
+ * anything is forwarded. Only the agent's own endpoint is answered; anything
+ * else is 404 after authorization, so an unauthorized caller learns nothing
+ * about it.
+ */
+export async function admitIngress(req, endpoint, options) {
+    // Policy is decided on the /<type>/<name> prefix; a dot segment in what
+    // follows could resolve to a sibling path on the backend. Checked on the
+    // raw path, before URL parsing normalizes it away.
+    if (hasDotSegment(req.target.split("?")[0])) {
+        return { status: 400, text: "Invalid path" };
+    }
+    const url = new URL(req.target, "http://mesh.invalid");
+    const parts = url.pathname.replace(/^\//, "").split("/");
+    if (parts.length < 2 || parts[0] === "" || parts[1] === "") {
+        return { status: 400, text: "Invalid path" };
+    }
+    const [serviceType, serviceName, ...rest] = parts;
+    if (serviceType !== "inference" && serviceType !== "a2a" && serviceType !== "mcp" && serviceType !== "egress") {
+        return { status: 400, text: "Invalid service type" };
+    }
+    const upstreamPath = rest.join("/");
+    const biscuitB64 = req.headers.get(HEADER_MESH_BISCUIT);
+    if (biscuitB64 === null || biscuitB64 === "") {
+        return { status: 401, text: "Missing X-Mesh-Biscuit header" };
+    }
+    let biscuit;
+    try {
+        biscuit = fromBase64(biscuitB64);
+        if (biscuit.length === 0) {
+            throw new Error("empty");
+        }
+    }
+    catch {
+        return { status: 400, text: "Invalid X-Mesh-Biscuit encoding" };
+    }
+    const targetService = `${serviceType}://${serviceName}`;
+    if (options.isBanned?.(req.remotePeer) === true) {
+        return { status: 403, text: "Authorization failed" };
+    }
+    let verified;
+    try {
+        verified = await authorizeCaller({
+            biscuit,
+            peerId: req.remotePeer,
+            targetService,
+            protocol: HTTP_PROTOCOL,
+            // The path as the backend sees it, decided before authorization so
+            // path() is what policy meant, never the routing prefix.
+            method: req.method,
+            path: "/" + upstreamPath,
+        }, options);
+    }
+    catch (err) {
+        if (err instanceof AuthorizationError) {
+            return { status: 403, text: "Authorization failed" };
+        }
+        throw err;
+    }
+    options.onAuthorized?.(req.remotePeer, verified, targetService);
+    // Under the type the policy was evaluated on.
+    if (targetService !== endpoint.service) {
+        return { status: 404, text: "Service not found" };
+    }
+    return { verified, path: "/" + upstreamPath + url.search, noTrailingSlash: upstreamPath === "" && rest.length === 0 };
+}
+/** Headers of the mesh datapath and of the hop itself, not passed on to the agent. */
+const HOP_HEADERS = new Set([HEADER_MESH_BISCUIT, HEADER_MESH_NO_TRAILING_SLASH, HEADER_PEER_ID, "host", "connection", "transfer-encoding", "content-length", "keep-alive"]);
+/**
+ * The headers the agent sees: the request's own, less the datapath's, with
+ * X-Peer-Id set (not added) to the verified caller so an inbound value
+ * cannot pose as the peer.
+ */
+export function agentHeaders(inbound, remotePeer, noTrailingSlash) {
+    const headers = new Headers();
+    inbound.forEach((value, name) => {
+        if (!HOP_HEADERS.has(name)) {
+            headers.append(name, value);
+        }
+    });
+    headers.set(HEADER_PEER_ID, remotePeer);
+    if (noTrailingSlash) {
+        headers.set(HEADER_MESH_NO_TRAILING_SLASH, "true");
+    }
+    return headers;
+}
+/** A plain-text refusal, as agentmesh-node's ingress writes one. */
+export function refusalResponse(refusal) {
+    return new Response(refusal.text + "\n", { status: refusal.status, headers: { "content-type": "text/plain; charset=utf-8" } });
+}
+async function writeResponse(stream, response, headOnly) {
+    const headers = new Headers();
+    response.headers.forEach((value, name) => {
+        if (name !== "content-length" && name !== "transfer-encoding" && name !== "connection") {
+            headers.set(name, value);
+        }
+    });
+    headers.set("connection", "close");
+    if (headOnly) {
+        // The same head a GET would get (RFC 9110 section 9.3.2): the length the
+        // agent declared, if any; the body it may have built is not sent.
+        const declared = response.headers.get("content-length");
+        if (declared !== null) {
+            headers.set("content-length", declared);
+        }
+        void response.body?.cancel().catch(() => { });
+        await sendAll(stream, encodeResponseHead(response.status, response.statusText, headers));
+        return;
+    }
+    const body = response.body;
+    if (body === null) {
+        headers.set("content-length", "0");
+        await sendAll(stream, encodeResponseHead(response.status, response.statusText, headers));
+        return;
+    }
+    // The length is not known up front, so each piece goes as a chunk as soon
+    // as the agent writes it; an SSE event reaches the caller before the next.
+    headers.set("transfer-encoding", "chunked");
+    await sendAll(stream, encodeResponseHead(response.status, response.statusText, headers));
+    const reader = body.getReader();
+    try {
+        for (let next = await reader.read(); !next.done; next = await reader.read()) {
+            if (next.value.length > 0) {
+                await sendAll(stream, encodeChunk(next.value));
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    await sendAll(stream, LAST_CHUNK);
+}
+async function serveIngress(stream, remotePeer, endpoint, options) {
+    const reader = new ByteReader(streamSource(stream));
+    const headTimer = setTimeout(() => stream.abort(new Error(`no request head from ${remotePeer} within ${AUTH_HANDSHAKE_TIMEOUT_MS}ms`)), AUTH_HANDSHAKE_TIMEOUT_MS);
+    let response;
+    let headOnly = false;
+    try {
+        let head;
+        try {
+            head = await readRequestHead(reader);
+        }
+        finally {
+            clearTimeout(headTimer);
+        }
+        if (head === null) {
+            return;
+        }
+        headOnly = head.method === "HEAD";
+        const admission = await admitIngress({ method: head.method, target: head.target, headers: head.headers, remotePeer }, endpoint, options);
+        if ("status" in admission) {
+            response = refusalResponse(admission);
+        }
+        else if ("listener" in endpoint.target) {
+            response = refusalResponse({ status: 501, text: "A request listener is not served in this runtime" });
+        }
+        else {
+            const headers = agentHeaders(head.headers, remotePeer, admission.noTrailingSlash);
+            const init = { method: head.method, headers };
+            if (head.method !== "GET" && head.method !== "HEAD") {
+                init.body = await readBody(reader, requestBodyFraming(head), MAX_INGRESS_BODY_BYTES);
+            }
+            if ("url" in endpoint.target) {
+                const base = endpoint.target.url.replace(/\/$/, "");
+                response = await fetch(base + admission.path, { ...init, redirect: "manual" });
+            }
+            else {
+                response = await endpoint.target.handler(new Request("http://" + endpoint.name + admission.path, init), admission.verified);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof HTTPParseError) {
+            response = refusalResponse({ status: 400, text: `Bad request: ${err.message}` });
+        }
+        else {
+            response = refusalResponse({ status: 500, text: `ingress error: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    await writeResponse(stream, response, headOnly);
+}
+/**
+ * Server side of /libp2p-http for an endpoint answered by a handler in this
+ * process or an A2A server at a URL. One request per stream; the stream is
+ * closed once the response has been written.
+ */
+export function httpIngressHandler(endpoint, options) {
+    return (stream, connection) => {
+        void serveIngress(stream, connection.remotePeer.toString(), endpoint, options)
+            .then(() => stream.close())
+            .catch((err) => stream.abort(err instanceof Error ? err : new Error(String(err))));
+    };
+}
+/** The request target for a service on a peer: /<type>/<name>/<path>. */
+export function meshHTTPTarget(targetService, path = "") {
+    const m = /^(inference|a2a|mcp|egress):\/\/(.+)$/.exec(targetService);
+    if (m === null) {
+        throw new Error(`service target must look like inference://<name>, got ${JSON.stringify(targetService)}`);
+    }
+    if (path === "") {
+        return `/${m[1]}/${m[2]}`;
+    }
+    return `/${m[1]}/${m[2]}${path.startsWith("/") ? path : "/" + path}`;
+}
+/**
+ * The URL a fetch bound to a session (session.fetch()) takes for a service
+ * on a peer: http://mesh/mesh/<peer-id>/<type>/<name>/<path>.
+ */
+export function meshURL(peerId, targetService, path = "") {
+    return "http://mesh" + MESH_PATH_PREFIX + canonicalPeerId(peerId) + meshHTTPTarget(targetService, path);
+}
+/** (peer ID, request target) of a mesh URL; the target is what the peer's ingress takes. */
+export function splitMeshURL(url) {
+    if (!url.pathname.startsWith(MESH_PATH_PREFIX)) {
+        throw new TypeError(`a mesh URL looks like http://mesh${MESH_PATH_PREFIX}<peer-id>/<type>/<name>/..., got ${url.toString()}`);
+    }
+    const [peerId = "", ...rest] = url.pathname.slice(MESH_PATH_PREFIX.length).split("/");
+    if (peerId === "" || rest.length < 2 || rest[0] === "" || rest[1] === "") {
+        throw new TypeError(`a mesh URL names a peer, a service type and a name, got ${url.toString()}`);
+    }
+    return { peerId, target: "/" + rest.join("/") + url.search };
+}
+/** The bare service root counts too: a2a-go treats a pathful base URL as the card location. */
+function agentCardService(method, target) {
+    const m = /^\/a2a\/([^/?]+)(?:\/(?:\.well-known\/agent-card\.json)?)?(?:\?.*)?$/.exec(target);
+    return method === "GET" && m !== null ? `a2a://${m[1]}` : undefined;
+}
+/**
+ * An agent card rebuilt for the mesh, as agentmesh-node's egress proxy serves it:
+ * HTTP interfaces resolve under base (meshInterfaceURL), gRPC ones go, signatures no longer match.
+ * Streaming stays as declared, this transport streams. Throws when no interface remains.
+ */
+export function rewriteAgentCard(card, base) {
+    if (typeof card !== "object" || card === null || Array.isArray(card)) {
+        throw new Error("agent card is not a JSON object");
+    }
+    const out = { ...card };
+    delete out.signatures;
+    const interfaces = Array.isArray(out.supportedInterfaces) ? out.supportedInterfaces : [];
+    const kept = interfaces.filter(carriedOverHTTP).map((iface) => {
+        const url = iface.url;
+        return { ...iface, url: meshInterfaceURL(base, typeof url === "string" ? url : "") };
+    });
+    if (kept.length === 0) {
+        throw new Error("agent card advertises no supported interface the mesh can carry (JSONRPC or HTTP+JSON); is the agent serving a pre-1.0 A2A card?");
+    }
+    return { ...out, supportedInterfaces: kept };
+}
+/**
+ * The mesh URL of one agent interface, as agentmesh-node resolves it. The
+ * provider's node names an interface it can reach by a reference relative to
+ * the service root ("invoke", "a2a/rest", "" for the root), which resolves
+ * under base; anything else maps to base itself. A reference that could leave
+ * the service (a dot segment, a rooted path, a scheme or a host) also maps to
+ * base: a provider must not be able to point the caller at another path on
+ * this node. Mirrors Go's url.Parse and URL.EscapedPath for the parts it reads.
+ */
+export function meshInterfaceURL(base, raw) {
+    const hash = raw.indexOf("#");
+    const beforeFragment = hash < 0 ? raw : raw.slice(0, hash);
+    if (hash >= 0 && percentDecode(utf8.encode(raw.slice(hash + 1))) === undefined) {
+        return base;
+    }
+    if (/[\x00-\x1f\x7f]/.test(beforeFragment)) {
+        return base;
+    }
+    const query = beforeFragment.indexOf("?");
+    let rawPath = query < 0 ? beforeFragment : beforeFragment.slice(0, query);
+    const rawQuery = query < 0 ? "" : beforeFragment.slice(query + 1);
+    // A scheme, or for Go a parse error: a colon in the first segment.
+    if (rawPath.split("/", 1)[0].includes(":")) {
+        return base;
+    }
+    // "//" alone is an empty authority and an empty path; any other authority
+    // names a host, a user or a rooted path.
+    if (rawPath === "//") {
+        rawPath = "";
+    }
+    const encoded = utf8.encode(rawPath);
+    const decoded = percentDecode(encoded);
+    if (decoded === undefined) {
+        return base;
+    }
+    const path = latin1(decoded);
+    if (path.startsWith("/") || path.split("/").some((seg) => seg === "." || seg === "..")) {
+        return base;
+    }
+    let out = base;
+    if (path !== "") {
+        out += "/" + escapedPath(rawPath, encoded, decoded);
+    }
+    if (rawQuery !== "") {
+        out += "?" + rawQuery;
+    }
+    return out;
+}
+const utf8 = new TextEncoder();
+// Bytes Go's url package leaves alone in a path (shouldEscape(c, encodePath) is false).
+const PATH_SAFE = new Set(Array.from("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~$&+,/:;=@", (c) => c.charCodeAt(0)));
+// Bytes Go's validEncoded also accepts in an already escaped path.
+const PATH_SUB_DELIMS = new Set(Array.from("!'()*[]%", (c) => c.charCodeAt(0)));
+function hexValue(c) {
+    if (c >= 0x30 && c <= 0x39)
+        return c - 0x30;
+    if (c >= 0x41 && c <= 0x46)
+        return c - 0x37;
+    if (c >= 0x61 && c <= 0x66)
+        return c - 0x57;
+    return -1;
+}
+/** Percent-decodes bytes, or undefined when a "%" is not followed by two hex digits. */
+function percentDecode(bytes) {
+    const out = [];
+    for (let i = 0; i < bytes.length; i++) {
+        if (bytes[i] !== 0x25) {
+            out.push(bytes[i]);
+            continue;
+        }
+        const hi = hexValue(bytes[i + 1] ?? -1);
+        const lo = hexValue(bytes[i + 2] ?? -1);
+        if (hi < 0 || lo < 0) {
+            return undefined;
+        }
+        out.push((hi << 4) | lo);
+        i += 2;
+    }
+    return Uint8Array.from(out);
+}
+/** Go's URL.EscapedPath: the path as written when that is a valid escaping of it, else the default escaping. */
+function escapedPath(rawPath, encoded, decoded) {
+    const escaped = percentEncodePath(decoded);
+    if (escaped !== rawPath && encoded.every((c) => PATH_SAFE.has(c) || PATH_SUB_DELIMS.has(c))) {
+        return rawPath;
+    }
+    return latin1(decoded) === "*" ? "*" : escaped;
+}
+function percentEncodePath(bytes) {
+    let out = "";
+    for (const c of bytes) {
+        out += PATH_SAFE.has(c) ? String.fromCharCode(c) : "%" + c.toString(16).toUpperCase().padStart(2, "0");
+    }
+    return out;
+}
+/** One char per byte, so that segment checks see the decoded bytes as Go does. */
+function latin1(bytes) {
+    return Array.from(bytes, (c) => String.fromCharCode(c)).join("");
+}
+/** Whether an interface's binding can traverse the mesh; gRPC needs its own connection. */
+function carriedOverHTTP(iface) {
+    const binding = typeof iface === "object" && iface !== null ? iface.protocolBinding : undefined;
+    return typeof binding === "string" && ["JSONRPC", "HTTP+JSON"].includes(binding.toUpperCase());
+}
+/**
+ * Impersonates the agent's card endpoint as agentmesh-node's egress proxy does: holds
+ * the client's request, fetches the card itself with identity encoding, and
+ * answers with it regenerated; the agent's own non-200 is relayed as it is.
+ */
+async function serveAgentCard(conn, biscuit, request, options, service) {
+    const base = meshURL(conn.remotePeer.toString(), service);
+    const headers = new Headers(request.headers);
+    headers.delete("accept-encoding");
+    let response;
+    try {
+        response = await sendOverStream(conn, biscuit, new Request(`${base}/${AGENT_CARD_PATH}`, { headers, signal: request.signal }), options);
+    }
+    catch (err) {
+        return badGateway(`agent card fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (response.status !== 200) {
+        return response;
+    }
+    let card;
+    try {
+        card = JSON.parse(new TextDecoder().decode(await readLimited(response.body, MAX_AGENT_CARD_BYTES)));
+    }
+    catch {
+        return badGateway("agent card is not valid JSON");
+    }
+    try {
+        return new Response(JSON.stringify(rewriteAgentCard(card, base)), { status: 200, headers: { "content-type": "application/json" } });
+    }
+    catch (err) {
+        return badGateway(err instanceof Error ? err.message : String(err));
+    }
+}
+function badGateway(reason) {
+    return new Response(`Bad Gateway: ${reason}`, { status: 502, headers: { "content-type": "text/plain" } });
+}
+/** The first limit bytes of a body, the rest dropped, as io.LimitReader bounds the node. */
+async function readLimited(body, limit) {
+    const chunks = [];
+    let n = 0;
+    if (body !== null) {
+        const reader = body.getReader();
+        for (let next = await reader.read(); !next.done && n < limit; next = await reader.read()) {
+            const chunk = next.value.subarray(0, limit - n);
+            chunks.push(chunk);
+            n += chunk.length;
+        }
+        await reader.cancel();
+    }
+    const out = new Uint8Array(n);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}
+/**
+ * Client side of /libp2p-http, as go-libp2p-http's RoundTripper: one stream
+ * per request, plain HTTP/1.1 with Host set to the peer ID and the biscuit in
+ * X-Mesh-Biscuit. Resolves once the response headers are in; the body streams
+ * after, so an SSE response is consumed as the peer sends it. An agent card
+ * is served rewritten for the mesh (rewriteAgentCard), as agentmesh-node serves one.
+ */
+export async function fetchOverStream(conn, biscuit, request, options = {}) {
+    const { target } = splitMeshURL(new URL(request.url));
+    const service = agentCardService(request.method, target);
+    return service === undefined ? sendOverStream(conn, biscuit, request, options) : serveAgentCard(conn, biscuit, request, options, service);
+}
+async function sendOverStream(conn, biscuit, request, options) {
+    const { target } = splitMeshURL(new URL(request.url));
+    const peerId = conn.remotePeer.toString();
+    // One controller ends the exchange: the caller's signal at any time, the
+    // headers timeout only until the response headers are in.
+    const ctl = new AbortController();
+    let headersIn = false;
+    const forward = (s) => s?.addEventListener("abort", () => ctl.abort(s.reason), { once: true });
+    forward(options.signal);
+    forward(request.signal);
+    if (options.signal === undefined) {
+        const timer = setTimeout(() => {
+            if (!headersIn) {
+                ctl.abort(new DOMException(`no response headers from ${peerId} within ${REQUEST_TIMEOUT_MS}ms`, "TimeoutError"));
+            }
+        }, REQUEST_TIMEOUT_MS);
+        timer.unref?.();
+    }
+    const signal = ctl.signal;
+    const stream = await conn.newStream(HTTP_PROTOCOL, { signal, runOnLimitedConnection: true });
+    const asError = (reason) => (reason instanceof Error ? reason : new Error(String(reason)));
+    const abortStream = () => stream.abort(asError(signal.reason));
+    signal.addEventListener("abort", abortStream, { once: true });
+    const headers = new Headers();
+    request.headers.forEach((value, name) => {
+        if (name !== "host" && name !== "content-length" && name !== "transfer-encoding" && name !== HEADER_MESH_BISCUIT && name !== HEADER_PEER_ID) {
+            headers.set(name, value);
+        }
+    });
+    headers.set("host", peerId);
+    headers.set(HEADER_MESH_BISCUIT, toBase64(biscuit));
+    const body = request.body === null ? new Uint8Array(0) : new Uint8Array(await request.arrayBuffer());
+    headers.set("content-length", String(body.length));
+    try {
+        await sendAll(stream, encodeRequestHead(request.method, target, headers));
+        await sendAll(stream, body);
+        const reader = new ByteReader(streamSource(stream));
+        const head = await readResponseHead(reader);
+        headersIn = true;
+        signal.throwIfAborted();
+        const framing = responseBodyFraming(request.method, head);
+        const done = (err) => {
+            signal.removeEventListener("abort", abortStream);
+            if (err !== undefined) {
+                stream.abort(err);
+            }
+            else {
+                void stream.close().catch(() => { });
+            }
+        };
+        let responseBody = null;
+        if (framing.kind === "none") {
+            done();
+        }
+        else {
+            responseBody = bodyStream(reader, framing, done);
+        }
+        return new Response(responseBody, { status: head.status, statusText: head.statusText, headers: head.headers });
+    }
+    catch (err) {
+        stream.abort(asError(err));
+        throw signal.aborted ? (signal.reason ?? err) : err;
+    }
+}
+/** One request to /<type>/<name>/<path> on a peer, body read whole. */
+export async function httpRequestOverStream(conn, biscuit, targetService, path, options = {}) {
+    const signal = options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    const init = { method: options.method ?? "GET", headers: options.headers ?? {}, signal };
+    if (options.body !== undefined) {
+        init.body = options.body;
+    }
+    const request = new Request(meshURL(conn.remotePeer.toString(), targetService, path), init);
+    const streamOptions = { signal };
+    const response = await fetchOverStream(conn, biscuit, request, streamOptions);
+    const buf = new Uint8Array(await response.arrayBuffer());
+    if (buf.length > MAX_INGRESS_BODY_BYTES) {
+        throw new Error("response body too large");
+    }
+    const flat = {};
+    response.headers.forEach((value, key) => {
+        flat[key] = value;
+    });
+    return { status: response.status, headers: flat, body: buf, text: () => new TextDecoder().decode(buf) };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,67 @@
+import type { Connection, Stream } from "@libp2p/interface";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { type JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import { type VerifiedBiscuit } from "./biscuit.ts";
+/** go-msgio's default message cap, which agentmesh-node's StreamTransport uses. */
+export declare const MAX_MCP_MESSAGE_BYTES: number;
+/** The MCP client the SDK identifies itself as. */
+export declare const MCP_CLIENT_INFO: {
+    name: string;
+    version: string;
+};
+/**
+ * A Transport for @modelcontextprotocol/sdk over a libp2p stream that has
+ * already passed the auth handshake.
+ */
+export declare class StreamTransport implements Transport {
+    #private;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(stream: Stream);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+}
+export interface MCPSessionOptions {
+    /** Labels the provider's credential must all carry, e.g. { region: "eu", compliance: "gdpr" }. */
+    requiredLabels?: Record<string, string>;
+    signal?: AbortSignal;
+    /** The mesh policy as the session synced it (Session.policyRules); set by the session, not the caller. */
+    policyRules?: readonly string[];
+}
+/** An open MCP session with a provider on the mesh. */
+export interface MCPSession {
+    client: Client;
+    /** The provider's verified credential. */
+    provider: VerifiedBiscuit;
+    close(): Promise<void>;
+}
+/**
+ * The provider's credential lacks a label the caller requires or a label of
+ * the session's egress floor, as checkPeerLabels refuses.
+ */
+export declare class LabelsNotSatisfiedError extends Error {
+    constructor(peerId: string, required: string[], what: string);
+}
+/**
+ * A requirement is satisfied only when the provider attests every pair, as
+ * agentmesh-node's api.LabelCheck (`check if label(k1, v1), label(k2, v2)`), the
+ * same rule as the egress floor. A map holds one value per key, so listing
+ * several pairs narrows the acceptable providers. Empty is no requirement.
+ */
+export declare function requireLabels(provider: VerifiedBiscuit, required: Record<string, string> | undefined): void;
+/**
+ * The session's egress floor, agentmesh-node's egress.require_labels: the same
+ * rule as requireLabels, refused with a message that names the floor. Empty
+ * is no floor.
+ */
+export declare function requireEgressLabels(provider: VerifiedBiscuit, required: Record<string, string> | undefined): void;
+/**
+ * Opens /mesh/mcp/1.0.0 to a connected provider for targetService ("" is the
+ * provider's own catalog), verifies the provider, and returns a connected
+ * MCP client. frame is this member's AuthFrame for that service; egressRequireLabels
+ * is the session's, not the caller's (requireEgressLabels).
+ */
+export declare function openMCPSession(conn: Connection, frame: Uint8Array, trustedKeys: Uint8Array[], options?: MCPSessionOptions, egressRequireLabels?: Record<string, string>): Promise<MCPSession>;