Skip to content

secondsky/claude-skills / plugins/better-auth/skills/better-auth

better-auth

Verified

Skill for integrating Better Auth - comprehensive TypeScript authentication framework for Cloudflare D1, Next.js, Nuxt, and 15+ frameworks. Use when adding auth, encountering D1 adapter errors, or implementing OAuth/2FA/RBAC features.

FileKindSize
SKILL.mdskill md29.2 KB
assets/auth-flow-diagram.mdmarkdown24.0 KB
references/advanced-features.mdmarkdown14.7 KB
references/cloudflare-worker-drizzle.tsscript12.7 KB
references/cloudflare-worker-kysely.tsscript9.7 KB
references/configuration-guide.mdmarkdown10.7 KB
references/database-schema.tsscript10.8 KB
references/databases/mongodb.mdmarkdown5.3 KB
references/databases/mysql.mdmarkdown6.8 KB
references/databases/postgresql.mdmarkdown8.4 KB
references/error-catalog.mdmarkdown12.9 KB
references/framework-comparison.mdmarkdown8.2 KB
references/frameworks/api-frameworks.mdmarkdown9.2 KB
references/frameworks/expo-mobile.mdmarkdown8.7 KB
references/frameworks/nextjs.mdmarkdown5.4 KB
references/frameworks/nuxt.mdmarkdown6.0 KB
references/frameworks/remix.mdmarkdown6.1 KB
references/frameworks/sveltekit.mdmarkdown6.3 KB
references/integrations/electron.mdmarkdown8.2 KB
references/migration-guide-1.4.0.mdmarkdown23.2 KB
references/migration-guide-1.5.0.mdmarkdown6.3 KB
references/nextjs/README.mdmarkdown1.1 KB
references/nextjs/postgres-example.tsscript4.0 KB
references/plugins/api-tokens.mdmarkdown10.0 KB
references/plugins/authentication.mdmarkdown9.2 KB
references/plugins/enterprise.mdmarkdown9.1 KB
references/plugins/payments.mdmarkdown8.0 KB
references/plugins/sso.mdmarkdown9.4 KB
references/plugins/test-utils.mdmarkdown5.5 KB
references/react-client-hooks.tsxother12.8 KB
references/setup-guide.mdmarkdown8.9 KB
references/v1.4-features.mdmarkdown8.2 KB
references/v1.5-features.mdmarkdown11.0 KB
references/v1.6-features.mdmarkdown6.1 KB
scripts/generate-secret.shexecutablescript2.0 KB
scripts/setup-d1-drizzle.shexecutablescript10.2 KB
scripts/test-auth-health.shexecutablescript2.1 KB
scripts/validate-config.tsscript4.3 KB

assets/auth-flow-diagram.md

View on GitHub
# better-auth Authentication Flow Diagrams

Visual representations of common authentication flows using better-auth.

---

## 1. Email/Password Sign-Up Flow

```
┌─────────┐                 ┌─────────┐                 ┌──────────┐
│ Client  │                 │ Worker  │                 │    D1    │
└────┬────┘                 └────┬────┘                 └────┬─────┘
     │                           │                           │
     │  POST /api/auth/signup    │                           │
     │  { email, password }      │                           │
     ├──────────────────────────>│                           │
     │                           │  Hash password (bcrypt)   │
     │                           │                           │
     │                           │  INSERT INTO users        │
     │                           ├──────────────────────────>│
     │                           │                           │
     │                           │  Generate verification    │
     │                           │  token                    │
     │                           │                           │
     │                           │  INSERT INTO              │
     │                           │  verification_tokens      │
     │                           ├──────────────────────────>│
     │                           │                           │
     │                           │  Send verification email  │
     │                           │  (via email service)      │
     │                           │                           │
     │  { success: true }        │                           │
     │<──────────────────────────┤                           │
     │                           │                           │
     │                           │                           │
     │  User clicks email link   │                           │
     │                           │                           │
     │  GET /api/auth/verify?    │                           │
     │      token=xyz            │                           │
     ├──────────────────────────>│                           │
     │                           │  Verify token             │
     │                           ├──────────────────────────>│
     │                           │                           │
     │                           │  UPDATE users SET         │
     │                           │  email_verified = true    │
     │                           ├──────────────────────────>│
     │                           │                           │
     │  Redirect to dashboard    │                           │
     │<──────────────────────────┤                           │
     │                           │                           │
```

---

## 2. Social Sign-In Flow (Google OAuth)

