Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
sdk: keep the interface path when rewriting the A2A agent card
Vitalii Cherepanov9fa539d2b3ec
diff --git a/sdk/js/src/libp2p-http.test.ts b/sdk/js/src/libp2p-http.test.tsindex e518bcd0..95235f76 100644--- a/sdk/js/src/libp2p-http.test.ts+++ b/sdk/js/src/libp2p-http.test.ts@@ -38,6 +38,7 @@ import {httpRequestOverStream,meshHTTPTarget,meshURL,+ meshInterfaceURL,rewriteAgentCard,splitMeshURL,type ProviderOptions,@@ -308,11 +309,75 @@ test("the card of an agent behind a node comes back rewritten for the mesh, as atest("rewriteAgentCard keeps only what the mesh carries", () => {assert.throws(() => rewriteAgentCard([], "http://mesh/x"), /not a JSON object/);assert.throws(() => rewriteAgentCard({ supportedInterfaces: [] }, "http://mesh/x"), /no supported interface/);- assert.deepEqual(rewriteAgentCard({ supportedInterfaces: [{ url: "x", protocolBinding: "http+json" }] }, "http://mesh/x"), {+ assert.deepEqual(rewriteAgentCard({ supportedInterfaces: [{ url: "http://localhost:7777/", protocolBinding: "http+json" }] }, "http://mesh/x"), {supportedInterfaces: [{ url: "http://mesh/x", protocolBinding: "http+json" }],});});+// As agentmesh-node's TestA2AServiceCardKeepsInterfacePaths: the provider's node names+// each interface relative to its target URL, and the caller's card resolves it under+// the mesh URL, so an agent whose JSON-RPC endpoint is "/invoke" stays reachable there.+test("rewriteAgentCard keeps the interface path the provider names", () => {+ const base = "http://mesh/mesh/12D3KooWpeer/a2a/agent";+ const card = rewriteAgentCard(+ {+ supportedInterfaces: [+ { url: "invoke", protocolBinding: "JSONRPC" },+ { url: "a2a/rest", protocolBinding: "HTTP+JSON" },+ { url: "", protocolBinding: "JSONRPC" },+ { url: "v1/rpc?tenant=a", protocolBinding: "JSONRPC" },+ { url: "http://localhost:7777/invoke", protocolBinding: "JSONRPC" },+ { protocolBinding: "JSONRPC" },+ { url: "localhost:50051", protocolBinding: "GRPC" },+ ],+ },+ base,+ );+ assert.deepEqual(+ (card.supportedInterfaces as { url: string }[]).map((iface) => iface.url),+ [`${base}/invoke`, `${base}/a2a/rest`, base, `${base}/v1/rpc?tenant=a`, base, base],+ );+});++// As agentmesh-node's TestMeshInterfaceURLStaysInService: a provider cannot use the+// relative reference to point a caller at another path on the caller's own node.+test("meshInterfaceURL stays in the service", () => {+ const base = "http://127.0.0.1:8080/mesh/12D3KooWpeer/a2a/agent";+ for (const [ref, want] of [+ ["", base],+ ["invoke", `${base}/invoke`],+ ["a2a/rest/", `${base}/a2a/rest/`],+ ["?tenant=a", `${base}?tenant=a`],+ ["../../../../debug/connect-peer", base],+ ["a/../../x", base],+ ["%2e%2e/%2e%2e/debug", base],+ ["./invoke", base],+ ["/debug/connect-peer", base],+ ["//evil.example/x", base],+ ["http://localhost:7777/invoke", base],+ ["mailto:[email protected]", base],+ ["%zz", base],+ // Go's url.Parse and URL.EscapedPath, byte for byte.+ ["invoke#frag", `${base}/invoke`],+ ["invoke#%zz", base],+ ["in\tvoke", base],+ ["1a:b", base],+ ["v1/a:b", `${base}/v1/a:b`],+ ["a%2Fb", `${base}/a%2Fb`],+ ["a%41", `${base}/a%41`],+ ["%2f/debug", base],+ ["%2A", `${base}/*`],+ ["it's(1)*", `${base}/it's(1)*`],+ ["a b", `${base}/a%20b`],+ ["a b%41", `${base}/a%20bA`],+ ["\u00e9t\u00e9", `${base}/%C3%A9t%C3%A9`],+ ["x?", `${base}/x`],+ ["x?a?b", `${base}/x?a?b`],+ ]) {+ assert.equal(meshInterfaceURL(base, ref!), want, `meshInterfaceURL(${JSON.stringify(ref)})`);+ }+});+test("a fetch handler sees the caller and the path, and its streaming body goes out as it is written", async () => {const conn = await dial(handlerAgent);const res = await httpRequestOverStream(conn, callerBiscuit, "a2a://agent", "/tasks?x=1", { method: "POST", headers: { "x-mesh-biscuit": "spoof", "content-type": "text/plain" }, body: "hello" });diff --git a/sdk/js/src/libp2p-http.ts b/sdk/js/src/libp2p-http.tsindex c7570257..c779878c 100644--- a/sdk/js/src/libp2p-http.ts+++ b/sdk/js/src/libp2p-http.ts@@ -413,7 +413,7 @@ function agentCardService(method: string, target: string): string | undefined {/*** An agent card rebuilt for the mesh, as agentmesh-node's egress proxy serves it:- * HTTP interfaces point at base, gRPC ones go, signatures no longer match.+ * 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: unknown, base: string): Record<string, unknown> {@@ -423,13 +423,119 @@ export function rewriteAgentCard(card: unknown, base: string): Record<string, unconst out = { ...(card as Record<string, unknown>) };delete out.signatures;const interfaces = Array.isArray(out.supportedInterfaces) ? (out.supportedInterfaces as unknown[]) : [];- const kept = interfaces.filter(carriedOverHTTP).map((iface) => ({ ...(iface as Record<string, unknown>), url: base }));+ const kept = interfaces.filter(carriedOverHTTP).map((iface) => {+ const url = (iface as { url?: unknown }).url;+ return { ...(iface as Record<string, unknown>), 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: string, raw: string): string {+ 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: number): number {+ 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: Uint8Array): Uint8Array | undefined {+ const out: number[] = [];+ 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: string, encoded: Uint8Array, decoded: Uint8Array): string {+ 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: Uint8Array): string {+ 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: Uint8Array): string {+ 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: unknown): boolean {const binding = typeof iface === "object" && iface !== null ? (iface as { protocolBinding?: unknown }).protocolBinding : undefined;diff --git a/sdk/python/src/agent_mesh/libp2p_http.py b/sdk/python/src/agent_mesh/libp2p_http.pyindex 78f46b68..68a483b3 100644--- a/sdk/python/src/agent_mesh/libp2p_http.py+++ b/sdk/python/src/agent_mesh/libp2p_http.py@@ -337,15 +337,91 @@ def _agent_card_service(method: str, target: str) -> Optional[str]:return f"a2a://{m.group(1)}" if method == "GET" and m else None+def mesh_interface_url(base: str, raw: str) -> str:+ """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."""+ before_fragment, hash_sep, fragment = raw.partition("#")+ if hash_sep and _percent_decode(_utf8(fragment)) is None:+ return base+ if _CONTROL_CHAR.search(before_fragment):+ return base+ raw_path, _, raw_query = before_fragment.partition("?")+ # A scheme, or for Go a parse error: a colon in the first segment.+ if ":" in raw_path.split("/", 1)[0]:+ return base+ # "//" alone is an empty authority and an empty path; any other authority+ # names a host, a user or a rooted path.+ if raw_path == "//":+ raw_path = ""+ encoded = _utf8(raw_path)+ decoded = _percent_decode(encoded)+ if decoded is None or decoded.startswith(b"/") or any(seg in (b".", b"..") for seg in decoded.split(b"/")):+ return base+ out = base+ if decoded:+ out += "/" + _escaped_path(raw_path, encoded, decoded)+ if raw_query:+ out += "?" + raw_query+ return out+++_CONTROL_CHAR = re.compile(r"[\x00-\x1f\x7f]")+# Bytes Go's url package leaves alone in a path (shouldEscape(c, encodePath) is false).+_PATH_SAFE = frozenset(b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~$&+,/:;=@")+# Bytes Go's validEncoded also accepts in an already escaped path.+_PATH_SUB_DELIMS = frozenset(b"!'()*[]%")+_HEX_DIGITS = frozenset(b"0123456789abcdefABCDEF")+++def _utf8(s: str) -> bytes:+ """UTF-8 as Go sees a JSON string: a lone surrogate is U+FFFD."""+ return s.encode("utf-16", "surrogatepass").decode("utf-16", "replace").encode()+++def _percent_decode(data: bytes) -> Optional[bytes]:+ """Percent-decodes bytes, or None when a "%" is not followed by two hex digits."""+ out = bytearray()+ i = 0+ while i < len(data):+ if data[i] != 0x25:+ out.append(data[i])+ i += 1+ continue+ pair = data[i + 1 : i + 3]+ if len(pair) != 2 or pair[0] not in _HEX_DIGITS or pair[1] not in _HEX_DIGITS:+ return None+ out.append(int(pair, 16))+ i += 3+ return bytes(out)+++def _escaped_path(raw_path: str, encoded: bytes, decoded: bytes) -> str:+ """Go's URL.EscapedPath: the path as written when that is a valid escaping of it, else the default escaping."""+ escaped = _percent_encode_path(decoded)+ if escaped != raw_path and all(c in _PATH_SAFE or c in _PATH_SUB_DELIMS for c in encoded):+ return raw_path+ return "*" if decoded == b"*" else escaped+++def _percent_encode_path(data: bytes) -> str:+ return "".join(chr(c) if c in _PATH_SAFE else f"%{c:02X}" for c in data)++def rewrite_agent_card(card: object, base: str) -> dict:"""An agent card rebuilt for the mesh, as agentmesh-node's egress proxy serves- it: HTTP interfaces point at base, gRPC ones go, signatures no longer match.+ it: HTTP interfaces resolve under base (mesh_interface_url), gRPC ones go,+ signatures no longer match.Streaming stays as declared, this transport streams. Raises when no interface remains."""if not isinstance(card, dict):raise ValueError("agent card is not a JSON object")interfaces = card.get("supportedInterfaces")kept = [- {**iface, "url": base}+ {**iface, "url": mesh_interface_url(base, iface["url"] if isinstance(iface.get("url"), str) else "")}for iface in (interfaces if isinstance(interfaces, list) else [])if isinstance(iface, dict) and str(iface.get("protocolBinding", "")).upper() in _HTTP_BINDINGS]@@ -534,6 +610,7 @@ __all__: Sequence[str] = ("http_ingress_handler","http_request_over_stream","mesh_http_target",+ "mesh_interface_url","mesh_url","open_http_request","rewrite_agent_card",diff --git a/sdk/python/tests/test_libp2p_http.py b/sdk/python/tests/test_libp2p_http.pyindex 02d41ea4..2af740dd 100644--- a/sdk/python/tests/test_libp2p_http.py+++ b/sdk/python/tests/test_libp2p_http.py@@ -44,6 +44,7 @@ from agent_mesh.libp2p_http import (http_ingress_handler,http_request_over_stream,mesh_http_target,+ mesh_interface_url,open_http_request,rewrite_agent_card,)@@ -307,11 +308,84 @@ def test_rewrite_agent_card_keeps_only_what_the_mesh_carries():rewrite_agent_card([], "http://mesh/x")with pytest.raises(ValueError, match="no supported interface"):rewrite_agent_card({"supportedInterfaces": []}, "http://mesh/x")- assert rewrite_agent_card({"supportedInterfaces": [{"url": "x", "protocolBinding": "http+json"}]}, "http://mesh/x") == {+ assert rewrite_agent_card({"supportedInterfaces": [{"url": "http://localhost:7777/", "protocolBinding": "http+json"}]}, "http://mesh/x") == {"supportedInterfaces": [{"url": "http://mesh/x", "protocolBinding": "http+json"}],}+def test_rewrite_agent_card_keeps_the_interface_path_the_provider_names():+ # As agentmesh-node's TestA2AServiceCardKeepsInterfacePaths: the provider's node names+ # each interface relative to its target URL, and the caller's card resolves it under+ # the mesh URL, so an agent whose JSON-RPC endpoint is "/invoke" stays reachable there.+ base = "http://mesh/mesh/12D3KooWpeer/a2a/agent"+ card = rewrite_agent_card(+ {+ "supportedInterfaces": [+ {"url": "invoke", "protocolBinding": "JSONRPC"},+ {"url": "a2a/rest", "protocolBinding": "HTTP+JSON"},+ {"url": "", "protocolBinding": "JSONRPC"},+ {"url": "v1/rpc?tenant=a", "protocolBinding": "JSONRPC"},+ {"url": "http://localhost:7777/invoke", "protocolBinding": "JSONRPC"},+ {"protocolBinding": "JSONRPC"},+ {"url": "localhost:50051", "protocolBinding": "GRPC"},+ ],+ },+ base,+ )+ assert [iface["url"] for iface in card["supportedInterfaces"]] == [+ f"{base}/invoke",+ f"{base}/a2a/rest",+ base,+ f"{base}/v1/rpc?tenant=a",+ base,+ base,+ ]+++BASE = "http://127.0.0.1:8080/mesh/12D3KooWpeer/a2a/agent"+++# As agentmesh-node's TestMeshInterfaceURLStaysInService: a provider cannot use the+# relative reference to point a caller at another path on the caller's own node.+ ("ref", "want"),+ [+ ("", BASE),+ ("invoke", f"{BASE}/invoke"),+ ("a2a/rest/", f"{BASE}/a2a/rest/"),+ ("?tenant=a", f"{BASE}?tenant=a"),+ ("../../../../debug/connect-peer", BASE),+ ("a/../../x", BASE),+ ("%2e%2e/%2e%2e/debug", BASE),+ ("./invoke", BASE),+ ("/debug/connect-peer", BASE),+ ("//evil.example/x", BASE),+ ("http://localhost:7777/invoke", BASE),+ ("mailto:[email protected]", BASE),+ ("%zz", BASE),+ # Go's url.Parse and URL.EscapedPath, byte for byte.+ ("invoke#frag", f"{BASE}/invoke"),+ ("invoke#%zz", BASE),+ ("in\tvoke", BASE),+ ("1a:b", BASE),+ ("v1/a:b", f"{BASE}/v1/a:b"),+ ("a%2Fb", f"{BASE}/a%2Fb"),+ ("a%41", f"{BASE}/a%41"),+ ("%2f/debug", BASE),+ ("%2A", f"{BASE}/*"),+ ("it's(1)*", f"{BASE}/it's(1)*"),+ ("a b", f"{BASE}/a%20b"),+ ("a b%41", f"{BASE}/a%20bA"),+ ("\u00e9t\u00e9", f"{BASE}/%C3%A9t%C3%A9"),+ ("\ud800", f"{BASE}/%EF%BF%BD"),+ ("x?", f"{BASE}/x"),+ ("x?a?b", f"{BASE}/x?a?b"),+ ],+)+def test_mesh_interface_url_stays_in_the_service(ref, want):+ assert mesh_interface_url(BASE, ref) == want++def test_an_in_process_handler_sees_the_verified_caller():async def hello(request: HTTPRequest, caller) -> HTTPResponse:return HTTPResponse(status=201, body=f"hello {caller.peer_id} {request.method} {request.path}".encode())