research: remote agent auth forwarding plan

[AndrewBarba]

Summary

Research plan for forwarding end-user identity across defineRemoteAgent hops, so a per-user principal (and therefore per-user Vercel Connect) survives a cross-deployment delegation.

Closes nothing yet — design doc for #604; implementation PR to follow.

Design at a glance

• Sender: defineRemoteAgent({ forwardAuth: true }) serializes the dispatching turn's auth.current / auth.initiator into a strict-validated forwardedAuth field on the create-session body. OutboundAuthFn also gains an OutboundAuthContext argument so custom schemes can mint per-user credentials at dispatch time.
• Receiver: eveChannel({ forwardedAuth: AuthFn | AuthFn[] }) gates which transport-authenticated callers may assert a forwarded principal, reusing the existing AuthFn / routeAuth primitive. Accepted identities become the session principal, so Connect, local subagents, and chained remote hops work unchanged.
• Only principal metadata crosses the wire — never tokens or credentials. Mismatches fail loud at the hop (403) instead of silently downgrading to service identity.

Notes

• Docs-only (research plan) — no changeset per AGENTS.md.
• pnpm docs:check passes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview, Comment, Open in v0	Jul 8, 2026 4:44pm
eve-docs-1644	Ready	Preview, Comment, Open in v0	Jul 8, 2026 4:44pm
eve-docs-4759	Ready	Preview, Comment, Open in v0	Jul 8, 2026 4:44pm

[AndrewBarba]

Pushed a hardening pass after an end-to-end review of the plan (5431813):

1. Version-skew silent downgrade closed. A pre-forwarding receiver silently ignores unknown create-body fields, which would run the session as the calling service — the exact failure this design rejects. The receiver now acknowledges acceptance (forwardedAuth: "accepted" on the 202), and the sender fails the dispatch when it forwarded a principal and the ack is missing.
2. Gate runs in strict mode. The Vercel OIDC always-on current-project bypass does not apply inside forwardedAuth — otherwise any same-project caller (including preview deployments) could assert arbitrary principals against production Connect grants.
3. Audit trail is receiver-written. eve:forwarded-by is always overwritten from the verified transport principal; a forwarder cannot falsify it. Multi-hop chains record the most recent hop only.
4. Changeset corrected to minor — the OutboundAuthFn signature change is a public API break.
5. Deliver-route parity cut to out-of-scope. Remote dispatch is create-only; nothing in eve would send it today.