```
┌─────────┐       ┌─────────┐       ┌──────────┐       ┌─────────┐
│ Client  │       │ Worker  │       │    D1    │       │ Google  │
└────┬────┘       └────┬────┘       └────┬─────┘       └────┬────┘
     │                 │                  │                  │
     │  Click "Sign    │                  │                  │
     │  in with        │                  │                  │
     │  Google"        │                  │                  │
     │                 │                  │                  │
     │  POST /api/     │                  │                  │
     │  auth/signin/   │                  │                  │
     │  google         │                  │                  │
     ├────────────────>│                  │                  │
     │                 │  Generate OAuth  │                  │
     │                 │  state + PKCE    │                  │
     │                 │                  │                  │
     │  Redirect to    │                  │                  │
     │  Google OAuth   │                  │                  │
     │<────────────────┤                  │                  │
     │                 │                  │                  │
     │                 │                  │                  │
     │  User authorizes on Google         │                  │
     ├───────────────────────────────────────────────────────>│
     │                 │                  │                  │
     │                 │                  │  User approves  │
     │<───────────────────────────────────────────────────────┤
     │                 │                  │                  │
     │  Redirect to    │                  │                  │
     │  callback with  │                  │                  │
     │  code           │                  │                  │
     │                 │                  │                  │
     │  GET /api/auth/ │                  │                  │
     │  callback/      │                  │                  │
     │  google?code=   │                  │                  │
     ├────────────────>│                  │                  │
     │                 │  Exchange code   │                  │
     │                 │  for tokens      │                  │
     │                 ├─────────────────────────────────────>│
     │                 │                  │                  │
     │                 │  { access_token, │                  │
     │                 │    id_token }    │                  │
     │                 │<─────────────────────────────────────┤
     │                 │                  │                  │
     │                 │  Fetch user info │                  │
     │                 ├─────────────────────────────────────>│
     │                 │                  │                  │
     │                 │  { email, name,  │                  │
     │                 │    picture }     │                  │
     │                 │<─────────────────────────────────────┤
     │                 │                  │                  │
     │                 │  Find or create  │                  │
     │                 │  user            │                  │
     │                 ├─────────────────>│                  │
     │                 │                  │                  │
     │                 │  Store account   │                  │
     │                 │  (provider data) │                  │
     │                 ├─────────────────>│                  │
     │                 │                  │                  │
     │                 │  Create session  │                  │
     │                 ├─────────────────>│                  │
     │                 │                  │                  │
     │  Set session    │                  │                  │
     │  cookie +       │                  │                  │
     │  redirect       │                  │                  │
     │<────────────────┤                  │                  │
     │                 │                  │                  │
```

---

## 3. Session Verification Flow

```
┌─────────┐              ┌─────────┐              ┌──────────┐
│ Client  │              │ Worker  │              │    KV    │
└────┬────┘              └────┬────┘              └────┬─────┘
     │                        │                        │
     │  GET /api/protected    │                        │
     │  Cookie: session=xyz   │                        │
     ├───────────────────────>│                        │
     │                        │  Extract session ID    │
     │                        │  from cookie           │
     │                        │                        │
     │                        │  GET session from KV   │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  { userId, expiresAt } │
     │                        │<───────────────────────┤
     │                        │                        │
     │                        │  Check expiration      │
     │                        │                        │
     │  If valid:             │                        │
     │  { data: ... }         │                        │
     │<───────────────────────┤                        │
     │                        │                        │
     │  If invalid:           │                        │
     │  401 Unauthorized      │                        │
     │<───────────────────────┤                        │
     │                        │                        │
```

---

## 4. Password Reset Flow

```
┌─────────┐              ┌─────────┐              ┌──────────┐
│ Client  │              │ Worker  │              │    D1    │
└────┬────┘              └────┬────┘              └────┬─────┘
     │                        │                        │
     │  POST /api/auth/       │                        │
     │  forgot-password       │                        │
     │  { email }             │                        │
     ├───────────────────────>│                        │
     │                        │  Find user by email    │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  Generate reset token  │
     │                        │                        │
     │                        │  INSERT INTO           │
     │                        │  verification_tokens   │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  Send reset email      │
     │                        │                        │
     │  { success: true }     │                        │
     │<───────────────────────┤                        │
     │                        │                        │
     │                        │                        │
     │  User clicks email     │                        │
     │  link                  │                        │
     │                        │                        │
     │  GET /reset-password?  │                        │
     │      token=xyz         │                        │
     ├───────────────────────>│                        │
     │                        │  Verify token          │
     │                        ├───────────────────────>│
     │                        │                        │
     │  Show reset form       │                        │
     │<───────────────────────┤                        │
     │                        │                        │
     │  POST /api/auth/       │                        │
     │  reset-password        │                        │
     │  { token, password }   │                        │
     ├───────────────────────>│                        │
     │                        │  Hash new password     │
     │                        │                        │
     │                        │  UPDATE users          │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  DELETE token          │
     │                        ├───────────────────────>│
     │                        │                        │
     │  Redirect to login     │                        │
     │<───────────────────────┤                        │
     │                        │                        │
```

