RFC: Enforce world-scoped isolation at transport layer (peer/message)

[Jing-yilin]

Context

PR #96 implements world-scoped agent isolation at the discovery layer — agents only learn each other's endpoints through World membership. However, the transport layer has no enforcement: /peer/message accepts messages from anyone with a valid Ed25519 signature, regardless of World membership.

Current Port/Route Analysis

Agent Node (port 8099 HTTP + 8098 UDP)

Route	Auth	World-scoped?	Issue
GET /peer/ping	None	N/A	OK — health check
GET /peer/peers	None	No	Returns all known peers — should this be restricted?
POST /peer/announce	Signature	No	Agent no longer calls this (PR #96), but still accepts inbound
POST /peer/message	Signature + TOFU	No	Anyone can send messages if they know the IP:port
POST /peer/key-rotation	Dual signature	No	Key rotation from any known peer
GET /.well-known/agent.json	None	N/A	Agent Card (public)
UDP 8098	Signature	No	QUIC transport — same issue as /peer/message

World Server (port 8099)

Route	Auth	World-scoped?	Issue
GET /world/members	X-AgentWorld-From header	Partially	Checks if sender is in agentLastSeen, but doesn't verify signature
GET /world/agents	None	No	Public — returns agent summaries from ledger
GET /world/ledger	None	No	Public — returns event log

Registry Node (port 8099)

Route	Auth	World-scoped?
GET /worlds	None	N/A — public directory
POST /peer/announce	Signature	Rejects non-world:* peers (403)

Security Gap

The isolation model is:

Agent A can only communicate with Agent B if they share a World.

But currently:

1. Discovery is scoped ✅ — endpoints only revealed through world.join response
2. Transport is NOT scoped ❌ — /peer/message accepts any signed message
3. If an attacker learns an agent's IP:8099 (scanning, logs, DNS), they can send arbitrary messages

Questions

1. Should /peer/message on agent nodes reject messages from non-co-members? This requires the agent to maintain a set of worldId → Set<agentId> and check the sender.
2. Should /peer/peers be restricted or removed from agent nodes? After PR feat!: world-scoped agent isolation — remove global peer gossip #96, agents don't use peer exchange.
3. Should /peer/announce be restricted or removed from agent nodes? Agents no longer announce.
4. Should /world/agents and /world/ledger require authentication on World Servers?
5. Should /world/members verify the signature (not just the header value)?
6. What about /peer/ping? It reveals agentId — is that acceptable?
7. Should UDP 8098 (QUIC) have the same co-member check?

Possible Approach

Minimal (enforce at message layer):

• Agent tracks co-members: Set<agentId> populated from world.join response + /world/members polling
• /peer/message rejects messages where from is not in any co-member set
• UDP handler applies same check

Aggressive (minimize attack surface):

• Remove /peer/peers, /peer/announce from agent nodes entirely
• Require authentication on /world/agents, /world/ledger
• Sign /world/members requests properly

Related

• PR feat!: world-scoped agent isolation — remove global peer gossip #96: feat!: world-scoped agent isolation
• PR feat: convert bootstrap to World Registry — auto-registration for worlds #99: feat: convert bootstrap to World Registry (merged into feat!: world-scoped agent isolation — remove global peer gossip #96)

[Jing-yilin]

Reviewed current code in src/peer-server.ts and packages/agent-world-sdk/src/peer-protocol.ts, plus packages/agent-world-sdk/src/world-server.ts to verify the current /world/* surface.

Short version: the transport gap is real, but I would take a minimal-plus approach, not a full aggressive sweep yet.

What the current code actually does:

• src/peer-server.ts
  • Public GET /peer/inbox and GET /peer/peers
  • Signed-header-only POST /peer/announce and POST /peer/message
  • POST /peer/message checks HTTP request signature, timestamp, TOFU, and X-AgentWorld-From === body.from, but it does not check shared-world membership
  • UDP handleUdpMessage(...) has the same missing membership check
  • POST /peer/key-rotation is also not membership-scoped; if the peer is unknown it can still seed/update TOFU after the dual proof passes
• packages/agent-world-sdk/src/peer-protocol.ts
  • Public GET /peer/ping and GET /peer/peers
  • POST /peer/announce and POST /peer/message accept either signed HTTP headers or a body signature
  • They also do not check shared-world membership
  • Unlike src/peer-server.ts, the header-auth path does not explicitly enforce X-AgentWorld-From === body.from
• packages/agent-world-sdk/src/world-server.ts
  • There is no /world/members route in the current tree
  • Current public world routes are GET /world/ledger and GET /world/agents
  • world.join / world.action / world.leave are message events handled behind /peer/message

Direct answers to the RFC questions:

1. Should /peer/message reject non-co-members on agent nodes?
   Yes.

2. Should /peer/peers be restricted or removed from agent nodes?
   Remove it from ordinary agent nodes. It is public, and I could not find a runtime call site using GET /peer/peers. If it is still operationally useful anywhere, keep it only on bootstrap/registry roles.

3. Should /peer/announce be restricted or removed from agent nodes?
   Do not remove it blindly yet. Both src/peer-discovery.ts and packages/agent-world-sdk/src/bootstrap.ts still use /peer/announce for discovery. For this stage I would role-gate it, not delete it.

4. Should /world/agents and /world/ledger require authentication on World Servers?
   For public worlds, not necessarily yet. For private worlds, yes. Either way, do not use them as an authorization source until they are signed, because the current response-signing hook only covers /peer/*.

5. Should /world/members verify the signature?
   There is no /world/members route in the current tree. If we add one, yes: signed request and signed response.

6. What about /peer/ping?
   Acceptable to leave public. Exposing agentId is a much smaller issue than unauthenticated transport ingress.

7. Should UDP 8098 have the same co-member check?
   Yes. Apply the exact same authorization rule as HTTP.

Routes to lock down now:

• Agent POST /peer/message
• Agent UDP message ingress
• POST /peer/key-rotation
  • Only allow for an already-authorized / already-known sender
  • Do not let unknown first contact create TOFU state through key rotation
• On world servers, make /peer/message event-aware:
  • Allow world.join from non-members
  • Require current membership for world.action and world.leave
  • If world.state is ever accepted inbound, restrict it to the world host / trusted sender

Routes to remove or disable now:

• GET /peer/inbox in src/peer-server.ts should be removed or made dev-only. This is a direct message disclosure endpoint and is more serious than /peer/peers.
• GET /peer/peers should be removed from ordinary agent nodes.

Why minimal-plus is better than aggressive right now:

• It closes the real isolation bypass first: signed strangers can currently hit message ingress directly.
• The shared SDK currently registers the same peer surface for world servers and agents, so an aggressive sweep needs role-aware route registration first.
• The current code still depends on /peer/announce for discovery, so removing it immediately will break bootstrapping.
• The issue text is slightly out of sync with the tree (/world/members is gone, /peer/announce is still used), so a staged fix is safer than a blanket hardening pass.

Main implementation concern:

Do not use peerDb as the authorization source. It is discovery state, not membership state.

• peerDb contains bootstrap/discovered peers and can outlive active membership.
• World membership today lives in agentLastSeen on the server side, and there is no authoritative signed roster on the client side.
• To make transport checks correct, introduce a separate membership allowlist, for example Map<worldId, Set<agentId>>.

The missing piece is distribution of that allowlist. Right now:

• world.join reply does not return a roster
• /world/members does not exist
• /world/agents is public and unsigned

So I would pair the transport fix with one protocol addition:

• Either add a signed /world/members
• Or include a signed roster snapshot/version in the world.join reply and subsequent world.state updates

Small cleanup while touching this:

• In packages/agent-world-sdk/src/peer-protocol.ts, when header-based auth is used, explicitly require X-AgentWorld-From === body.from just like src/peer-server.ts does.
• Make registerPeerRoutes(...) role-aware so agent nodes, world servers, and bootstrap/registry nodes do not all expose the same routes by default.