refactor route protection with typed UserMatch and auto-inferred types

Author: onmax

docs/app/components/app/AppHeader.vue

@@ -1,14 +1,11 @@
 <script setup lang="ts">
-const route = useRoute()
 const appConfig = useAppConfig()
 const site = useSiteConfig()
 
 const navLinks = [
   { name: 'docs', path: '/getting-started/quickstart' },
   { name: 'better-auth', path: 'https://www.better-auth.com', external: true },
 ]
-
-const isLanding = computed(() => route.path === '/')
 </script>
 
 <template>

docs/app/components/content/landing/LandingFeatures.vue

@@ -25,7 +25,9 @@ const items = features.items as { title: string, description: string, icon: stri
         >
           <div class="flex items-center gap-2 my-1">
             <UIcon :name="feature.icon" class="size-4" />
-            <p class="text-stone-600 dark:text-stone-400">{{ feature.title }}</p>
+            <p class="text-stone-600 dark:text-stone-400">
+              {{ feature.title }}
+            </p>
           </div>
           <div class="mt-2">
             <p class="mt-2 text-sm text-left text-muted">
@@ -44,7 +46,9 @@ const items = features.items as { title: string, description: string, icon: stri
           <div class="flex flex-col items-center justify-center w-full h-full gap-3">
             <div class="flex items-center gap-2">
               <UIcon name="i-lucide-globe" class="size-4" />
-              <p class="text-stone-600 dark:text-stone-400">Nuxt + Better Auth</p>
+              <p class="text-stone-600 dark:text-stone-400">
+                Nuxt + Better Auth
+              </p>
             </div>
             <p class="max-w-md mx-auto mt-4 text-4xl font-normal tracking-tighter text-center md:text-4xl">
               <strong>Set up authentication in minutes, not hours!</strong>

docs/app/components/content/landing/LandingHero.vue

@@ -7,9 +7,12 @@ const tabs = hero.tabs as { name: string, code: string, lang: string }[]
 
 // Map file extensions to languages
 function getLang(filename: string) {
-  if (filename.endsWith('.ts')) return 'ts'
-  if (filename.endsWith('.vue')) return 'vue'
-  if (filename.endsWith('.js')) return 'js'
+  if (filename.endsWith('.ts'))
+    return 'ts'
+  if (filename.endsWith('.vue'))
+    return 'vue'
+  if (filename.endsWith('.js'))
+    return 'js'
   return 'ts'
 }
 

docs/content/1.getting-started/4.type-augmentation.md

@@ -1,22 +1,38 @@
 ---
 title: Type Augmentation
-description: Extend Better Auth user and session types in your app.
+description: Types are automatically inferred from your auth config.
 ---
 
-Nuxt Better Auth exposes augmentable types under `#nuxt-better-auth`.
+## Automatic Type Inference
 
-Create `shared/types/auth.d.ts`:
+Types for `AuthUser` and `AuthSession` are automatically inferred from your `server/auth.config.ts`. No manual type augmentation needed for plugin fields!
 
 ```ts
+// server/auth.config.ts
+import { admin } from 'better-auth/plugins'
+
+export default defineServerAuth(() => ({
+  plugins: [admin()],
+}))
+
+// Now user.role is typed automatically in your app!
+```
+
+## HMR Support
+
+Changes to `auth.config.ts` automatically update types - no restart needed.
+
+## Custom Fields (Optional)
+
+If you need custom fields not from plugins, you can still use module augmentation:
+
+```ts
+// shared/types/auth.d.ts
 import '#nuxt-better-auth'
 
 declare module '#nuxt-better-auth' {
   interface AuthUser {
-    role?: string | null
-    banned?: boolean | null
+    customField?: string
   }
 }
 ```
-
-After this, `useUserSession()` and server utilities will reflect your custom fields.
-

docs/content/2.core-concepts/3.route-protection.md

@@ -1,45 +1,138 @@
 ---
 title: Route Protection
-description: Protect pages with route rules or meta.
+description: Layered approach to protect routes on client and server.
 ---
 
-There are two protection layers:
+## Layer 1: Route Rules
 
-## Client pages
+Declarative protection in `nuxt.config.ts`. Covers 90% of use cases:
 
-Global route middleware reads `meta.auth` / `meta.role`:
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/app/**': { auth: 'user' },
+    '/login': { auth: 'guest' },
+    '/admin/**': { auth: { user: { role: 'admin' } } },
+    '/staff/**': { auth: { user: { role: ['admin', 'moderator'] } } },
+  },
+})
+```
+
+## Layer 2: Page Meta
+
+Per-page overrides using `definePageMeta`. Same syntax as `routeRules`:
 
 ```ts
 definePageMeta({
-  auth: 'user',          // or 'guest'
-  // role: 'admin',      // optional
+  auth: 'user',
+})
+
+// Or with user matching
+definePageMeta({
+  auth: { user: { role: 'admin' } },
+})
+
+// Custom redirect
+definePageMeta({
+  auth: { only: 'user', redirectTo: '/subscribe' },
 })
 ```
 
-If a user is not logged in and `auth` resolves to `'user'`, they are redirected to `/login`.
+## Layer 3: Custom Middleware
 
-## Route rules sync
+For complex client-side logic, create standard Nuxt route middleware:
 
-The module copies `routeRules.auth` and `routeRules.role` into page meta at build time:
+```ts
+// middleware/premium.ts
+export default defineNuxtRouteMiddleware(() => {
+  const { user } = useUserSession()
+
+  if (!user.value?.subscription?.active) {
+    return navigateTo('/pricing')
+  }
+})
+```
 
 ```ts
+// pages/premium.vue
+definePageMeta({
+  middleware: 'premium',
+})
+```
+
+## Layer 4: Server API Protection
+
+Use `requireUserSession()` for server-side checks:
+
+```ts
+// server/api/admin/stats.get.ts
+export default defineEventHandler(async (event) => {
+  const { user } = await requireUserSession(event)
+
+  // User is guaranteed to exist
+  return { stats: await getStats(user.id) }
+})
+```
+
+With user matching:
+
+```ts
+// server/api/admin/users.get.ts
+export default defineEventHandler(async (event) => {
+  await requireUserSession(event, { user: { role: 'admin' } })
+
+  return { users: await getAllUsers() }
+})
+```
+
+## Module Configuration
+
+```ts
+// nuxt.config.ts
 export default defineNuxtConfig({
-  routeRules: {
-    '/app/**': { auth: 'user' },
-    '/admin/**': { auth: { role: 'admin' } },
-    '/login': { auth: 'guest' },
+  auth: {
+    redirects: {
+      login: '/login',   // Where to send unauthenticated users
+      guest: '/',        // Where to send authenticated users from guest-only pages
+    },
   },
 })
 ```
 
-### `auth` values
+## AuthMeta Types
+
+| Value | Description |
+|-------|-------------|
+| `false` | Public, no checks |
+| `'guest'` | Unauthenticated only |
+| `'user'` | Authenticated only |
+| `{ only?, redirectTo?, user? }` | Object form with options |
+
+Object form options:
+- `only: 'guest' | 'user'` - access restriction
+- `redirectTo: string` - custom redirect path
+- `user: UserMatch` - match against user properties
+
+## UserMatch Syntax
 
-- `false` or `undefined`: public
-- `'guest'`: only unauthenticated users
-- `'user'`: any authenticated user
-- `{ only?: 'guest' | 'user', role?: string | string[], redirectTo?: string }`
+Match user properties for fine-grained access control:
+
+```ts
+// Exact match - user.role must equal 'admin'
+{ user: { role: 'admin' } }
+
+// OR logic - user.role must be 'admin' OR 'moderator'
+{ user: { role: ['admin', 'moderator'] } }
+
+// AND logic - multiple fields must all match
+{ user: { role: 'admin', verified: true } }
+
+// Combined - role is admin OR moderator, AND verified is true
+{ user: { role: ['admin', 'moderator'], verified: true } }
+```
 
-## See also
+## See Also
 
-- How the module works: `/core-concepts/how-it-works`
-- Security & caveats: `/core-concepts/security-caveats`
+- [How It Works](/core-concepts/how-it-works)
+- [Security Caveats](/core-concepts/security-caveats)
+- [API Protection Guide](/guides/api-protection)

docs/content/3.guides/1.role-based-access.md

@@ -1,27 +1,57 @@
 ---
 title: Role‑Based Access
-description: Enforce roles on pages and server handlers.
+description: Protect routes using generic field matching on AuthUser.
 ---
 
-Roles are free‑form strings on your `AuthUser`.  
-Augment the type if you store `role` or `banned` on users (see `/getting-started/type-augmentation`).
+Route protection uses generic field matching via the `user` key. Works with ANY field on your `AuthUser` - not just roles.
 
-## Pages
+## With Admin Plugin
 
 ```ts
-definePageMeta({
-  auth: { role: 'admin' },
-})
+// server/auth.config.ts  
+import { admin } from 'better-auth/plugins'
+export default defineServerAuth(() => ({ plugins: [admin()] }))
+
+// nuxt.config.ts - role is now typed!
+routeRules: {
+  '/admin/**': { auth: { user: { role: 'admin' } } },
+  '/staff/**': { auth: { user: { role: ['admin', 'moderator'] } } },
+}
+```
+
+## With Organization Plugin
+
+```ts
+// Works the same way with any plugin fields
+routeRules: {
+  '/team/**': { auth: { user: { teamRole: 'owner' } } },
+}
 ```
 
-## Server
+## With Custom Fields
 
 ```ts
-export default defineEventHandler(async (event) => {
-  const { user } = await requireUserSession(event, { role: 'admin' })
-  return { ok: true, user }
-})
+// Any field on AuthUser works
+routeRules: {
+  '/premium/**': { auth: { user: { isPremium: true } } },
+  '/verified/**': { auth: { user: { emailVerified: true } } },
+}
+```
+
+## Matching Logic
+
+- **Single value**: exact match required
+- **Array**: OR logic (user field must be one of the values)
+- **Multiple fields**: AND logic (all must match)
+
+```ts
+// Must be admin AND verified
+{ auth: { user: { role: 'admin', emailVerified: true } } }
+
+// Must be admin OR moderator
+{ auth: { user: { role: ['admin', 'moderator'] } } }
 ```
 
-`requireUserSession` also checks `user.banned` and throws `403` if true.
+## Complex Logic
 
+For complex authorization, use custom middleware or `requireUserSession` with a `rule` callback.