---

## 5. Two-Factor Authentication (2FA) Flow

```
┌─────────┐              ┌─────────┐              ┌──────────┐
│ Client  │              │ Worker  │              │    D1    │
└────┬────┘              └────┬────┘              └────┬─────┘
     │                        │                        │
     │  POST /api/auth/       │                        │
     │  signin                │                        │
     │  { email, password }   │                        │
     ├───────────────────────>│                        │
     │                        │  Verify credentials    │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  Check if 2FA enabled  │
     │                        ├───────────────────────>│
     │                        │                        │
     │  { requires2FA: true } │                        │
     │<───────────────────────┤                        │
     │                        │                        │
     │  Show 2FA input        │                        │
     │                        │                        │
     │  POST /api/auth/       │                        │
     │  verify-2fa            │                        │
     │  { code: "123456" }    │                        │
     ├───────────────────────>│                        │
     │                        │  Get 2FA secret        │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  Verify TOTP code      │
     │                        │                        │
     │  If valid:             │                        │
     │  Create session        │                        │
     │  + redirect            │                        │
     │<───────────────────────┤                        │
     │                        │                        │
```

---

## 6. Organization/Team Flow

```
┌─────────┐              ┌─────────┐              ┌──────────┐
│ Client  │              │ Worker  │              │    D1    │
└────┬────┘              └────┬────┘              └────┬─────┘
     │                        │                        │
     │  POST /api/org/create  │                        │
     │  { name, slug }        │                        │
     ├───────────────────────>│                        │
     │                        │  Verify session        │
     │                        │                        │
     │                        │  INSERT INTO orgs      │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  INSERT INTO           │
     │                        │  org_members           │
     │                        │  (user as owner)       │
     │                        ├───────────────────────>│
     │                        │                        │
     │  { org: { ... } }      │                        │
     │<───────────────────────┤                        │
     │                        │                        │
     │                        │                        │
     │  POST /api/org/invite  │                        │
     │  { orgId, email,       │                        │
     │    role }              │                        │
     ├───────────────────────>│                        │
     │                        │  Check permissions     │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  Generate invite token │
     │                        │                        │
     │                        │  INSERT INTO           │
     │                        │  org_invitations       │
     │                        ├───────────────────────>│
     │                        │                        │
     │                        │  Send invite email     │
     │                        │                        │
     │  { success: true }     │                        │
     │<───────────────────────┤                        │
     │                        │                        │
```

---

## Database Schema Overview

```
┌──────────────────────┐
│       users          │
├──────────────────────┤
│ id (PK)              │
│ email (UNIQUE)       │
│ email_verified       │
│ name                 │
│ image                │
│ role                 │
│ created_at           │
│ updated_at           │
└──────────┬───────────┘
           │
           │ 1:N
           │
┌──────────┴───────────┐        ┌──────────────────────┐
│     sessions         │        │      accounts        │
├──────────────────────┤        ├──────────────────────┤
│ id (PK)              │        │ id (PK)              │
│ user_id (FK)         │◄───────┤ user_id (FK)         │
│ expires_at           │        │ provider             │
│ ip_address           │        │ provider_account_id  │
│ user_agent           │        │ access_token         │
│ created_at           │        │ refresh_token        │
└──────────────────────┘        │ expires_at           │
                                │ created_at           │
                                └──────────────────────┘

┌──────────────────────┐
│  verification_tokens │
├──────────────────────┤
│ identifier           │
│ token                │
│ expires              │
│ created_at           │
└──────────────────────┘

┌──────────────────────┐        ┌──────────────────────┐
│   organizations      │        │ organization_members │
├──────────────────────┤        ├──────────────────────┤
│ id (PK)              │        │ id (PK)              │
│ name                 │        │ organization_id (FK) │◄──┐
│ slug (UNIQUE)        │◄───────┤ user_id (FK)         │   │
│ logo                 │        │ role                 │   │
│ created_at           │        │ created_at           │   │
│ updated_at           │        └──────────────────────┘   │
└──────────────────────┘                                    │
                                                            │
┌──────────────────────┐                                    │
│organization_invites  │                                    │
├──────────────────────┤                                    │
│ id (PK)              │                                    │
│ organization_id (FK) │────────────────────────────────────┘
│ email                │
│ role                 │
│ invited_by (FK)      │
│ token                │
│ expires_at           │
│ created_at           │
└──────────────────────┘
```

---

These diagrams illustrate the complete authentication flows supported by better-auth. Use them as reference when implementing auth in your application.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall