secondsky/claude-skills / plugins/better-auth/skills/better-auth
better-auth
VerifiedSkill 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.
references/v1.4-features.md
View on GitHub# better-auth v1.4.x New Features
New features added in v1.4.4 through v1.4.8.
---
## Background Tasks (v1.4.8)
Defer non-critical actions like email sending to improve response times.
### Configuration
```typescript
import { betterAuth } from "better-auth";
export const auth = betterAuth({
// Global background tasks configuration
backgroundTasks: {
enabled: true,
// Queue implementation (default: in-memory)
queue: "memory", // or "redis", "custom"
},
// ...
});
```
### Redis Queue
```typescript
import { createRedisQueue } from "better-auth/queue";
backgroundTasks: {
enabled: true,
queue: createRedisQueue({
url: process.env.REDIS_URL!,
prefix: "auth-tasks:",
}),
},
```
### Deferred Email Sending
```typescript
import { betterAuth } from "better-auth";
export const auth = betterAuth({
backgroundTasks: { enabled: true },
emailAndPassword: {
enabled: true,
sendVerificationEmail: async ({ user, url }) => {
// This runs in background, not blocking the response
await sendEmail({
to: user.email,
subject: "Verify your email",
html: `<a href="${url}">Verify</a>`,
});
},
},
});
```
---
## New OAuth Providers
### Patreon (v1.4.8)
```typescript
import { betterAuth } from "better-auth";
export const auth = betterAuth({
socialProviders: {
patreon: {
clientId: process.env.PATREON_CLIENT_ID!,
clientSecret: process.env.PATREON_CLIENT_SECRET!,
// Scopes for patron data
scope: ["identity", "identity[email]", "campaigns", "campaigns.members"],
},
},
});
// Client usage
await authClient.signIn.social({ provider: "patreon" });
```
### Vercel (v1.4.3)
```typescript
socialProviders: {
vercel: {
clientId: process.env.VERCEL_CLIENT_ID!,
clientSecret: process.env.VERCEL_CLIENT_SECRET!,
// Team-specific access
teamId: process.env.VERCEL_TEAM_ID,
},
},
```
### Kick (v1.4.6)
```typescript
socialProviders: {
kick: {
clientId: process.env.KICK_CLIENT_ID!,
clientSecret: process.env.KICK_CLIENT_SECRET!,
// Refresh token support
refreshToken: true,
},
},
```
---
## OAuth 2.1 Provider (v1.5.0+)
The OAuth 2.1 Provider (`@better-auth/oauth-provider`) replaces the deprecated OIDC Provider plugin. Shipped in v1.5.0 with authorization_code, refresh_token, and client_credentials grants, OIDC support, JWKS, and MCP readiness.
See `references/v1.5-features.md` for full configuration details.
```typescript
import { oauthProvider } from "@better-auth/oauth-provider";
export const auth = betterAuth({
plugins: [
oauthProvider({
loginPage: "/sign-in",
consentPage: "/consent",
}),
],
});
```
---
## SAML/SSO Enhancements
### Clock Skew Tolerance (v1.4.7)
```typescript
import { sso } from "@better-auth/sso";
sso({
saml: {
// Allow clock drift between SP and IdP
clockSkew: 60 * 1000, // 60 seconds (default: 5 minutes)
},
}),
```
### InResponseTo Validation (v1.4.7, default ON in v1.6+)
```typescript
sso({
saml: {
// Validate SAML response matches request
enableInResponseToValidation: true,
},
}),
```
### OIDC Discovery for SSO (v1.4.7)
Better Auth automatically fetches OIDC discovery documents during provider registration. See `references/plugins/sso.md` for full details.
### Crypto Algorithm Validation (v1.4.8)
```typescript
sso({
saml: {
algorithms: {
// "warn" (default) | "reject" | "allow"
onDeprecated: "warn",
},
},
}),
```
---
## CLI Tool (v1.4.4, updated in v1.5.0)
The new `npx auth` CLI replaces `@better-auth/cli`.
### Commands
```bash
# Initialize better-auth in project (v1.5+)
npx auth init
# Generate auth schema
npx auth generate
# Run migrations
npx auth migrate
# Upgrade to latest version (v1.5+)
npx auth upgrade
# Generate with specific adapter (v1.5+)
npx auth generate --adapter drizzle
```
---
## Admin Role Permissions (v1.4.7)
Granular permissions for admin operations.
### Configuration
```typescript
import { admin } from "better-auth/plugins";
admin({
adminRoles: ["admin", "super-admin"],
// Granular permissions by role
permissions: {
admin: {
updateUser: ["name", "image"], // Can only update name/image
deleteUser: false, // Cannot delete
banUser: true,
},
"super-admin": {
updateUser: true, // Can update any field
deleteUser: true,
banUser: true,
},
},
}),
```
### Permission Check
```typescript
// Server-side
const canDelete = await auth.api.admin.hasPermission({
userId: session.user.id,
permission: "deleteUser",
});
```
---
## Domain Verification Helpers
### ctx.isTrustedDomain (v1.4.6)
```typescript
// In custom endpoints or middleware
app.get("/api/secure", async (c) => {
const ctx = auth.getContext(c);
// Check if request origin is trusted
if (!ctx.isTrustedDomain(c.req.headers.get("origin"))) {
return c.json({ error: "Untrusted origin" }, 403);
}
// Proceed with trusted request
});
```
### Automatic Provider Trust (v1.4.6)
```typescript
socialProviders: {
google: {
clientId: "...",
clientSecret: "...",
// Trust verified domains from Google
trustVerifiedDomains: true,
},
},
```
---
## Verification Table Extensions (v1.4.8)
Add custom fields to verification records.
### Configuration
```typescript
betterAuth({
// Add custom fields to verification table
additionalFields: {
verification: {
// Custom field for tracking verification source
source: {
type: "string",
required: false,
},
// Custom field for IP tracking
requestIp: {
type: "string",
required: false,
},
},
},
});
```
### Usage
```typescript
// When creating verification (internal)
await auth.api.createVerification({
identifier: email,
value: token,
expiresAt: new Date(Date.now() + 3600000),
// Custom fields
source: "password-reset",
requestIp: req.ip,
});
```
---
## GitHub PKCE Support (v1.4.2)
```typescript
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
// Enable PKCE for enhanced security
pkce: true,
},
},
```
---
## Trusted Proxy Headers (v1.4.3)
Properly infer base URL behind reverse proxies.
```typescript
betterAuth({
// Trust X-Forwarded-* headers from proxy
trustedProxyHeaders: true,
// Or specify trusted proxies
trustedProxies: ["10.0.0.0/8", "172.16.0.0/12"],
});
```
---
## Last Login Method (v1.4.6)
Track which method users last used to sign in.
### Server Configuration
```typescript
import { lastLoginMethod } from "better-auth/plugins";
betterAuth({
plugins: [lastLoginMethod()],
});
```
### Client Usage (Expo-Optimized)
```typescript
import { lastLoginMethodClient } from "better-auth/client/plugins";
const authClient = createAuthClient({
plugins: [lastLoginMethodClient()],
});
// Access in session
const { data: session } = useSession();
console.log(session?.user.lastLoginMethod);
// "email" | "google" | "github" | "passkey" | etc.
```
---
## Migration from v1.4.3
### Breaking Changes
None - all v1.4.x releases are backward compatible.
### Recommended Updates
1. **Enable Background Tasks** for email-heavy apps:
```typescript
backgroundTasks: { enabled: true }
```
2. **Add PKCE to GitHub** if not using:
```typescript
github: { pkce: true }
```
3. **Configure Clock Skew** for SAML if timing issues:
```typescript
saml: { clockSkew: 60 * 1000 }
```
4. **Use CLI** for configuration validation:
```bash
npx better-auth check
```
---
## Cloudflare Workers Compatibility
All v1.4.x features are compatible with Cloudflare Workers:
- **Background Tasks**: Use in-memory queue (Redis not available on Workers)
- **OAuth Providers**: All new providers work on edge
- **SAML/SSO**: Full support with clock skew handling
- **CLI**: For local development, not edge runtime
### Workers-Specific Configuration
```typescript
// wrangler.jsonc
{
"compatibility_flags": ["nodejs_compat"]
}
```
```typescript
// For background tasks on Workers
backgroundTasks: {
enabled: true,
queue: "memory", // Only option for Workers
// Consider using Cloudflare Queues for production
},
```
---
## Official Changelog
Full changelog: https://www.better-auth.com/changelogs
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |