feat(gateway): fetch AgentCard on first contact — activate DID fallback

raahulrahl · claude · raahulrahl · commit d540ef2a53ad · 2026-04-20T16:44:44.000+02:00
Resolves the second high-severity entry in BUGS_AND_KNOWN_ISSUES.md —
the `peer.card` fallback at bindu/client/index.ts:196 was dead code
because nothing in the codebase ever populated it. Signature
verification required a pinnedDID; with none set, maybeVerifySignatures
always short-circuited.

New src/bindu/client/agent-card.ts — fetchAgentCard(peerUrl, opts):
  - GETs /.well-known/agent.json, Zod-parses against the AgentCard
    schema, caches per-process.
  - 2-second default timeout (short because it blocks the first call
    per peer; callers can override).
  - Every failure mode degrades to null: non-2xx, malformed JSON,
    schema mismatch, network error, abort. Failures are cached too so
    a flaky peer doesn't cost one outbound fetch per /plan.

Wired into runCall at bindu/client/index.ts: fetches only when
`trust.verifyDID: true` AND peer.card isn't already set. No cost on
peers that don't care about verification. Mutation of input.peer.card
is safe because PeerDescriptor is built fresh per catalog entry per
request.

End-to-end effect: `trust.verifyDID: true` WITHOUT `pinnedDID` is now
a real feature. The gateway observes the peer's published DID,
resolves its public key via the DID document, and verifies every
artifact signature against it. Pinned wins over observed when both
are set (pinning is a stronger security claim — the caller vouched
for the identity, while observed just trusts what the peer published).

Coverage: tests/bindu/agent-card-fetch.test.ts — 9 cases:
  - success path parses valid card
  - 404 returns null
  - malformed JSON returns null
  - schema mismatch returns null
  - network throw returns null
  - cache hit skips re-fetch (same reference returned)
  - negative cache skips re-fetch on known-bad peer
  - per-URL isolation — different peers fetched independently
  - timeout honored via internal AbortController

BUGS_AND_KNOWN_ISSUES.md: original AgentCard entry marked RESOLVED
with cross-refs to the helper and test. A new medium entry now
tracks the remaining follow-up — SSE's agent_did field still only
reflects pinned DIDs, not observed ones. That's plan-route.ts layer
(findPinnedDID → findAgentDID with observed fallback), scheduled
next.

Typecheck clean, 210/210 tests pass (+9 agent-card-fetch).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/gateway/docs/BUGS_AND_KNOWN_ISSUES.md b/gateway/docs/BUGS_AND_KNOWN_ISSUES.md
@@ -47,26 +47,66 @@ Shipped on branch `feat/gateway-recipes` prior to merge.
 
 ---
 
-### 🔴 `peer.card` is never populated — AgentCard-based DID fallback is dead code
+### ✅ RESOLVED — `peer.card` is now populated via `fetchAgentCard`
 
-**Where:** [`src/bindu/client/index.ts:196`](../src/bindu/client/index.ts:196)
+**Was at:** [`src/bindu/client/index.ts:196`](../src/bindu/client/index.ts:196) (the fallback itself unchanged — it was correct, just starved of input).
+
+**Fixed by:** new [`src/bindu/client/agent-card.ts`](../src/bindu/client/agent-card.ts) —
+`fetchAgentCard(peerUrl, opts)` that GETs `<peer_url>/.well-known/agent.json`,
+Zod-parses it, and caches per-process. Wired into `runCall` at
+[`bindu/client/index.ts:153-159`](../src/bindu/client/index.ts:153):
 
 ```ts
-const did = peer.trust.pinnedDID ?? (peer.card ? getPeerDID(peer.card) : null)
+if (!input.peer.card && input.peer.trust?.verifyDID) {
+  const card = await fetchAgentCard(input.peer.url, { signal: input.signal })
+  if (card) input.peer.card = card
+}
 ```
 
-The `peer.card` branch is permanently `null` — nothing in the codebase
-fetches `/.well-known/agent.json` or sets `PeerDescriptor.card`. Grep
-confirms: no writes to `peer.card =` anywhere. Either:
+Now `trust.verifyDID: true` *without* a `pinnedDID` is a real feature:
+the gateway observes the peer's published DID, resolves its public key
+via the DID document, and verifies every artifact signature against it.
+The pinned path still wins when both are set.
+
+Design choices:
+- **Fetch only when `verifyDID: true`** — no network cost on peers that
+  don't care about verification.
+- **2-second timeout** — short because it blocks the first call per
+  peer. Failures degrade to null (same behavior as before the fix).
+- **Per-process cache includes negatives** — a flaky peer doesn't cost
+  one outbound fetch per `/plan`.
+- **Mutation of `input.peer.card`** is safe because `PeerDescriptor`
+  is built fresh per catalog entry per request — no cross-session
+  leak.
+
+Coverage: [`tests/bindu/agent-card-fetch.test.ts`](../tests/bindu/agent-card-fetch.test.ts)
+— 9 cases (success / 404 / malformed / schema-mismatch / network
+failure / cache hit / negative cache / per-URL isolation / timeout).
+
+**Remaining follow-up — SSE `agent_did` still null without pinnedDID.**
+`plan-route.ts`'s [`findPinnedDID()`](../src/api/plan-route.ts:314) only
+reads `trust.pinnedDID`. The observed DID from `peer.card` isn't
+surfaced in the SSE stream yet. Separate ticket; tracked below as
+🟠 "SSE `agent_did` doesn't surface observed DIDs".
+
+---
+
+### 🟠 SSE `agent_did` doesn't surface observed DIDs
+
+**Where:** [`src/api/plan-route.ts:314-316`](../src/api/plan-route.ts:314) — `findPinnedDID` only reads `trust.pinnedDID` from the request catalog.
 
-1. Implement AgentCard fetch at first call per session (the "option C"
-   from the earlier design discussion), OR
-2. Delete the fallback and mark `peer.card` as reserved for a future
-   feature — pretending the fallback exists is worse than owning up.
+Consequence: even after `fetchAgentCard` populates `peer.card` inside the
+Bindu client (see the resolved AgentCard-fallback entry above), the SSE
+stream still emits `agent_did: null` unless the caller pinned a DID up
+front. Signature verification works against the observed DID; the
+display layer doesn't know about it.
 
-The plan-route's [`findPinnedDID()`](../src/api/plan-route.ts:314) also
-only reads `pinnedDID`, so `agent_did` in SSE is `null` whenever the
-caller didn't pin. Users quickly trip on this.
+**Fix:** rename to `findAgentDID(request, agentName)`, add an observed-DID
+path (reads a per-plan cache populated after the first successful call
+publishes a Bus event with the observed DID), and add an optional
+`agent_did_source: "pinned" | "observed" | null` field on SSE frames so
+consumers can tell the provenance. Detailed in the earlier design
+discussion; ~80 LOC including tests.
 
 ---
 
