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/cloudflare-worker-drizzle.ts

View on GitHub
/**
 * Complete Cloudflare Worker with better-auth + Drizzle ORM
 *
 * This example demonstrates:
 * - D1 database with Drizzle ORM adapter
 * - Email/password authentication
 * - Google and GitHub OAuth
 * - Protected routes with session verification
 * - CORS configuration for SPA
 * - KV storage for sessions (strong consistency)
 * - Rate limiting with KV
 *
 * ⚠️ CRITICAL: better-auth requires Drizzle ORM or Kysely for D1
 * There is NO direct d1Adapter()!
 */

import { Hono } from "hono";
import { cors } from "hono/cors";
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle, type DrizzleD1Database } from "drizzle-orm/d1";
import { rateLimit } from "better-auth/plugins";
import * as schema from "../db/schema"; // Your Drizzle schema

// ═══════════════════════════════════════════════════════════════
// Environment bindings
// ═══════════════════════════════════════════════════════════════
type Env = {
  DB: D1Database;
  SESSIONS_KV: KVNamespace;
  RATE_LIMIT_KV: KVNamespace;
  BETTER_AUTH_SECRET: string;
  BETTER_AUTH_URL: string;
  GOOGLE_CLIENT_ID: string;
  GOOGLE_CLIENT_SECRET: string;
  GITHUB_CLIENT_ID: string;
  GITHUB_CLIENT_SECRET: string;
  FRONTEND_URL: string;
};

// Database type
export type Database = DrizzleD1Database<typeof schema>;

const app = new Hono<{ Bindings: Env }>();

// ═══════════════════════════════════════════════════════════════
// CORS configuration for SPA
// ═══════════════════════════════════════════════════════════════
app.use("/api/*", async (c, next) => {
  const corsMiddleware = cors({
    origin: [c.env.FRONTEND_URL, "http://localhost:3000"],
    credentials: true,
    allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allowHeaders: ["Content-Type", "Authorization"],
  });
  return corsMiddleware(c, next);
});

// ═══════════════════════════════════════════════════════════════
// Helper: Initialize Drizzle database
// ═══════════════════════════════════════════════════════════════
function createDatabase(d1: D1Database): Database {
  return drizzle(d1, { schema });
}

// ═══════════════════════════════════════════════════════════════
// Helper: Initialize auth (per-request to access env)
// ═══════════════════════════════════════════════════════════════
function createAuth(db: Database, env: Env) {
  return betterAuth({
    // Base URL for OAuth callbacks
    baseURL: env.BETTER_AUTH_URL,

    // Secret for signing tokens
    secret: env.BETTER_AUTH_SECRET,

    // ⚠️ CRITICAL: Use Drizzle adapter with SQLite provider
    // There is NO direct d1Adapter()!
    database: drizzleAdapter(db, {
      provider: "sqlite",
    }),

    // Email/password authentication
    emailAndPassword: {
      enabled: true,
      requireEmailVerification: true,
      sendVerificationEmail: async ({ user, url, token }) => {
        // TODO: Implement email sending (Resend, SendGrid, or Cloudflare Email Routing).
        // Pass `url` to your email provider so the user can click through.
        // ❌ NEVER log `url` or `token` — both are single-use secrets, and
        //    wrangler tail / Logpush persist stdout. Redacted stub only:
        console.log(`Verification email sent to ${user.email.substring(0, 2)}***`);
      },
    },

    // Social providers
    socialProviders: {
      google: {
        clientId: env.GOOGLE_CLIENT_ID,
        clientSecret: env.GOOGLE_CLIENT_SECRET,
        scope: ["openid", "email", "profile"],
      },
      github: {
        clientId: env.GITHUB_CLIENT_ID,
        clientSecret: env.GITHUB_CLIENT_SECRET,
        scope: ["user:email", "read:user"],
      },
    },

    // Session configuration
    session: {
      expiresIn: 60 * 60 * 24 * 7, // 7 days
      updateAge: 60 * 60 * 24, // Update every 24 hours

      // Use KV for sessions (strong consistency vs D1 eventual consistency)
      storage: {
        get: async (sessionId) => {
          const session = await env.SESSIONS_KV.get(sessionId);
          return session ? JSON.parse(session) : null;
        },
        set: async (sessionId, session, ttl) => {
          await env.SESSIONS_KV.put(sessionId, JSON.stringify(session), {
            expirationTtl: ttl,
          });
        },
        delete: async (sessionId) => {
          await env.SESSIONS_KV.delete(sessionId);
        },
      },
    },

    // Plugins
    plugins: [
      rateLimit({
        window: 60, // 60 seconds
        max: 10, // 10 requests per window
        storage: {
          get: async (key) => {
            return await env.RATE_LIMIT_KV.get(key);
          },
          set: async (key, value, ttl) => {
            await env.RATE_LIMIT_KV.put(key, value, {
              expirationTtl: ttl,
            });
          },
        },
      }),
    ],
  });
}

// ═══════════════════════════════════════════════════════════════
// Auth routes - handle all better-auth endpoints
// ═══════════════════════════════════════════════════════════════
app.all("/api/auth/*", async (c) => {
  const db = createDatabase(c.env.DB);
  const auth = createAuth(db, c.env);
  return auth.handler(c.req.raw);
});

// ═══════════════════════════════════════════════════════════════
// Example: Protected API route
// ═══════════════════════════════════════════════════════════════
app.get("/api/protected", async (c) => {
  const db = createDatabase(c.env.DB);
  const auth = createAuth(db, c.env);

  // Verify session
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  return c.json({
    message: "Protected data",
    user: {
      id: session.user.id,
      email: session.user.email,
      name: session.user.name,
    },
  });
});

// ═══════════════════════════════════════════════════════════════
// Example: User profile endpoint
// ═══════════════════════════════════════════════════════════════
app.get("/api/user/profile", async (c) => {
  const db = createDatabase(c.env.DB);
  const auth = createAuth(db, c.env);

  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  // Fetch additional user data from D1
  const userProfile = await db.query.user.findFirst({
    where: (user, { eq }) => eq(user.id, session.user.id),
  });

  return c.json(userProfile);
});

// ═══════════════════════════════════════════════════════════════
// Example: Update user profile
// ═══════════════════════════════════════════════════════════════
app.patch("/api/user/profile", async (c) => {
  const db = createDatabase(c.env.DB);
  const auth = createAuth(db, c.env);

  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  const { name } = await c.req.json();

  // Update user in D1 using Drizzle
  await db
    .update(schema.user)
    .set({ name, updatedAt: new Date() })
    .where(eq(schema.user.id, session.user.id));

  return c.json({ success: true });
});

// ═══════════════════════════════════════════════════════════════
// Example: Admin-only endpoint
// ═══════════════════════════════════════════════════════════════
app.get("/api/admin/users", async (c) => {
  const db = createDatabase(c.env.DB);
  const auth = createAuth(db, c.env);

  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  // Check admin role (you'd store this in users table)
  const user = await db.query.user.findFirst({
    where: (user, { eq }) => eq(user.id, session.user.id),
    // Add role field to your schema if needed
  });

  // if (user.role !== 'admin') {
  //   return c.json({ error: 'Forbidden' }, 403)
  // }

  // Fetch all users
  const users = await db.query.user.findMany({
    columns: {
      id: true,
      email: true,
      name: true,
      createdAt: true,
    },
  });

  return c.json(users);
});

// ═══════════════════════════════════════════════════════════════
// Health check
// ═══════════════════════════════════════════════════════════════
app.get("/health", (c) => {
  return c.json({
    status: "ok",
    timestamp: new Date().toISOString(),
  });
});

// ═══════════════════════════════════════════════════════════════
// Export Worker
// ═══════════════════════════════════════════════════════════════
export default app;

/**
 * ═══════════════════════════════════════════════════════════════
 * SETUP CHECKLIST
 * ═══════════════════════════════════════════════════════════════
 *
 * 1. Create D1 database:
 *    wrangler d1 create my-app-db
 *
 * 2. Create KV namespaces:
 *    wrangler kv:namespace create SESSIONS_KV
 *    wrangler kv:namespace create RATE_LIMIT_KV
 *
 * 3. Add to wrangler.toml:
 *    [[d1_databases]]
 *    binding = "DB"
 *    database_name = "my-app-db"
 *    database_id = "YOUR_ID"
 *
 *    [[kv_namespaces]]
 *    binding = "SESSIONS_KV"
 *    id = "YOUR_ID"
 *
 *    [[kv_namespaces]]
 *    binding = "RATE_LIMIT_KV"
 *    id = "YOUR_ID"
 *
 *    [vars]
 *    BETTER_AUTH_URL = "http://localhost:8787"
 *    FRONTEND_URL = "http://localhost:3000"
 *
 * 4. Set secrets:
 *    wrangler secret put BETTER_AUTH_SECRET
 *    wrangler secret put GOOGLE_CLIENT_ID
 *    wrangler secret put GOOGLE_CLIENT_SECRET
 *    wrangler secret put GITHUB_CLIENT_ID
 *    wrangler secret put GITHUB_CLIENT_SECRET
 *
 * 5. Generate and apply migrations:
 *    npx drizzle-kit generate
 *    wrangler d1 migrations apply my-app-db --local
 *    wrangler d1 migrations apply my-app-db --remote
 *
 * 6. Deploy:
 *    wrangler deploy
 *
 * ═══════════════════════════════════════════════════════════════
 */
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