@onmax/nuxt-better-auth 0.0.2-alpha.12 → 0.0.2-alpha.14

package/skills/nuxt-better-auth/references/route-protection.md

@@ -0,0 +1,105 @@
+# Route Protection
+
+Three layers of protection: route rules, page meta, and server middleware.
+
+## Route Rules (Global)
+
+Define auth requirements in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/admin/**': { auth: { user: { role: 'admin' } } },
+    '/dashboard/**': { auth: 'user' },
+    '/login': { auth: 'guest' },
+    '/public/**': { auth: false }
+  }
+})
+```
+
+## Auth Modes
+
+| Mode              | Behavior                                               |
+| ----------------- | ------------------------------------------------------ |
+| `'user'`          | Requires authenticated user                            |
+| `'guest'`         | Only unauthenticated users (redirects logged-in users) |
+| `{ user: {...} }` | Requires user matching specific properties             |
+| `false`           | No protection                                          |
+
+## Page Meta (Per-Page)
+
+Override or define auth for specific pages:
+
+```vue
+<script setup>
+// Require authentication
+definePageMeta({ auth: 'user' })
+</script>
+```
+
+```vue
+<script setup>
+// Require admin role
+definePageMeta({
+  auth: { user: { role: 'admin' } }
+})
+</script>
+```
+
+```vue
+<script setup>
+// Guest-only (login page)
+definePageMeta({ auth: 'guest' })
+</script>
+```
+
+## User Property Matching
+
+```ts
+// Single value
+{ auth: { user: { role: 'admin' } } }
+
+// OR logic (array)
+{ auth: { user: { role: ['admin', 'moderator'] } } }
+
+// AND logic (multiple fields)
+{ auth: { user: { role: 'admin', verified: true } } }
+```
+
+## Redirect Configuration
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  auth: {
+    redirects: {
+      login: '/login',    // Where to redirect unauthenticated users
+      guest: '/dashboard' // Where to redirect logged-in users from guest pages
+    }
+  }
+})
+```
+
+## Server Middleware
+
+Auth middleware runs on all `/api/**` routes matching `routeRules`.
+
+For custom API protection, use `requireUserSession()`:
+
+```ts
+// server/api/admin/[...].ts
+export default defineEventHandler(async (event) => {
+  await requireUserSession(event, { user: { role: 'admin' } })
+  // Handle request
+})
+```
+
+## Priority Order
+
+1. `definePageMeta({ auth })` - highest priority
+2. `routeRules` patterns - matched by path
+3. Default: no protection
+
+## Prerendered Pages
+
+Auth checks skip during prerender hydration. Session fetched client-side after hydration completes.

package/skills/nuxt-better-auth/references/server-auth.md

@@ -0,0 +1,135 @@
+# Server-Side Authentication
+
+## serverAuth()
+
+Get the Better Auth instance for advanced operations:
+
+```ts
+// server/api/custom.ts
+export default defineEventHandler(async (event) => {
+  const auth = serverAuth()
+  // Access full Better Auth API
+  const sessions = await auth.api.listSessions({ headers: event.headers })
+  return sessions
+})
+```
+
+Module-level singleton (safe to call multiple times - returns cached instance).
+
+### Available Server Methods
+
+Via `serverAuth().api`:
+
+```ts
+const auth = serverAuth()
+
+// Session management
+await auth.api.listSessions({ headers: event.headers })
+await auth.api.revokeSession({ sessionId: 'xxx' }, { headers: event.headers })
+await auth.api.revokeOtherSessions({ headers: event.headers })
+await auth.api.revokeSessions({ headers: event.headers })
+
+// User management (with admin plugin)
+await auth.api.setRole({ userId: 'xxx', role: 'admin' }, { headers: event.headers })
+```
+
+## getUserSession()
+
+Get current session without throwing (returns null if not authenticated):
+
+```ts
+export default defineEventHandler(async (event) => {
+  const result = await getUserSession(event)
+  if (!result) {
+    return { guest: true }
+  }
+  return { user: result.user }
+})
+```
+
+Returns `{ user: AuthUser, session: AuthSession } | null`.
+
+## requireUserSession()
+
+Enforce authentication - throws if not authenticated:
+
+```ts
+export default defineEventHandler(async (event) => {
+  const { user, session } = await requireUserSession(event)
+  // user and session are guaranteed to exist
+  return { userId: user.id }
+})
+```
+
+- Throws `401` if not authenticated
+- Throws `403` if user matching fails
+
+## User Matching
+
+Restrict access based on user properties:
+
+```ts
+// Single value - exact match
+await requireUserSession(event, {
+  user: { role: 'admin' }
+})
+
+// Array - OR logic (any value matches)
+await requireUserSession(event, {
+  user: { role: ['admin', 'moderator'] }
+})
+
+// Multiple fields - AND logic (all must match)
+await requireUserSession(event, {
+  user: { role: 'admin', verified: true }
+})
+```
+
+## Custom Rules
+
+For complex validation logic:
+
+```ts
+await requireUserSession(event, {
+  rule: ({ user, session }) => {
+    return user.subscription?.active && user.points > 100
+  }
+})
+
+// Combined with user matching
+await requireUserSession(event, {
+  user: { verified: true },
+  rule: ({ user }) => user.subscription?.plan === 'pro'
+})
+```
+
+## Pattern Examples
+
+```ts
+// Admin-only endpoint
+export default defineEventHandler(async (event) => {
+  const { user } = await requireUserSession(event, {
+    user: { role: 'admin' }
+  })
+  return getAdminData()
+})
+
+// Premium feature
+export default defineEventHandler(async (event) => {
+  await requireUserSession(event, {
+    rule: ({ user }) => ['pro', 'enterprise'].includes(user.plan)
+  })
+  return getPremiumContent()
+})
+
+// Owner-only resource
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, 'id')
+  const { user } = await requireUserSession(event)
+  const resource = await getResource(id)
+  if (resource.ownerId !== user.id) {
+    throw createError({ statusCode: 403 })
+  }
+  return resource
+})
+```

package/skills/nuxt-better-auth/references/types.md

@@ -0,0 +1,142 @@
+# TypeScript Types
+
+## Module Alias
+
+Import types from the module alias:
+
+```ts
+import type { AuthUser, AuthSession, ServerAuthContext, AppAuthClient } from '#nuxt-better-auth'
+```
+
+## Core Types
+
+### AuthUser
+
+User object returned by `useUserSession()` and `requireUserSession()`:
+
+```ts
+interface AuthUser {
+  id: string
+  email: string
+  name?: string
+  image?: string
+  emailVerified: boolean
+  createdAt: Date
+  updatedAt: Date
+  // Plus any fields from plugins (role, etc.)
+}
+```
+
+### AuthSession
+
+Session object:
+
+```ts
+interface AuthSession {
+  id: string
+  userId: string
+  expiresAt: Date
+  // token is filtered from exposed data
+}
+```
+
+## Type Inference
+
+Types are automatically inferred from your server config. The module uses `InferUser` and `InferSession` from Better Auth:
+
+```ts
+// Inferred from server/auth.config.ts
+type AuthUser = InferUser<typeof authConfig>
+type AuthSession = InferSession<typeof authConfig>
+```
+
+## Plugin Type Augmentation
+
+When using plugins, types extend automatically:
+
+```ts
+// With admin plugin
+interface AuthUser {
+  // ... base fields
+  role: 'user' | 'admin'
+}
+
+// With 2FA plugin
+interface AuthUser {
+  // ... base fields
+  twoFactorEnabled: boolean
+}
+```
+
+## ServerAuthContext
+
+Available in `defineServerAuth()` callback:
+
+```ts
+interface ServerAuthContext {
+  runtimeConfig: RuntimeConfig
+  db?: DrizzleDatabase  // When NuxtHub enabled
+}
+```
+
+## Using Types in Components
+
+```vue
+<script setup lang="ts">
+import type { AuthUser } from '#nuxt-better-auth'
+
+const { user } = useUserSession()
+// user is Ref<AuthUser | null>
+
+function greet(u: AuthUser) {
+  return `Hello, ${u.name}`
+}
+</script>
+```
+
+## Using Types in Server
+
+```ts
+// server/utils/helpers.ts
+import type { AuthUser, AuthSession } from '#nuxt-better-auth'
+
+export function isAdmin(user: AuthUser): boolean {
+  return user.role === 'admin'
+}
+```
+
+## Custom User Fields
+
+Extend user type via Better Auth config:
+
+```ts
+// server/auth.config.ts
+export default defineServerAuth(() => ({
+  user: {
+    additionalFields: {
+      plan: { type: 'string' },
+      credits: { type: 'number' }
+    }
+  }
+}))
+```
+
+Types automatically include these fields:
+
+```ts
+// AuthUser now includes:
+interface AuthUser {
+  // ... base fields
+  plan: string
+  credits: number
+}
+```
+
+## Type-Safe User Matching
+
+```ts
+// Fully typed
+await requireUserSession(event, {
+  user: { role: 'admin' }  // TypeScript knows valid fields
+})
+```