@onmax/nuxt-better-auth 0.0.2-alpha.15 → 0.0.2-alpha.17

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

@@ -1,139 +0,0 @@
-# Better Auth Plugins
-
-The module supports all Better Auth plugins. Configure in both server and client configs.
-
-## Server Plugin Setup
-
-```ts
-// server/auth.config.ts
-import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
-import { admin, twoFactor, passkey, multiSession } from 'better-auth/plugins'
-
-export default defineServerAuth({
-  emailAndPassword: { enabled: true },
-  plugins: [
-    admin(),
-    twoFactor({ issuer: 'MyApp' }),
-    passkey(),
-    multiSession()
-  ]
-})
-```
-
-## Client Plugin Setup
-
-```ts
-// app/auth.config.ts
-import { defineClientAuth } from '@onmax/nuxt-better-auth/config'
-import { adminClient, twoFactorClient, passkeyClient, multiSessionClient } from 'better-auth/client/plugins'
-
-export default defineClientAuth({
-  plugins: [
-    adminClient(),
-    twoFactorClient(),
-    passkeyClient(),
-    multiSessionClient()
-  ]
-})
-```
-
-## Common Plugins
-
-### Admin
-
-Role-based access control:
-
-```ts
-// Server
-import { admin } from 'better-auth/plugins'
-plugins: [admin()]
-
-// Client
-import { adminClient } from 'better-auth/client/plugins'
-plugins: [adminClient()]
-```
-
-Usage:
-
-```ts
-// Protect route
-await requireUserSession(event, { user: { role: 'admin' } })
-
-// Client: set user role
-await client.admin.setRole({ userId: 'xxx', role: 'admin' })
-```
-
-### Two-Factor (2FA)
-
-```ts
-// Server
-import { twoFactor } from 'better-auth/plugins'
-plugins: [twoFactor({ issuer: 'MyApp' })]
-
-// Client
-import { twoFactorClient } from 'better-auth/client/plugins'
-plugins: [twoFactorClient()]
-```
-
-Usage:
-
-```ts
-// Enable 2FA
-const { totpURI } = await client.twoFactor.enable({ password: 'xxx' })
-// Show QR code with totpURI
-
-// Verify OTP on login
-await client.twoFactor.verifyTotp({ code: '123456' })
-```
-
-### Passkey
-
-WebAuthn/FIDO2 authentication:
-
-```ts
-// Server
-import { passkey } from 'better-auth/plugins'
-plugins: [passkey()]
-
-// Client
-import { passkeyClient } from 'better-auth/client/plugins'
-plugins: [passkeyClient()]
-```
-
-Usage:
-
-```ts
-// Register passkey
-await client.passkey.addPasskey()
-
-// Sign in with passkey
-await signIn.passkey()
-```
-
-### Multi-Session
-
-Allow multiple concurrent sessions:
-
-```ts
-// Server
-import { multiSession } from 'better-auth/plugins'
-plugins: [multiSession()]
-
-// Client
-import { multiSessionClient } from 'better-auth/client/plugins'
-plugins: [multiSessionClient()]
-```
-
-Usage:
-
-```ts
-// List all sessions
-const sessions = await client.multiSession.listDeviceSessions()
-
-// Revoke specific session
-await client.multiSession.revokeSession({ sessionId: 'xxx' })
-```
-
-## Plugin Type Inference
-
-Types from plugins are automatically inferred. See [references/types.md](types.md) for type augmentation.

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

@@ -1,105 +0,0 @@
-# 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

@@ -1,135 +0,0 @@
-# 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

@@ -1,144 +0,0 @@
-# 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
-import { defineServerAuth } from '@onmax/nuxt-better-auth/config'
-
-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
-})
-```