better-auth

What this skill does

# Better Auth - Complete Authentication

TypeScript-first authentication library with 40+ OAuth providers and 20+ plugins.

## Agent Workflow (MANDATORY)

Before ANY implementation, use `TeamCreate` to spawn 3 agents:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing auth setup and patterns
2. **fuse-ai-pilot:research-expert** - Verify latest Better Auth docs via Context7/Exa
3. **mcp__context7__query-docs** - Check providers/plugins availability

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

## Overview

### When to Use

- Implementing authentication in TypeScript/JavaScript applications
- Need OAuth providers (Google, GitHub, Discord, Apple, Microsoft, etc.)
- Adding 2FA, magic links, passkeys, or phone authentication
- Enterprise SSO with SAML, SCIM provisioning, or organizations
- Integrating payments with Stripe or Polar subscriptions
- Web3 authentication with Sign-In with Ethereum (SIWE)
- Migrating from Auth.js, Clerk, Auth0, Supabase, or WorkOS

### Why Better Auth

| Feature | Benefit |
|---------|---------|
| Framework agnostic | Next.js, SvelteKit, Nuxt, Remix, Astro, Expo, NestJS |
| Plugin architecture | Add only the features you need (20+ plugins) |
| Full TypeScript | End-to-end type safety, inference included |
| Self-hosted | Your data stays on your infrastructure |
| Database flexible | Prisma, Drizzle, MongoDB, PostgreSQL, MySQL, SQLite |
| Enterprise ready | SSO, SCIM, organizations, audit logs |

---

## Coverage

### OAuth Providers (40+)

Google, GitHub, Discord, Apple, Microsoft, Slack, Spotify, Twitter/X, Facebook, LinkedIn, GitLab, Bitbucket, Dropbox, Twitch, Reddit, TikTok, and 25+ more documented in [providers/](references/providers/).

### Plugins (20+)

| Plugin | Purpose |
|--------|---------|
| 2FA | TOTP authenticator, backup codes |
| Magic Link | Passwordless email login |
| Passkey | WebAuthn biometric authentication |
| Organization | Multi-tenant, roles, invitations |
| SSO | Enterprise SAML/OIDC single sign-on |
| SCIM | Directory sync, user provisioning |
| Stripe | Subscription billing integration |
| API Key | Machine-to-machine authentication |
| JWT/Bearer | Token-based API authentication |

### Database Adapters

Prisma, Drizzle, MongoDB, raw SQL (PostgreSQL, MySQL, SQLite), and community adapters.

---

## SOLID Architecture (Next.js 16)

Components organized in `modules/auth/` following separation of concerns:

- **Services**: `betterAuth` configuration and initialization
- **Hooks**: `createAuthClient` for client-side auth state
- **API Route**: `app/api/auth/[...all]/route.ts` handler
- **Proxy**: `proxy.ts` for route protection (replaces middleware)

---

## Reference Guide

| Need | Reference |
|------|-----------|
| Initial setup | [installation.md](references/installation.md), [server-config.md](references/server-config.md) |
| Client usage | [client.md](references/client.md), [session.md](references/session.md) |
| OAuth providers | [providers/overview.md](references/providers/overview.md), individual provider docs |
| Add plugins | [plugins/overview.md](references/plugins/overview.md), individual plugin docs |
| Database setup | [adapters/prisma.md](references/adapters/prisma.md), [adapters/drizzle.md](references/adapters/drizzle.md) |
| Enterprise SSO | [plugins/sso.md](references/plugins/sso.md), [guides/saml-okta.md](references/guides/saml-okta.md) |
| Payments | [plugins/stripe.md](references/plugins/stripe.md), [plugins/polar.md](references/plugins/polar.md) |
| Migration | [guides/clerk-migration.md](references/guides/clerk-migration.md), other migration guides |
| Complete examples | [examples/](references/examples/) for full implementations |

---

## Best Practices

1. **Plugins on demand** - Only add plugins you actually need
2. **Type-safe client** - Use generated types from server config
3. **Session caching** - Enable session caching for performance
4. **Rate limiting** - Configure rate limits for auth endpoints
5. **Secure cookies** - Use secure, httpOnly, sameSite cookies
6. **Database indexes** - Add indexes on user lookup fields

---

## Concepts

Core concepts explained in [concepts/](references/concepts/):

- **Sessions** - Token management, refresh, revocation
- **Database** - Schema design, migrations, adapters
- **Plugins** - Extension system, composition
- **OAuth** - Provider configuration, callbacks
- **Security** - CSRF, rate limiting, password hashing
- **Cookies** - Session storage, cross-domain