Skip to content

Agent Mesh

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.ts
index 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 a
test("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.ts
index 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, un
const 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.py
index 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.py
index 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())