diff --git a/gateway/src/bindu/client/agent-card.ts b/gateway/src/bindu/client/agent-card.ts
@@ -0,0 +1,88 @@
+import { AgentCard } from "../protocol/agent-card"
+
+/**
+ * Fetch and parse a peer's AgentCard from `/.well-known/agent.json`.
+ *
+ * Populated via this helper, the `peer.card` field on a PeerDescriptor
+ * activates the DID fallback in `maybeVerifySignatures` — when the
+ * caller sets `trust.verifyDID: true` but didn't pin a DID, the
+ * gateway can recover the peer's published DID from its AgentCard and
+ * verify artifacts against the corresponding public key.
+ *
+ * # Cache
+ *
+ * Per-process, keyed by peer URL. AgentCards are stable for the life
+ * of the peer process; a gateway restart is an acceptable boundary
+ * for picking up a rotated identity. Negative results (404, malformed
+ * JSON, timeout) are cached too so a flaky peer doesn't cost us one
+ * outbound fetch per /plan.
+ *
+ * # Timeout
+ *
+ * 2 seconds by default — the fetch blocks the first call to a new
+ * peer, so we keep it short. Callers can override via the opts.
+ *
+ * # Errors become `null`
+ *
+ * Every failure mode (network error, non-2xx, invalid JSON, schema
+ * mismatch, abort) returns `null` rather than throwing. The fallback
+ * in maybeVerifySignatures degrades gracefully — null peer.card just
+ * means the pinnedDID path is the only option, same behavior as before
+ * this module existed. Errors aren't "safety failures" here; they're
+ * "couldn't enrich."
+ */
+
+const cache = new Map<string, AgentCard | null>()
+
+export interface FetchAgentCardOptions {
+  readonly signal?: AbortSignal
+  readonly timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 2000
+const WELL_KNOWN_PATH = "/.well-known/agent.json"
+
+export async function fetchAgentCard(
+  peerUrl: string,
+  opts: FetchAgentCardOptions = {},
+): Promise<AgentCard | null> {
+  if (cache.has(peerUrl)) return cache.get(peerUrl) ?? null
+
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), timeoutMs)
+  const onUpstreamAbort = () => ac.abort()
+  opts.signal?.addEventListener("abort", onUpstreamAbort, { once: true })
+
+  try {
+    const target = new URL(WELL_KNOWN_PATH, peerUrl).toString()
+    const res = await fetch(target, { signal: ac.signal })
+    if (!res.ok) {
+      cache.set(peerUrl, null)
+      return null
+    }
+    const json = (await res.json()) as unknown
+    const parsed = AgentCard.safeParse(json)
+    if (!parsed.success) {
+      cache.set(peerUrl, null)
+      return null
+    }
+    cache.set(peerUrl, parsed.data)
+    return parsed.data
+  } catch {
+    cache.set(peerUrl, null)
+    return null
+  } finally {
+    clearTimeout(timer)
+    opts.signal?.removeEventListener("abort", onUpstreamAbort)
+  }
+}
+
+/**
+ * Reset the AgentCard cache. Only intended for use in tests — production
+ * callers have no reason to evict (a gateway restart picks up any
+ * identity rotation). Exported on a `__`-prefixed name to signal intent.
+ */
+export function __resetAgentCardCacheForTests(): void {
+  cache.clear()
+}
diff --git a/gateway/src/bindu/client/index.ts b/gateway/src/bindu/client/index.ts
@@ -10,6 +10,7 @@ import { verifyArtifact } from "../identity/verify"
 import { createResolver, primaryPublicKeyBase58 } from "../identity/resolve"
 import { getPeerDID } from "../protocol/identity"
 import type { AgentCard } from "../protocol/agent-card"
