0025. Authentication with Better Auth: email codes, Google, and MCP OAuth
- Status: Superseded by 0040
- Date: 2026-11-08
Context
Section titled “Context”The dashboard needs sign-in, and MCP clients need OAuth. The same code must run on Cloudflare (Workers and D1) and in containers (Node and Postgres). Better Auth runs on both runtimes and has plugins for email one-time codes, social sign-in, and acting as an OAuth provider for MCP. The MCP authorization specification requires resource indicators (RFC 8707), protected resource metadata (RFC 9728), and client registration (dynamic client registration or client metadata documents).
Decision
Section titled “Decision”- Use Better Auth.
- Sign-in methods:
- Email one-time codes: stored hashed, valid 5 minutes, 3 attempts, rate limited per email and per IP.
- Google: an existing account is linked only when Google reports
email_verified.
- Dashboard sessions are cookies. Cookie-authenticated requests are accepted only with a JSON body and a matching
Originheader (CSRF protection). Routes authenticated by API key ignore cookies. - Managed service: anti-abuse checks at sign-up through the abuse-screening extension point.
- Self-hosted:
ALLOWED_EMAILSandADMIN_EMAILSallowlists, enforced when a user and when a session is created. A first-boot sign-in path works before mail is configured. - MCP OAuth uses Better Auth’s OAuth provider plugins. The grant model (one project per grant, scopes, scope ∩ role) is in ADR 0026.
- External identity providers and SSO can be added later.
Consequences
Section titled “Consequences”- This ADR becomes Accepted only after a spike passes on Workers with D1 and on Node with Postgres, and confirms that the OAuth plugin meets the MCP authorization specification: RFC 8707 resource indicators, RFC 9728 protected resource metadata, dynamic client registration or client metadata documents, and rate-limited registration.
- Better Auth routes, and the issuance of keys and grants, are covered by the isolation fixture (two workspaces; the first has two projects, ADR 0019).
- The earlier proposal to use
@cloudflare/workers-oauth-provideris dropped; one library covers both targets. - Sign-in codes are sent through
SystemMailer(ADR 0029).