giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-typescript/skills/better-auth
better-auth
UnverifiedProvides Better Auth integration patterns for NestJS backend and Next.js frontend with Drizzle ORM and PostgreSQL. Use when setting up Better Auth with NestJS backend, integrating Next.js App Router frontend, configuring Drizzle ORM schema, implementing social login (GitHub, Google), adding plugins (2FA, Organization, SSO, Magic Link, Passkey), implementing email/password authentication with session management, or creating protected routes and middleware.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.3 KB |
| assets/env.example | other | 1.8 KB |
| assets/nestjs/auth.controller.ts | script | 1.6 KB |
| assets/nestjs/auth.guard.ts | script | 1.5 KB |
| assets/nestjs/auth.module.ts | script | 479 B |
| assets/nestjs/auth.schema.ts | script | 2.8 KB |
| assets/nestjs/auth.service.ts | script | 1.5 KB |
| assets/nestjs/database.module.ts | script | 220 B |
| assets/nestjs/database.service.ts | script | 536 B |
| assets/nextjs/auth-client.ts | script | 462 B |
| assets/nextjs/auth-route.ts | script | 143 B |
| assets/nextjs/dashboard-page.tsx | other | 2.2 KB |
| assets/nextjs/middleware.ts | script | 388 B |
| assets/nextjs/sign-in-page.tsx | other | 6.3 KB |
| assets/nextjs/use-session.ts | script | 780 B |
| references/best-practices.md | markdown | 4.4 KB |
| references/examples.md | markdown | 7.8 KB |
| references/mfa-2fa.md | markdown | 7.6 KB |
| references/nestjs-setup.md | markdown | 9.6 KB |
| references/nextjs-setup.md | markdown | 12.0 KB |
| references/passkey.md | markdown | 10.1 KB |
| references/patterns.md | markdown | 2.8 KB |
| references/plugins.md | markdown | 9.4 KB |
| references/schema.md | markdown | 9.1 KB |
| references/social-providers.md | markdown | 9.1 KB |
references/mfa-2fa.md
View on GitHub# Better Auth MFA/2FA Guide
## Overview
Better Auth provides comprehensive Multi-Factor Authentication (MFA) support through the `twoFactor` plugin. This includes TOTP-based authentication, backup codes for recovery, and trusted device management.
## Installation
```bash
npm install better-auth
```
The twoFactor plugin is included in the main better-auth package.
## Server Configuration
### Basic Setup
```typescript
import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
export const auth = betterAuth({
appName: "My App",
plugins: [
twoFactor({
issuer: "My App", // Displayed in authenticator apps
otpOptions: {
async sendOTP({ user, otp }, ctx) {
// Required: Send OTP to user via email, SMS, etc.
await sendEmail({
to: user.email,
subject: 'Your verification code',
body: `Your code is: ${otp}`
});
}
}
})
]
});
```
### Configuration Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `issuer` | string | No | App name displayed in authenticator apps (default: "Better Auth") |
| `otpOptions.sendOTP` | function | Yes | Async function to send OTP to user |
| `otpOptions.digits` | number | No | Number of OTP digits (default: 6) |
| `otpOptions.period` | number | No | OTP validity period in seconds (default: 30) |
## Client-Side Implementation
### Enable 2FA
```typescript
import { authClient } from "@/lib/auth/client";
// Enable 2FA for current user
const enable2FA = async (password: string) => {
const { data, error } = await authClient.twoFactor.enable({
password
});
if (data) {
// Display TOTP URI as QR code
const qrCodeUrl = data.totpURI;
// Example: otpauth://totp/MyApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=MyApp
// Show backup codes (single-use recovery codes)
console.log('Save these backup codes securely:');
data.backupCodes.forEach((code: string) => {
console.log(code);
});
}
};
```
**Response:**
- `totpURI`: URI for QR code generation
- `backupCodes`: Array of single-use recovery codes
### Verify TOTP
```typescript
const verifyTOTP = async (code: string, trustDevice: boolean = true) => {
const { data, error } = await authClient.twoFactor.verifyTotp({
code,
trustDevice // Trust device for 30 days
});
if (data) {
// 2FA verified, user is authenticated
router.push('/dashboard');
}
};
```
### Verify with OTP (Email/SMS)
```typescript
const verifyOTP = async (code: string) => {
const { data, error } = await authClient.twoFactor.verifyOtp({
code,
trustDevice: true
});
if (data) {
router.push('/dashboard');
}
};
```
### Use Backup Code
```typescript
const recoverWithBackupCode = async (code: string) => {
const { data, error } = await authClient.twoFactor.verifyBackupCode({
code
});
if (data) {
// User can disable 2FA or set up new authenticator
router.push('/settings/2fa');
}
};
```
### Get TOTP URI
```typescript
const getTOTPUri = async (password: string) => {
const { data, error } = await authClient.twoFactor.getTotpUri({
password
});
if (data) {
// Display QR code from data.totpURI
displayQRCode(data.totpURI);
}
};
```
### Disable 2FA
```typescript
const disable2FA = async (password: string) => {
const { data, error } = await authClient.twoFactor.disable({
password
});
if (data) {
// 2FA disabled
}
};
```
## Trusted Devices
### How It Works
- Pass `trustDevice: true` when verifying 2FA
- Device is trusted for **30 days**
- Trust period refreshes on each successful sign-in
- Device-specific (not user-wide)
### Implementation
```typescript
const signInWith2FA = async (code: string) => {
const { data, error } = await authClient.twoFactor.verifyTotp({
code,
trustDevice: true // Device won't require 2FA for 30 days
});
if (data) {
// User authenticated, device is now trusted
}
};
```
### Applicable Endpoints
- `verifyTotp` - TOTP code verification
- `verifyOtp` - OTP (email/SMS) verification
- `verifyBackupCode` - Backup code verification
## API Endpoints
### POST /two-factor/enable
Enable 2FA for current user.
**Body:**
```json
{
"password": "user-password",
"issuer": "My App" // Optional
}
```
**Response:**
```json
{
"totpURI": "otpauth://totp/...",
"backupCodes": ["CODE1", "CODE2", "CODE3", "CODE4", "CODE5"]
}
```
### POST /two-factor/verify-totp
Verify TOTP code.
**Body:**
```json
{
"code": "123456",
"trustDevice": true
}
```
### POST /two-factor/verify-otp
Verify OTP sent via email/SMS.
**Body:**
```json
{
"code": "123456",
"trustDevice": true
}
```
### POST /two-factor/verify-backup-code
Verify single-use backup code.
**Body:**
```json
{
"code": "BACKUP-CODE"
}
```
### POST /two-factor/disable
Disable 2FA for current user.
**Body:**
```json
{
"password": "user-password"
}
```
### POST /two-factor/get-totp-uri
Get TOTP URI for reconfiguring authenticator.
**Body:**
```json
{
"password": "user-password"
}
```
## Security Best Practices
1. **Backup Codes**
- Display immediately after enabling 2FA
- Store in secure location (password manager)
- Cannot be retrieved later
2. **OTP Delivery**
- Use secure channels (HTTPS)
- Implement rate limiting
- Set short expiration times
3. **TOTP Configuration**
- Use 6 digits (standard)
- 30-second period (standard)
- Allow ±1 period drift for clock skew
4. **Trusted Devices**
- Clear trust on password change
- Allow users to view/revoke trusted devices
- Consider shorter trust period for sensitive apps
## React Component Example
```tsx
'use client';
import { useState } from 'react';
import { authClient } from '@/lib/auth/client';
export function TwoFactorSetup() {
const [step, setStep] = useState<'password' | 'qr' | 'backup'>('password');
const [password, setPassword] = useState('');
const [qrCode, setQrCode] = useState('');
const [backupCodes, setBackupCodes] = useState<string[]>([]);
const handleEnable = async () => {
const { data, error } = await authClient.twoFactor.enable({ password });
if (data) {
setQrCode(data.totpURI);
setBackupCodes(data.backupCodes);
setStep('qr');
}
};
return (
<div>
{step === 'password' && (
<div>
<input
type="password"
value={password}
onChange={(e) => setPassword(e.target.value)}
placeholder="Enter password"
/>
<button onClick={handleEnable}>Enable 2FA</button>
</div>
)}
{step === 'qr' && (
<div>
<img src={`/api/qr?data=${encodeURIComponent(qrCode)}`} alt="Scan with authenticator" />
<button onClick={() => setStep('backup')}>I've scanned the code</button>
</div>
)}
{step === 'backup' && (
<div>
<h3>Save these backup codes securely:</h3>
<ul>
{backupCodes.map((code) => (
<li key={code}>{code}</li>
))}
</ul>
<p>These codes can be used to recover your account if you lose access to your authenticator.</p>
</div>
)}
</div>
);
}
```
## Troubleshooting
### "Invalid TOTP code"
- Check device time synchronization
- Ensure authenticator app uses correct time
- Try regenerating TOTP URI
### "Backup code already used"
- Each backup code is single-use
- Use a different backup code
- Disable and re-enable 2FA to generate new codes
### "Device not trusted"
- `trustDevice` must be `true` during verification
- Check browser cookie settings
- Clear cookies and re-authenticate
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |