@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/app-dev/better-auth/SKILL.md

@@ -0,0 +1,598 @@
+---
+name: better-auth
+description: "Add or debug Better Auth for Next.js App Router: login, sessions, protected routes, middleware, OAuth (including Feishu/Lark), cookies, Prisma, and Auth.js migration."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Better Auth for Next.js
+
+## Auth Strategy Matrix
+
+| Action | Source | Method |
+|--------|--------|--------|
+| Get session | RSC (server) | `getSession()` wrapper |
+| Get session | Client component | Session React context |
+| Get preferences | RSC (server) | Direct DB / wrapper |
+| Get preferences | Client component | Session context |
+| Update preferences | RSC / client | Server actions + `router.refresh()` |
+
+---
+
+## Setup
+
+### Installation
+
+```bash
+npm install better-auth
+```
+
+### Environment Variables
+
+```env
+DATABASE_URL="your-database-url"
+BETTER_AUTH_SECRET="your-secret-key"
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+```
+
+### Run Migrations
+
+```bash
+npx better-auth migrate
+```
+
+---
+
+## Core Configuration
+
+### Server Auth (lib/auth.ts)
+
+```typescript
+import { betterAuth } from "better-auth"
+
+export const auth = betterAuth({
+  database: {
+    provider: "postgres",
+    url: process.env.DATABASE_URL,
+  },
+  emailAndPassword: {
+    enabled: true,
+  },
+  // Add OAuth providers as needed
+})
+```
+
+### API Route Handler
+
+```typescript
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/lib/auth"
+
+export const { GET, POST } = auth.handler()
+```
+
+### Client Auth (lib/auth-client.ts)
+
+```typescript
+import { createAuthClient } from "better-auth/client"
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL,
+})
+```
+
+---
+
+## NextAuth Migration Mappings
+
+### Client-side Sign In
+
+```typescript
+// Before (NextAuth)
+import { signIn } from "next-auth/react"
+await signIn("github")
+
+// After (Better Auth)
+import { authClient } from "@/lib/auth-client"
+const { data, error } = await authClient.signIn.social({
+  provider: "github",
+})
+```
+
+### Client-side Sign Out
+
+```typescript
+// Before
+import { signOut } from "next-auth/react"
+await signOut()
+
+// After
+import { authClient } from "@/lib/auth-client"
+const { data, error } = await authClient.signOut()
+```
+
+### Client-side Session
+
+```typescript
+// Before
+import { useSession } from "next-auth/react"
+const { data, status } = useSession()
+
+// After
+import { authClient } from "@/lib/auth-client"
+const { data, isPending, error } = authClient.useSession?.() ?? {}
+```
+
+### Server-side Sign In
+
+```typescript
+// Before
+import { signIn } from "@/lib/auth"
+await signIn("github")
+
+// After
+import { auth } from "@/lib/auth"
+const { redirect, url } = await auth.api.signInSocial({
+  body: { provider: "github" },
+})
+```
+
+### Server-side Sign Out
+
+```typescript
+// Before
+import { signOut } from "@/lib/auth"
+await signOut()
+
+// After
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+const { success } = await auth.api.signOut({
+  headers: await headers(),
+})
+```
+
+### Server-side Session
+
+```typescript
+// Before
+import { auth } from "@/lib/auth"
+const session = await auth()
+
+// After
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+const session = await auth.api.getSession({
+  headers: await headers(),
+})
+```
+
+---
+
+## Session Enrichment Pattern
+
+### Server-side Wrapper (lib/auth-server.ts)
+
+```typescript
+"use server"
+
+import { auth } from "./auth"
+import { headers } from "next/headers"
+import { db } from "./db"
+
+export async function getSession() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  })
+
+  if (!session) return null
+
+  const userData = await db.user.findUnique({
+    where: { id: session.user.id },
+    include: {
+      profile: true,
+      preferences: true,
+    },
+  })
+
+  return {
+    ...session,
+    user: {
+      ...session.user,
+      ...userData,
+    },
+  }
+}
+```
+
+### Session Context Provider (React 19)
+
+```tsx
+// context/session-context.tsx
+"use client"
+
+import { createContext, useContext, ReactNode, use } from "react"
+import type { getSession } from "@/lib/auth-server"
+
+type EnrichedSession = Awaited<ReturnType<typeof getSession>>
+
+const SessionContext = createContext<EnrichedSession | null>(null)
+
+export function SessionProvider({
+  children,
+  sessionPromise,
+}: {
+  children: ReactNode
+  sessionPromise: Promise<EnrichedSession>
+}) {
+  const session = use(sessionPromise) // React 19 pattern
+
+  return (
+    <SessionContext.Provider value={session}>
+      {children}
+    </SessionContext.Provider>
+  )
+}
+
+export function useSession() {
+  const context = useContext(SessionContext)
+  if (context === undefined) {
+    throw new Error("useSession must be used within SessionProvider")
+  }
+  return context
+}
+```
+
+### Root Layout Integration
+
+```tsx
+// app/layout.tsx
+import { SessionProvider } from "@/context/session-context"
+import { getSession } from "@/lib/auth-server"
+
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const sessionPromise = getSession()
+
+  return (
+    <html lang="en">
+      <body>
+        <SessionProvider sessionPromise={sessionPromise}>
+          {children}
+        </SessionProvider>
+      </body>
+    </html>
+  )
+}
+```
+
+### Usage in Client Components
+
+```tsx
+"use client"
+
+import { useSession } from "@/context/session-context"
+
+export function UserProfile() {
+  const session = useSession()
+
+  if (!session) return <div>Not logged in</div>
+
+  return (
+    <div>
+      <h1>Welcome, {session.user.name}</h1>
+      <p>Theme: {session.user.preferences?.theme}</p>
+    </div>
+  )
+}
+```
+
+---
+
+## Protected Routes
+
+### Client-side Protection
+
+```tsx
+"use client"
+
+import { authClient } from "@/lib/auth-client"
+import { redirect } from "next/navigation"
+
+export default function DashboardPage() {
+  const { data, error, isPending } = authClient.useSession?.() ?? {}
+
+  if (isPending) return <div>Loading...</div>
+  if (!data || error) redirect("/sign-in")
+
+  return <div>Welcome {data.user.name}</div>
+}
+```
+
+### Server-side Protection
+
+```tsx
+import { auth } from "@/lib/auth"
+import { headers } from "next/headers"
+import { redirect } from "next/navigation"
+
+export default async function DashboardPage() {
+  const session = await auth.api.getSession({
+    headers: await headers(),
+  })
+
+  if (!session) redirect("/sign-in")
+
+  return <div>Welcome {session.user.name}</div>
+}
+```
+
+---
+
+## Preferences Update Pattern
+
+```tsx
+"use client"
+
+import { useRouter } from "next/navigation"
+import { updateUserPreferences } from "@/lib/actions"
+
+export function UpdatePreferences() {
+  const router = useRouter()
+
+  async function handleUpdate(preferences: any) {
+    await updateUserPreferences(preferences)
+    router.refresh() // Refetch session via layout
+  }
+
+  return (
+    <button onClick={() => handleUpdate({ theme: "dark" })}>
+      Update Theme
+    </button>
+  )
+}
+```
+
+---
+
+## File Structure
+
+```
+app/
+├── api/
+│   └── auth/
+│       └── [...all]/
+│           └── route.ts        # Better Auth handler
+├── (auth)/
+│   ├── login/
+│   │   └── page.tsx
+│   ├── register/
+│   │   └── page.tsx
+│   └── layout.tsx
+└── dashboard/
+    └── page.tsx                # Protected route
+lib/
+├── auth.ts                     # Server config
+├── auth-client.ts              # Client instance
+└── auth-server.ts              # Enriched session wrapper
+context/
+└── session-context.tsx         # Provider + hook
+```
+
+---
+
+## Database Model Changes (from NextAuth)
+
+| NextAuth | Better Auth |
+|----------|-------------|
+| `sessionToken` | `token` |
+| `expires` | `expiresAt` |
+| `emailVerified` (Date) | `emailVerified` (boolean) |
+
+Additional Better Auth fields:
+- `ipAddress`, `userAgent` on Session
+- `createdAt`, `updatedAt` on all models
+- `password` field on Account for credentials
+
+---
+
+## Rules
+
+1. **Server session:** Always use `getSession()` from `lib/auth-server.ts`
+2. **Client session:** Always use `useSession()` from context
+3. **Single source of truth:** Don't re-fetch user data inconsistently
+4. **Type safety:** Infer types from `getSession` return type
+5. **Prefer async RSC patterns** and `use()` in appropriate boundaries
+
+---
+
+
+# Feishu + Better Auth OAuth Integration
+
+Integrate Feishu (飞书) / Lark OAuth login with Better Auth in Next.js using the `genericOAuth` plugin.
+
+## Architecture
+
+```
+Browser → /api/auth/sign-in/social {provider:"feishu"}
+       → 302 → accounts.feishu.cn/open-apis/authen/v1/authorize
+       → user approves → callback with ?code=...
+       → Better Auth exchanges code for token (POST tokenUrl)
+       → Better Auth calls getUserInfo → creates/links user + account
+       → session cookie set → redirect to app
+```
+
+## Prerequisites
+
+- Better Auth v1.5+ with `genericOAuth` plugin
+- Feishu App (Internal Enterprise or Marketplace) with **Web Application** capability enabled
+- `verification` table in DB (required by genericOAuth plugin)
+
+## Step 1 — Feishu App Setup
+
+1. Create app at [Feishu Open Platform](https://open.feishu.cn/app)
+2. Enable **Web Application** capability (Security Settings → Redirect URLs)
+3. Add redirect URL: `https://<your-domain>/api/auth/oauth2/callback/feishu`
+4. Note your **App ID** (`cli_xxx`) and **App Secret**
+5. Request scopes:
+   - `contact:user.email:readonly` — **requires admin approval** (高级权限: Enable → Create version → Submit → Admin approve)
+
+> ⚠️ Until email permission is approved, Feishu returns empty string `""` for email (not omitted). Use fallback pattern.
+
+## Step 2 — Server Auth Config
+
+```typescript
+// src/lib/auth.ts
+import { betterAuth } from "better-auth";
+import { prismaAdapter } from "@better-auth/prisma-adapter";
+import { genericOAuth } from "better-auth/plugins";
+import prisma from "@/lib/db";
+
+const FEISHU_BASE = process.env.FEISHU_BASE_URL ?? "feishu.cn";
+
+export const auth = betterAuth({
+  database: prismaAdapter(prisma, { provider: "postgresql" }),
+  emailAndPassword: { enabled: true },
+  session: {
+    expiresIn: 60 * 60 * 24 * 7,
+    updateAge: 60 * 60 * 24,
+  },
+  trustedOrigins: [
+    process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000",
+  ],
+  plugins: [
+    genericOAuth({
+      config: [
+        {
+          providerId: "feishu",
+          clientId: process.env.FEISHU_APP_ID!,
+          clientSecret: process.env.FEISHU_APP_SECRET!,
+          authorizationUrl: `https://accounts.${FEISHU_BASE}/open-apis/authen/v1/authorize`,
+          tokenUrl: `https://open.${FEISHU_BASE}/open-apis/authen/v2/oauth/token`,
+          scopes: ["contact:user.email:readonly"],
+          authentication: "post",
+          getUserInfo: async (tokens) => {
+            const res = await fetch(
+              `https://open.${FEISHU_BASE}/open-apis/authen/v1/user_info`,
+              { headers: { Authorization: `Bearer ${tokens.accessToken}` } },
+            );
+            if (!res.ok) throw new Error(`Feishu userinfo failed: ${res.status}`);
+            const json = await res.json();
+            const profile = json.data || json;
+            return {
+              id: profile.open_id,
+              name: profile.name || profile.en_name,
+              email: profile.email || `${profile.open_id}@feishu.local`,
+              image: profile.avatar_url,
+              emailVerified: false,
+            };
+          },
+        },
+      ],
+    }),
+  ],
+});
+```
+
+### Critical details
+
+- **`authentication: "post"`** — Feishu token endpoint requires `client_id`/`client_secret` in JSON body (not Basic auth header)
+- **`getUserInfo` over `mapProfileToUser`** — when `getUserInfo` is provided, `mapProfileToUser` is ignored; don't use both
+- **`tokens.accessToken`** — Better Auth normalizes to camelCase; NOT `access_token`
+- **`json.data`** — Feishu nests all user info under a `data` key; unwrap exactly once
+- **`emailVerified: false`** — must be Boolean, not DateTime (Better Auth schema requirement)
+- **Fallback email** — `${open_id}@feishu.local` when email scope not yet approved
+
+## Step 3 — Client Config
+
+```typescript
+// src/lib/auth-client.ts
+import { createAuthClient } from "better-auth/react";
+import { genericOAuthClient } from "better-auth/client/plugins";
+
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_APP_URL,
+  plugins: [genericOAuthClient()],
+});
+```
+
+## Step 4 — Route Handler
+
+```typescript
+// src/app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from "better-auth/next-js";
+import { auth } from "@/lib/auth";
+
+export const { GET, POST } = toNextJsHandler(auth);
+```
+
+> ⚠️ **Must use `toNextJsHandler`** from `better-auth/next-js`. Manual `auth.handler(req as unknown as Request)` breaks in Next.js 16 standalone mode.
+
+## Step 5 — Database Schema
+
+See [references/feishu-api.md](references/feishu-api.md) for the complete Prisma models (User, Session, Account, Verification).
+
+**Schema gotchas to watch for:**
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `emailVerified` insert fails | Schema has `DateTime` not `Boolean` | Migrate: `ALTER COLUMN TYPE BOOLEAN` |
+| Account insert fails | Missing `At` suffix | Rename: `accessTokenExpires` → `accessTokenExpiresAt` |
+| 500 on sign-in | Missing `Verification` model | Add Verification model, run migration |
+
+## Step 6 — Environment Variables
+
+```bash
+# Feishu OAuth
+FEISHU_APP_ID=cli_xxxxxxxxxxxx        # From Feishu Dev Console
+FEISHU_APP_SECRET=xxxxxxxxxxxx        # Store in Secret Manager — no trailing newline!
+FEISHU_BASE_URL=feishu.cn             # or larksuite.com for international
+
+# Better Auth
+BETTER_AUTH_SECRET=<random-string>
+BETTER_AUTH_URL=https://your-app.example.com  # Required for deployed apps
+
+# App URL (compile-time)
+NEXT_PUBLIC_APP_URL=https://your-app.example.com
+```
+
+### Secret Manager warning
+
+When storing secrets via `gcloud secrets versions add`:
+```bash
+# ✅ CORRECT — no trailing newline
+printf '%s' 'your-secret-value' | gcloud secrets versions add SECRET_NAME --data-file=-
+
+# ❌ WRONG — echo/add adds \n which breaks OAuth token exchange
+echo 'your-secret-value' | gcloud secrets versions add SECRET_NAME --data-file=-
+```
+
+## Step 7 — Trigger Login
+
+```typescript
+// In a React component
+import { authClient } from "@/lib/auth-client";
+
+const handleFeishuLogin = () => {
+  authClient.signIn.social({ provider: "feishu", callbackURL: "/" });
+};
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `email_is_missing` or empty email | `contact:user.email:readonly` not approved | Request admin approval; use `@feishu.local` fallback |
+| Token exchange fails | Trailing `\n` in app secret | Re-create secret with `printf '%s'` |
+| 404 on `/api/auth/*` | Missing `toNextJsHandler` | Use `better-auth/next-js` adapter, not manual handler |
+| Session not persisting | `BETTER_AUTH_URL` not set | Set env var to deployed URL |
+| Error 20029 | Redirect URL not registered | Add exact callback URL in Feishu app settings |
+
+## References
+
+- [Feishu Open Platform](https://open.feishu.cn/app)
+- [Better Auth genericOAuth Plugin](https://www.better-auth.com/docs/plugins/generic-oauth)
+- [Better Auth Next.js Adapter](https://www.better-auth.com/docs/integrations/next-js)
+- **API reference:** [references/feishu-api.md](references/feishu-api.md) — OAuth endpoints, request/response formats, user info fields, error codes, Prisma schema, and Feishu/Lark domain differences. Load this when implementing the OAuth flow or debugging auth errors.