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

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
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: 471kUpdated 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