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/plugins/authentication.md

View on GitHub
# better-auth Authentication Plugins

Complete guide for enhanced authentication methods: 2FA, Passkeys, Magic Links, Email OTP, and Anonymous Users.

---

## Two-Factor Authentication (2FA/TOTP)

### Installation

```bash
bun add better-auth
```

### Server Configuration

**`src/auth.ts`**:
```typescript
import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  // ... database config
  plugins: [
    twoFactor({
      issuer: "Your App Name",  // Shown in authenticator apps
      totpOptions: {
        digits: 6,
        period: 30,  // seconds
      },
    }),
  ],
});
```

### Client Configuration

```typescript
import { createAuthClient } from "better-auth/react";
import { twoFactorClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  baseURL: "http://localhost:3000",
  plugins: [twoFactorClient()],
});
```

### Enable 2FA Flow

```typescript
// Step 1: Generate TOTP secret and QR code
const { data } = await authClient.twoFactor.enable();
// data.totpURI - Use with QR code library
// data.backupCodes - Show to user ONCE

// Step 2: Verify setup with code from authenticator app
await authClient.twoFactor.verifyTotp({
  code: "123456",
});
```

### Login with 2FA

```typescript
// Step 1: Normal sign-in
const result = await authClient.signIn.email({
  email: "user@example.com",
  password: "password",
});

// Step 2: Check if 2FA is required
if (result.data?.twoFactorRedirect) {
  // Show 2FA input
  await authClient.twoFactor.verifyTotp({
    code: userEnteredCode,
  });
}
```

### Backup Codes

```typescript
// Generate new backup codes (invalidates old ones)
const { data } = await authClient.twoFactor.generateBackupCodes();
// data.backupCodes - Array of 10 codes

// Use backup code instead of TOTP
await authClient.twoFactor.verifyBackupCode({
  code: "XXXX-XXXX",
});
```

### Disable 2FA

```typescript
await authClient.twoFactor.disable({
  password: "current-password",  // Verify user identity
});
```

---

## Passkeys (WebAuthn)

### Installation

Passkey plugin is a separate package since v1.4.0:

```bash
bun add @better-auth/passkey
```

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { passkey } from "@better-auth/passkey";

export const auth = betterAuth({
  plugins: [
    passkey({
      rpID: "your-domain.com",
      rpName: "Your App",
      origin: "https://your-domain.com",
    }),
  ],
});
```

### Client Configuration

```typescript
import { createAuthClient } from "better-auth/react";
import { passkeyClient } from "@better-auth/passkey/client";

export const authClient = createAuthClient({
  plugins: [passkeyClient()],
});
```

### Register Passkey

```typescript
await authClient.passkey.addPasskey({
  name: "MacBook Pro Touch ID",
  authenticatorAttachment: "platform",  // or "cross-platform"
});
```

### Sign In with Passkey

```typescript
const result = await authClient.signIn.passkey({
  autoFill: true,  // Enable conditional UI
});
```

### Pre-Auth Registration (v1.6+)

Register passkeys before the user has a session — enables passkey-first onboarding:

```typescript
import { passkey } from "@better-auth/passkey";

export const auth = betterAuth({
  plugins: [
    passkey({
      registration: {
        requireSession: false,
        resolveUser: async ({ ctx, context }) => {
          // Validate context, then create or load user
          return { id: "user-id", name: "user@example.com" };
        },
        extensions: { credProps: true },
      },
    }),
  ],
});
```

Client:

```typescript
// Generate options with context
await auth.api.generatePasskeyRegistrationOptions({
  context: "signed-registration-token",
});

// Register with same context
await authClient.passkey.addPasskey({
  name: "Primary passkey",
  context: "signed-registration-token",
});
```

### WebAuthn Extensions (v1.6+)

Pass extensions on registration and authentication:

```typescript
const result = await authClient.passkey.addPasskey({
  name: "My Passkey",
  extensions: { credProps: true },
  returnWebAuthnResponse: true,
});
console.log(result.webauthn?.clientExtensionResults);
```

### List/Remove/Update Passkeys

```typescript
const { data: passkeys } = await authClient.passkey.listUserPasskeys();

await authClient.passkey.deletePasskey({ id: "passkey-id" });

await authClient.passkey.updatePasskey({ id: "passkey-id", name: "New Name" });
```

### Conditional UI (Autofill)

Add `webauthn` to input `autocomplete` attribute:

```html
<input type="text" autocomplete="username webauthn">
```

```typescript
useEffect(() => {
  if (
    !PublicKeyCredential.isConditionalMediationAvailable ||
    !PublicKeyCredential.isConditionalMediationAvailable()
  )
    return;
  authClient.signIn.passkey({ autoFill: true });
}, []);
```

---

## Magic Links

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { magicLink } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    magicLink({
      sendMagicLink: async ({ email, token, url }) => {
        // Send email with your provider (Resend, SendGrid, etc.)
        await sendEmail({
          to: email,
          subject: "Sign in to Your App",
          html: `<a href="${url}">Click to sign in</a>`,
        });
      },
      expiresIn: 60 * 10,  // 10 minutes
    }),
  ],
});
```

### Client Usage

```typescript
import { magicLinkClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
  plugins: [magicLinkClient()],
});

// Request magic link
await authClient.signIn.magicLink({
  email: "user@example.com",
  callbackURL: "/dashboard",  // Where to redirect after verification
});

// User clicks link in email → automatically signed in
```

### Verify Magic Link (Server-Side)

```typescript
// Handle callback route
app.get("/api/auth/magic-link/verify", async (req, res) => {
  const { token } = req.query;

  const session = await auth.api.verifyMagicLink({
    token: token as string,
  });

  // Redirect to app
  res.redirect("/dashboard");
});
```

---

## Email OTP

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { emailOTP } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    emailOTP({
      sendVerificationOTP: async ({ email, otp }) => {
        await sendEmail({
          to: email,
          subject: "Your verification code",
          text: `Your code is: ${otp}`,
        });
      },
      otpLength: 6,
      expiresIn: 60 * 5,  // 5 minutes
    }),
  ],
});
```

### Client Usage

```typescript
import { emailOTPClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
  plugins: [emailOTPClient()],
});

// Step 1: Request OTP
await authClient.signIn.emailOTP({
  email: "user@example.com",
});

// Step 2: Verify OTP
await authClient.signIn.emailOTP({
  email: "user@example.com",
  otp: "123456",
});
```

---

## Anonymous Users

### Server Configuration

```typescript
import { betterAuth } from "better-auth";
import { anonymous } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    anonymous({
      // Optional: Enable linking to real account later
      allowLinking: true,
    }),
  ],
});
```

### Client Usage

```typescript
import { anonymousClient } from "better-auth/client/plugins";

const authClient = createAuthClient({
  plugins: [anonymousClient()],
});

// Create anonymous session
const { data } = await authClient.signIn.anonymous();
// data.user.isAnonymous === true

// Later: Link to real account
await authClient.linkAccount.email({
  email: "user@example.com",
  password: "new-password",
});
// Anonymous user converted to regular user
```

### Check Anonymous Status

```typescript
const { data: session } = useSession();

if (session?.user.isAnonymous) {
  // Show "Create Account" prompt
}
```

---

## Combining Plugins

```typescript
import { betterAuth } from "better-auth";
import { passkey } from "@better-auth/passkey";
import {
  twoFactor,
  magicLink,
  emailOTP,
  anonymous
} from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    twoFactor({ issuer: "Your App" }),
    passkey({ rpID: "your-domain.com", rpName: "Your App", origin: "https://your-domain.com" }),
    magicLink({ sendMagicLink: async ({ email, url }) => { /* ... */ } }),
    emailOTP({ sendVerificationOTP: async ({ email, otp }) => { /* ... */ } }),
    anonymous({ allowLinking: true }),
  ],
});
```

---

## Common Issues

### 2FA: "Invalid code"
- Ensure device time is synced (NTP)
- Check TOTP period matches (default 30s)

### Passkeys: "Origin mismatch"
- `origin` in config must match exactly (https://domain.com, not https://domain.com/)
- `rpID` must be the domain without protocol

### Magic Link: "Token expired"
- Default expiry is 10 minutes
- Increase `expiresIn` if needed

### Anonymous: "Cannot link account"
- Ensure `allowLinking: true` in config
- User must be currently signed in as anonymous

---

## Official Resources

- Two-Factor: https://better-auth.com/docs/plugins/two-factor
- Passkeys: https://better-auth.com/docs/plugins/passkey
- Magic Link: https://better-auth.com/docs/plugins/magic-link
- Email OTP: https://better-auth.com/docs/plugins/email-otp
- Anonymous: https://better-auth.com/docs/plugins/anonymous
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