oneie/one/things/plans/better-auth-available-features.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: Better Auth Available Features
dimension: things
category: plans
tags: agent, ai, artificial-intelligence, auth
related_dimensions: groups, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the plans category.
  Location: one/things/plans/better-auth-available-features.md
  Purpose: Documents better auth convex component - available features
  Related dimensions: groups, knowledge, people
  For AI agents: Read this to understand better auth available features.
---

# Better Auth Convex Component - Available Features

## ✅ Successfully Installed and Generated

**Status:** Better Auth Convex component is now active and ready to use!

## 📊 Available Database Models

The Better Auth component provides the following data models (automatically managed):

### Core Authentication

1. **`user`** - User accounts
   - email, emailVerified
   - name, username, displayUsername
   - image, phoneNumber, phoneNumberVerified
   - twoFactorEnabled, isAnonymous
   - createdAt, updatedAt

2. **`session`** - User sessions
   - token, userId
   - expiresAt
   - ipAddress, userAgent
   - createdAt, updatedAt

3. **`account`** - OAuth provider accounts
   - providerId, accountId, userId
   - accessToken, accessTokenExpiresAt
   - refreshToken, refreshTokenExpiresAt
   - idToken, password, scope
   - createdAt, updatedAt

4. **`verification`** - Email/phone verification codes
   - identifier, value
   - expiresAt
   - createdAt, updatedAt

### Security Features

5. **`twoFactor`** - TOTP 2FA
   - secret, backupCodes
   - userId

6. **`passkey`** - WebAuthn passkeys
   - (Full passkey support)

7. **`rateLimit`** / **`ratelimit`** - Rate limiting
   - Built-in protection against brute force

### OAuth & SSO

8. **`oauthApplication`** - OAuth apps
9. **`oauthConsent`** - OAuth user consent
10. **`oauthAccessToken`** - OAuth tokens
11. **`ssoProvider`** - Enterprise SSO

### Team/Organization Features

12. **`organization`** - Multi-tenant orgs
13. **`team`** - Team management
14. **`member`** / **`teamMember`** - Team membership
15. **`invitation`** - Team invitations

### Advanced Features

16. **`subscription`** - Subscription management (Stripe integration ready)
17. **`walletAddress`** - Web3 wallet authentication
18. **`jwks`** - JWT key storage

## 🎯 What This Means

### Immediately Available Features

You can now use Better Auth's built-in functionality for:

✅ **Email/Password Authentication**

- Automatic Argon2 password hashing
- Email verification
- Password reset

✅ **OAuth Social Login**

- GitHub, Google, Discord, etc.
- Automatic account linking
- Token management

✅ **Two-Factor Authentication**

- TOTP (Google Authenticator, Authy)
- Backup codes
- SMS 2FA

✅ **Passkeys (WebAuthn)**

- Passwordless authentication
- Biometric login
- Cross-device sync

✅ **Session Management**

- Automatic session creation
- Token refresh
- Multi-device sessions

✅ **Rate Limiting**

- Built-in brute force protection
- Configurable limits

✅ **Team/Organization Features**

- Multi-tenant support
- Team invitations
- Role-based access

✅ **Subscription Management**

- Stripe integration ready
- Webhook handling

✅ **Web3 Authentication**

- Wallet address linking
- Crypto authentication

## 🚀 Migration Path

### Current State

- Using custom Convex mutations in `convex/auth.ts`
- Better Auth component available but not used

### Next Steps

1. **Replace Custom Auth with Better Auth Functions**

   ```typescript
   // Instead of custom mutations:
   import { components } from "./_generated/api";

   // Use Better Auth adapter:
   components.betterAuth.adapter.create({
     model: "user",
     data: { email, name, ... }
   });
   ```

2. **Set Up Better Auth HTTP Routes**

   ```typescript
   // convex/http.ts
   import { httpRouter } from "convex/server";
   import { authComponent } from "@convex-dev/better-auth/convex";

   const http = httpRouter();
   authComponent.registerRoutes(http);
   export default http;
   ```

3. **Configure Better Auth Instance**
   Create `src/lib/auth.ts`:

   ```typescript
   import { betterAuth } from "better-auth";
   import { convexAdapter } from "@convex-dev/better-auth";

   export const auth = betterAuth({
     database: convexAdapter(),
     emailAndPassword: { enabled: true },
     socialProviders: {
       github: { clientId: "...", clientSecret: "..." },
       google: { clientId: "...", clientSecret: "..." },
     },
   });
   ```

4. **Enable Plugins**

   ```typescript
   import { twoFactor } from "better-auth/plugins/two-factor";
   import { passkey } from "better-auth/plugins/passkey";
   import { magicLink } from "better-auth/plugins/magic-link";

   export const auth = betterAuth({
     // ... config
     plugins: [twoFactor(), passkey(), magicLink()],
   });
   ```

5. **Update UI Components**
   Replace custom API calls with Better Auth client:

   ```typescript
   // Instead of calling /api/auth/sign-in
   await authClient.signIn.email({ email, password });

   // OAuth
   await authClient.signIn.social({ provider: "github" });

   // Passkey
   await authClient.signIn.passkey();
   ```

## 📖 Benefits of Migration

### Security Improvements

- ✅ Argon2 password hashing (vs current SHA-256)
- ✅ Built-in rate limiting
- ✅ CSRF protection
- ✅ Email verification
- ✅ Session rotation

### Developer Experience

- ✅ Type-safe API
- ✅ Automatic database schema
- ✅ Built-in session management
- ✅ Plugin ecosystem
- ✅ Less code to maintain

### Feature Velocity

- ✅ OAuth in minutes (vs hours of custom code)
- ✅ 2FA with one plugin
- ✅ Passkeys with one plugin
- ✅ Magic links with one plugin
- ✅ Stripe subscriptions ready

## 🎯 Estimated Migration Time

- **Basic migration** (email/password): 2-4 hours
- **Add OAuth** (GitHub, Google): 1-2 hours
- **Add 2FA**: 1 hour
- **Add passkeys**: 1 hour
- **Add magic links**: 1 hour

**Total:** ~1 day to have feature-complete auth system

Compare to building from scratch:

- Custom OAuth: 8-16 hours
- Custom 2FA: 6-12 hours
- Custom passkeys: 12-20 hours
- **Total saved:** 26-48 hours of development time

## 🚦 Status

- ✅ Better Auth Convex component installed
- ✅ Types generated
- ✅ Models available
- ⏳ Waiting for migration from custom auth
- ⏳ HTTP routes setup
- ⏳ Better Auth instance configuration