claudeguide-engineer 1.14.8

package/.claude/skills/better-auth/references/advanced-features.md

@@ -0,0 +1,553 @@
+# Advanced Features
+
+Better Auth plugins extend functionality beyond basic authentication.
+
+## Two-Factor Authentication
+
+### Server Setup
+
+```ts
+import { betterAuth } from "better-auth";
+import { twoFactor } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    twoFactor({
+      issuer: "YourAppName", // TOTP issuer name
+      otpOptions: {
+        period: 30, // OTP validity period (seconds)
+        digits: 6, // OTP length
+      }
+    })
+  ]
+});
+```
+
+### Client Setup
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { twoFactorClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [
+    twoFactorClient({
+      twoFactorPage: "/two-factor", // Redirect to 2FA verification page
+      redirect: true // Auto-redirect if 2FA required
+    })
+  ]
+});
+```
+
+### Enable 2FA for User
+
+```ts
+// Enable TOTP
+const { data } = await authClient.twoFactor.enable({
+  password: "userPassword" // Verify user identity
+});
+
+// data contains QR code URI for authenticator app
+const qrCodeUri = data.totpURI;
+const backupCodes = data.backupCodes; // Save these securely
+```
+
+### Verify TOTP Code
+
+```ts
+await authClient.twoFactor.verifyTOTP({
+  code: "123456",
+  trustDevice: true // Skip 2FA on this device for 30 days
+});
+```
+
+### Disable 2FA
+
+```ts
+await authClient.twoFactor.disable({
+  password: "userPassword"
+});
+```
+
+### Backup Codes
+
+```ts
+// Generate new backup codes
+const { data } = await authClient.twoFactor.generateBackupCodes({
+  password: "userPassword"
+});
+
+// Use backup code instead of TOTP
+await authClient.twoFactor.verifyBackupCode({
+  code: "backup-code-123"
+});
+```
+
+## Passkeys (WebAuthn)
+
+### Server Setup
+
+```ts
+import { betterAuth } from "better-auth";
+import { passkey } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    passkey({
+      rpName: "YourApp", // Relying Party name
+      rpID: "yourdomain.com" // Your domain
+    })
+  ]
+});
+```
+
+### Client Setup
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { passkeyClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [passkeyClient()]
+});
+```
+
+### Register Passkey
+
+```ts
+// User must be authenticated first
+await authClient.passkey.register({
+  name: "My Laptop" // Optional: name for this passkey
+});
+```
+
+### Sign In with Passkey
+
+```ts
+await authClient.passkey.signIn();
+```
+
+### List User Passkeys
+
+```ts
+const { data } = await authClient.passkey.list();
+// data contains array of registered passkeys
+```
+
+### Delete Passkey
+
+```ts
+await authClient.passkey.delete({
+  id: "passkey-id"
+});
+```
+
+## Magic Link
+
+### Server Setup
+
+```ts
+import { betterAuth } from "better-auth";
+import { magicLink } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    magicLink({
+      sendMagicLink: async ({ email, url, token }) => {
+        await sendEmail({
+          to: email,
+          subject: "Sign in to YourApp",
+          html: `Click <a href="${url}">here</a> to sign in.`
+        });
+      },
+      expiresIn: 300, // Link expires in 5 minutes (seconds)
+    })
+  ]
+});
+```
+
+### Client Setup
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { magicLinkClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [magicLinkClient()]
+});
+```
+
+### Send Magic Link
+
+```ts
+await authClient.magicLink.sendMagicLink({
+  email: "user@example.com",
+  callbackURL: "/dashboard"
+});
+```
+
+### Verify Magic Link
+
+```ts
+// Called automatically when user clicks link
+// Token in URL query params handled by Better Auth
+await authClient.magicLink.verify({
+  token: "token-from-url"
+});
+```
+
+## Organizations (Multi-Tenancy)
+
+### Server Setup
+
+```ts
+import { betterAuth } from "better-auth";
+import { organization } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    organization({
+      allowUserToCreateOrganization: true,
+      organizationLimit: 5, // Max orgs per user
+      creatorRole: "owner" // Role for org creator
+    })
+  ]
+});
+```
+
+### Client Setup
+
+```ts
+import { createAuthClient } from "better-auth/client";
+import { organizationClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  plugins: [organizationClient()]
+});
+```
+
+### Create Organization
+
+```ts
+await authClient.organization.create({
+  name: "Acme Corp",
+  slug: "acme", // Unique slug
+  metadata: {
+    industry: "Technology"
+  }
+});
+```
+
+### Invite Members
+
+```ts
+await authClient.organization.inviteMember({
+  organizationId: "org-id",
+  email: "user@example.com",
+  role: "member", // owner, admin, member
+  message: "Join our team!" // Optional
+});
+```
+
+### Accept Invitation
+
+```ts
+await authClient.organization.acceptInvitation({
+  invitationId: "invitation-id"
+});
+```
+
+### List Organizations
+
+```ts
+const { data } = await authClient.organization.list();
+// Returns user's organizations
+```
+
+### Update Member Role
+
+```ts
+await authClient.organization.updateMemberRole({
+  organizationId: "org-id",
+  userId: "user-id",
+  role: "admin"
+});
+```
+
+### Remove Member
+
+```ts
+await authClient.organization.removeMember({
+  organizationId: "org-id",
+  userId: "user-id"
+});
+```
+
+### Delete Organization
+
+```ts
+await authClient.organization.delete({
+  organizationId: "org-id"
+});
+```
+
+## Session Management
+
+### Configure Session Expiration
+
+```ts
+export const auth = betterAuth({
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days (seconds)
+    updateAge: 60 * 60 * 24, // Update session every 24 hours
+    cookieCache: {
+      enabled: true,
+      maxAge: 5 * 60 // Cache for 5 minutes
+    }
+  }
+});
+```
+
+### Server-Side Session
+
+```ts
+// Next.js
+import { auth } from "@/lib/auth";
+import { headers } from "next/headers";
+
+const session = await auth.api.getSession({
+  headers: await headers()
+});
+
+if (!session) {
+  // Not authenticated
+}
+```
+
+### Client-Side Session
+
+```tsx
+// React
+import { authClient } from "@/lib/auth-client";
+
+function UserProfile() {
+  const { data: session, isPending, error } = authClient.useSession();
+
+  if (isPending) return <div>Loading...</div>;
+  if (error) return <div>Error</div>;
+  if (!session) return <div>Not logged in</div>;
+
+  return <div>Hello, {session.user.name}!</div>;
+}
+```
+
+### List Active Sessions
+
+```ts
+const { data: sessions } = await authClient.listSessions();
+// Returns all active sessions for current user
+```
+
+### Revoke Session
+
+```ts
+await authClient.revokeSession({
+  sessionId: "session-id"
+});
+```
+
+### Revoke All Sessions
+
+```ts
+await authClient.revokeAllSessions();
+```
+
+## Rate Limiting
+
+### Server Configuration
+
+```ts
+export const auth = betterAuth({
+  rateLimit: {
+    enabled: true,
+    window: 60, // Time window in seconds
+    max: 10, // Max requests per window
+    storage: "memory", // "memory" or "database"
+    customRules: {
+      "/api/auth/sign-in": {
+        window: 60,
+        max: 5 // Stricter limit for sign-in
+      },
+      "/api/auth/sign-up": {
+        window: 3600,
+        max: 3 // 3 signups per hour
+      }
+    }
+  }
+});
+```
+
+### Custom Rate Limiter
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  rateLimit: {
+    enabled: true,
+    customLimiter: async ({ request, limit }) => {
+      // Custom rate limiting logic
+      const ip = request.headers.get("x-forwarded-for");
+      const key = `ratelimit:${ip}`;
+
+      // Use Redis, etc.
+      const count = await redis.incr(key);
+      if (count === 1) {
+        await redis.expire(key, limit.window);
+      }
+
+      if (count > limit.max) {
+        throw new Error("Rate limit exceeded");
+      }
+    }
+  }
+});
+```
+
+## Anonymous Sessions
+
+Track users before they sign up.
+
+### Server Setup
+
+```ts
+import { betterAuth } from "better-auth";
+import { anonymous } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [anonymous()]
+});
+```
+
+### Client Usage
+
+```ts
+// Create anonymous session
+const { data } = await authClient.signIn.anonymous();
+
+// Convert to full account
+await authClient.signUp.email({
+  email: "user@example.com",
+  password: "password123",
+  linkAnonymousSession: true // Link anonymous data
+});
+```
+
+## Email OTP
+
+One-time password via email (passwordless).
+
+### Server Setup
+
+```ts
+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}`
+        });
+      },
+      expiresIn: 300, // 5 minutes
+      length: 6 // OTP length
+    })
+  ]
+});
+```
+
+### Client Usage
+
+```ts
+// Send OTP to email
+await authClient.emailOTP.sendOTP({
+  email: "user@example.com"
+});
+
+// Verify OTP
+await authClient.emailOTP.verifyOTP({
+  email: "user@example.com",
+  otp: "123456"
+});
+```
+
+## Phone Number Authentication
+
+Requires phone number plugin.
+
+### Server Setup
+
+```ts
+import { betterAuth } from "better-auth";
+import { phoneNumber } from "better-auth/plugins";
+
+export const auth = betterAuth({
+  plugins: [
+    phoneNumber({
+      sendOTP: async ({ phoneNumber, otp }) => {
+        // Use Twilio, AWS SNS, etc.
+        await sendSMS(phoneNumber, `Your code: ${otp}`);
+      }
+    })
+  ]
+});
+```
+
+### Client Usage
+
+```ts
+// Sign up with phone
+await authClient.signUp.phoneNumber({
+  phoneNumber: "+1234567890",
+  password: "password123"
+});
+
+// Send OTP
+await authClient.phoneNumber.sendOTP({
+  phoneNumber: "+1234567890"
+});
+
+// Verify OTP
+await authClient.phoneNumber.verifyOTP({
+  phoneNumber: "+1234567890",
+  otp: "123456"
+});
+```
+
+## Best Practices
+
+1. **2FA**: Offer 2FA as optional, make mandatory for admin users
+2. **Passkeys**: Implement as progressive enhancement (fallback to password)
+3. **Magic Links**: Set short expiration (5-15 minutes)
+4. **Organizations**: Implement RBAC for org permissions
+5. **Sessions**: Use short expiration for sensitive apps
+6. **Rate Limiting**: Enable in production, adjust limits based on usage
+7. **Anonymous Sessions**: Clean up old anonymous sessions periodically
+8. **Backup Codes**: Force users to save backup codes before enabling 2FA
+9. **Multi-Device**: Allow users to manage trusted devices
+10. **Audit Logs**: Track sensitive operations (role changes, 2FA changes)
+
+## Regenerate Schema After Plugins
+
+After adding any plugin:
+
+```bash
+npx @better-auth/cli generate
+npx @better-auth/cli migrate # if using Kysely
+```
+
+Or manually apply migrations for your ORM (Drizzle, Prisma).