+import { fetchAgentCard } from "./agent-card"
 
 /**
  * Public Bindu client — the thing the planner's tools invoke.
@@ -148,6 +149,22 @@ async function runCall(
   identity: LocalIdentity | undefined,
   tokenProvider: TokenProvider | undefined,
 ): Promise<CallPeerOutcome> {
+  // Populate peer.card from /.well-known/agent.json on first contact.
+  // Cached per process — subsequent calls to the same peer are free.
+  // This activates the AgentCard-based DID fallback in
+  // maybeVerifySignatures: when the caller enabled `trust.verifyDID`
+  // without pinning a DID, the gateway recovers the peer's published
+  // DID here and verifies against its public key.
+  //
+  // Runs concurrently-safe (cache handles races via last-write-wins,
+  // AgentCards are stable), non-blocking on failure (returns null,
+  // peer.card stays undefined, verification falls through to the
+  // pinnedDID-only path).
+  if (!input.peer.card && input.peer.trust?.verifyDID) {
+    const card = await fetchAgentCard(input.peer.url, { signal: input.signal })
+    if (card) input.peer.card = card
+  }
+
   const parts: Part[] =
     typeof input.input === "string" ? [{ kind: "text", text: input.input }] : input.input
 
diff --git a/gateway/tests/bindu/agent-card-fetch.test.ts b/gateway/tests/bindu/agent-card-fetch.test.ts
@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest"
+import { fetchAgentCard, __resetAgentCardCacheForTests } from "../../src/bindu/client/agent-card"
+
+/**
+ * Coverage for the AgentCard fetch helper — the piece that activates
+ * maybeVerifySignatures' observed-DID fallback when the caller enabled
+ * `trust.verifyDID: true` without pinning a DID.
+ *
+ * Resolves the "peer.card is never populated" high-severity entry in
+ * BUGS_AND_KNOWN_ISSUES.md: before this module, the fallback at
+ * bindu/client/index.ts:196 was dead code because nothing ever set
+ * peer.card. These tests pin the four real outcomes (success, 404,
+ * malformed body, cache hit) and the degrade-to-null contract on
+ * every failure mode.
+ */
+
+const VALID_CARD = {
+  id: "did:bindu:ops_at_example_com:research:7dc57d21-2c81-f6f5-c679-e51995f97e22",
+  name: "research",
+  description: "Web search and summarize.",
+  skills: [],
+  defaultInputModes: ["text/plain"],
+  defaultOutputModes: ["text/plain"],
+  capabilities: {
+    extensions: [
+      {
+        uri: "did:bindu:ops_at_example_com:research:7dc57d21-2c81-f6f5-c679-e51995f97e22",
+      },
+    ],
+  },
+}
+
+describe("fetchAgentCard", () => {
+  beforeEach(() => {
+    __resetAgentCardCacheForTests()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it("fetches and parses a valid AgentCard from /.well-known/agent.json", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(VALID_CARD), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    )
+
+    const result = await fetchAgentCard("http://localhost:3773")
+    expect(result).not.toBeNull()
+    expect(result?.name).toBe("research")
+    expect(fetchSpy).toHaveBeenCalledWith(
+      "http://localhost:3773/.well-known/agent.json",
+      expect.objectContaining({ signal: expect.anything() }),
+    )
+  })
+
+  it("returns null on non-2xx without throwing", async () => {
+    vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response("not found", { status: 404 }),
+    )
+
+    const result = await fetchAgentCard("http://localhost:3773")
+    expect(result).toBeNull()
+  })
+
+  it("returns null on malformed JSON body", async () => {
+    vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response("not a json body, just a string", {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    )
+
+    const result = await fetchAgentCard("http://localhost:3773")
+    expect(result).toBeNull()
+  })
+
+  it("returns null when the body doesn't match the AgentCard schema", async () => {
+    vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ wrong: "shape" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    )
+
+    const result = await fetchAgentCard("http://localhost:3773")
+    expect(result).toBeNull()
+  })
+
+  it("returns null and caches the failure when fetch throws", async () => {
+    vi.spyOn(global, "fetch").mockRejectedValue(new Error("ECONNREFUSED"))
+
+    const result = await fetchAgentCard("http://localhost:3773")
+    expect(result).toBeNull()
+  })
+
+  it("caches successful results — second call does not re-fetch", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(VALID_CARD), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      }),
+    )
+
+    const first = await fetchAgentCard("http://localhost:3773")
+    const second = await fetchAgentCard("http://localhost:3773")
+
+    expect(first).toBe(second) // same cached reference
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it("caches failures too — second call does not re-fetch a known-bad peer", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response("", { status: 404 }),
+    )
+
+    await fetchAgentCard("http://localhost:3773")
+    await fetchAgentCard("http://localhost:3773")
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it("caches per-URL — a different peer is fetched independently", async () => {
+    const fetchSpy = vi.spyOn(global, "fetch").mockResolvedValue(
+      new Response(JSON.stringify(VALID_CARD), { status: 200 }),
+    )
+
+    await fetchAgentCard("http://localhost:3773")
+    await fetchAgentCard("http://localhost:3775")
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2)
+    const urls = fetchSpy.mock.calls.map((c) => c[0])
+    expect(urls).toContain("http://localhost:3773/.well-known/agent.json")
+    expect(urls).toContain("http://localhost:3775/.well-known/agent.json")
+  })
+
+  it("aborts on timeout", async () => {
+    // Simulate a fetch that never resolves — the helper's internal
+    // timeout should abort. We use a short timeout and expect null.
+    vi.spyOn(global, "fetch").mockImplementation(
+      (_url, init) =>
+        new Promise((_resolve, reject) => {
+          const signal = (init as { signal?: AbortSignal } | undefined)?.signal
+          signal?.addEventListener("abort", () => reject(new Error("aborted")), {
+            once: true,
+          })
+        }),
+    )
+
+    const result = await fetchAgentCard("http://localhost:3773", { timeoutMs: 50 })
+    expect(result).toBeNull()
+  })
+})
