feat(web): publish auth.md describing agent credential paths

[jiashuoz]

Summary

• Adds web/public/auth.md, served at https://e2a.dev/auth.md, following the WorkOS auth.md convention. Agents (and their authors) can discover how to authenticate to e2a from a single LLM-readable file, without reverse-engineering the OAuth surface.
• The file is honest about today's state: it documents what's actually shipped (RFC 8414 AS metadata, RFC 7591 DCR, RFC 6750 Bearer + WWW-Authenticate challenges, the e2a_ / ate2a_ bearer dispatch) and lists exactly what's missing for full auth.md compliance (agent_auth block, RFC 9728 PRM, /agent/auth endpoint, JWKS for ID-JAG issuance) so we don't oversell.
• Lays out e2a's directional bet under "Agent identity" — leveraging verified agent email addresses to act as an OAuth / ID-JAG issuer for the rest of the agentic web. This is positioning, not shipped surface, and labeled as such.

What's in the file

• Two credential paths: MCP client via OAuth DCR (concrete 5-step recipe pointing at our real endpoints) and direct API consumer via API key (env / .env / ~/.e2a/config.json lookup order).
• A real POST /api/v1/send example with the correct JSON field names (body / html_body, not text) and an Idempotency-Key example.
• A dedicated HITL 202 pending_approval section so agents handle it correctly instead of retrying and double-queueing.
• Errors table covering 400 / 401 (first-use vs. previously-working, with split MCP / API-key guidance) / 403 / 409 / 422 / 429 — pulled from the OpenAPI annotations.
• Revocation paragraph covering both API keys and OAuth access tokens.

Test plan

• Pull this branch and run npm run dev from web/; confirm curl http://localhost:3000/auth.md returns the file with Content-Type: text/markdown (or text/plain — fine either way for the use case).
• After merge, confirm curl https://e2a.dev/auth.md returns the file once the static export deploys.
• Sanity-check the JSON field names in the send example match what POST /api/v1/send actually accepts (you can hit Mailpit locally via make docker-up + make run, or just spot-check against internal/outbound/sender.go — the JSON tags are the source of truth).
• Verify the OAuth discovery URL referenced in the file (https://e2a.dev/.well-known/oauth-authorization-server) returns the AS metadata in prod after deploy.

Not in scope (follow-ups)

• Adding RFC 9728 /.well-known/oauth-protected-resource and resource_metadata="..." to the 401 challenge (TODO already exists in internal/agent/api.go writeAuthError).
• Designing and implementing /agent/auth itself with the three flows (anonymous, identity_assertion + verified_email, identity_assertion + id-jag). The doc declares the direction; a separate design pass referencing the WorkOS reference implementation should precede the build.
• JWKS publication and ID-JAG issuance from e2a as an OAuth issuer.

🤖 Generated with Claude Code