feat(server): host-aware serve() for one-process multi-host

[bokelley]

Summary

Closes #885. Adds first-class multi-host routing to serve() so one Node process can front many hostnames (white-label publishers, multi-brand adapters) without re-owning the HTTP plumbing.

Changes

• ServeOptions.publicUrl: string | (host) => string — function form resolves per unique host; result cached. Path-match validation runs against each resolved URL. Static string form unchanged.
• ServeOptions.protectedResource: PRM | (host) => PRM — same pattern. Each host advertises its own RFC 9728 resource + authorization servers.
• ServeContext.host: string — resolved canonical host (lowercased, port preserved) passed into the factory on every request so it can branch on hostname.
• ServeOptions.trustForwardedHost: boolean — default false. Opt-in for X-Forwarded-Host when behind a proxy that sanitizes it (Fly, Cloud Run, internal ALB). Without it, an attacker-controlled header can't flip the advertised OAuth resource.
• verifyBearer({ audience: (req) => string }) — audience check follows the per-host publicUrl so a token minted for snap.example.com fails validation at meta.example.com. Resolver errors surface as sanitized AuthError, not 500.
• SKILL.md — §"Multi-Host and Alternative Transports" replaces the old "on the roadmap" caveat with a working multi-host recipe.

Security properties preserved

• Function-form publicUrl still validates each resolved URL's path against the mount path — mismatch fails closed (500) rather than minting audience-mismatched tokens.
• X-Forwarded-Host ignored by default; opt-in is explicit.
• Resolver throws are caught and logged, response is 500 — not a silent mis-advertisement.

Test plan

• 11 new tests in test/lib/serve-multihost.test.js — host threading, function-form publicUrl + PRM, caching, trustForwardedHost on/off, X-Forwarded-Host chain handling, 404 on missing host, 500 on invalid per-host publicUrl, backward compat for static form.
• 2 new tests in test/server-auth.test.js — function-form audience succeeds for matching host / rejects for mismatched host; resolver throw → sanitized AuthError.
• Full existing serve() + verifyBearer suites pass (54/54 targeted, 5627/5629 full suite — the 2 failures are a pre-existing EADDRINUSE flake on :3112 from a stale process in another Conductor worktree, unrelated).
• tsc --noEmit clean.
• CI green.

🤖 Generated with Claude Code

[bokelley]

Strong overall — security posture is right, the scope stayed tight, and the Express-AS composition recipe is the right addition for adapters that run their own OAuth AS. Three things I'd push back on before merge:

1. audience: (req) => string callback doesn't go through serve()'s host resolution — footgun in the example.

SKILL.md multi-host example (skills/build-seller-agent/SKILL.md) has:

audience: req => `https://${req.headers['x-forwarded-host'] ?? req.headers.host}/mcp`

serve() itself honors trustForwardedHost when resolving host. This audience callback doesn't — it reads X-Forwarded-Host unconditionally. A user copying this example without trustForwardedHost: true advertises one audience (from publicUrl(host)) but verifies against another (whatever X-Forwarded-Host says). Attacker-controlled header flips the audience check but not the advertised PRM — a token minted for the attacker's claimed host verifies, even though the framework advertised a different resource.

Fix options:

• Thread the already-resolved host into the audience callback: audience: (req, { host }) => ...
• Better: expose the resolved publicUrl directly, so the common case is audience: (_req, { publicUrl }) => publicUrl (one line, can't drift from what serve() advertised).

Either way, the example should not read X-Forwarded-Host directly.

2. Missing an end-to-end test for the cryptographic backstop.

The 11 new tests in test/lib/serve-multihost.test.js cover host threading, function-form publicUrl/PRM, caching, trustForwardedHost on/off, and 404/500 paths. What I don't see (and should exist, since it's the security property of multi-host): a named test proving a token minted for host A, presented on a request landing at host B in the same process, fails audience verification at host B. The 2 audience-function tests in test/server-auth.test.js are unit-level — this wants to be end-to-end: two publicUrl(host) mappings, two OAuth audiences, one process, cross-host token, assert 401. If that's covered by one of the existing tests I missed, a rename would make it obvious.

3. throw new Error("Unknown host: X") → 500 is defensible but unkind to ops.

The factory example throws on unregistered hosts, framework catches and 500s. Fine for security (doesn't leak the adapter table) but confusing when an operator typos a DNS entry. A dedicated UnknownHostError mapping to 404 with a clean body would be kinder. Minor — don't block merge on this one.

Security properties I did verify hold: X-Forwarded-Host off by default, path-match validation per resolved URL, fail-closed on resolver throws, per-host result caching. Good shape.

[bokelley]

reopening to retrigger skipped CI workflows