[ENG-4060] Accept a peer address from Fetch runtimes

[patchstackdave]

A WHATWG Request carries no transport peer. On Fetch runtimes the client address therefore always read as unavailable, and a trustedProxy policy could never apply.

New option: peerAddress. The host supplies the peer it knows, for example (req, info) => info.remoteAddr.hostname on Deno or (req, server) => server.requestIP(req)?.address on Bun.

• It is called with the request the host served and the host's handler arguments.
• fetch(handler) already receives those arguments. fetchGuard()(request, ...args) and the Supabase tunnel now pass them on.
• The tunnel reads the peer from the request the host served, not from the request it rebuilds.
• The result counts as the transport peer for client address resolution, including trustedProxy.
• A callback that throws is reported through onError and supplies no peer. A value that is not an address supplies no peer.

Warning. With trustedProxy set and no usable peer, the guard warns once, through onError or on the console.

Response screening for a request the guard has already screened reuses that request's resolved address. For a request it has not screened, screenResponse(response, request, ...args) resolves the address the same way, through peerAddress, passing any further arguments on as the host's handler arguments.

Without the new option, behaviour is unchanged. AGENT-INSTALL.md and the declarations describe it. Because AGENT-INSTALL.md changed, the hostile field-test run is still outstanding. It has to run immediately after the release that contains this change: a run before that release inspects the previously published docs.

Validation: full suite, typecheck, build, and the capability check.

Part of ENG-4060.

🤖 Generated with Claude Code

[coderbuds]

Well-structured feature adding host-supplied peer addresses across runtimes.

🎯 Quality: 100% Elite · 📦 Size: Medium

🤖 Authorship: Agent-written — Claude Code, going by its own attribution. Whether a person read it is unknown; coding agents can call the report-ai-usage tool to say.

📈 This month: Your 161st PR — above team average · Averaging Excellent

_{See how your team is trending →}

[patchstackdave]

/review