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

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

@@ -1,115 +0,0 @@
-# Database Integration
-
-## NuxtHub Setup
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@nuxthub/core', '@onmax/nuxt-better-auth'],
-  hub: { database: true },
-  auth: {
-    secondaryStorage: true,  // Optional: KV for session caching
-    schema: {
-      usePlural: false,      // user vs users
-      casing: 'camelCase'    // camelCase or snake_case
-    }
-  }
-})
-```
-
-## Schema Generation
-
-The module auto-generates Drizzle schema from Better Auth tables. Schema available via:
-
-```ts
-import { user, session, account, verification } from '#auth/database'
-```
-
-## Database Dialect
-
-Supports: `sqlite`, `postgresql`, `mysql`
-
-Schema syntax adapts to dialect:
-
-- SQLite: `integer('id').primaryKey()`
-- PostgreSQL/MySQL: `uuid('id').primaryKey()` or `text('id').primaryKey()`
-
-## Schema Options
-
-```ts
-auth: {
-  schema: {
-    usePlural: true,    // tables: users, sessions, accounts
-    casing: 'snake_case' // columns: created_at, updated_at
-  }
-}
-```
-
-| Option      | Default       | Description              |
-| ----------- | ------------- | ------------------------ |
-| `usePlural` | `false`       | Pluralize table names    |
-| `casing`    | `'camelCase'` | Column naming convention |
-
-## Extending Schema
-
-Add custom columns via NuxtHub's schema hooks:
-
-```ts
-// server/plugins/extend-schema.ts
-export default defineNitroPlugin(() => {
-  useNitroApp().hooks.hook('hub:db:schema:extend', (schema) => {
-    // Add custom tables or extend existing
-  })
-})
-```
-
-## Secondary Storage (KV)
-
-Enable session caching with KV:
-
-```ts
-auth: {
-  secondaryStorage: true
-}
-```
-
-Requires `hub.kv: true` in config. Improves session lookup performance.
-
-## Server Config with DB
-
-Database adapter injected via context:
-
-```ts
-// server/auth.config.ts
-import { defineServerAuth } from '#auth/server'
-
-export default defineServerAuth(({ db }) => ({
-  database: db,  // Already configured when hub.database: true
-  emailAndPassword: { enabled: true }
-}))
-```
-
-## Manual Database Setup
-
-Without NuxtHub, configure manually:
-
-```ts
-// server/auth.config.ts
-import { drizzle } from 'drizzle-orm/...'
-import { defineServerAuth } from '#auth/server'
-
-const db = drizzle(...)
-
-export default defineServerAuth(() => ({
-  database: drizzleAdapter(db, { provider: 'sqlite' })
-}))
-```
-
-## Migrations
-
-Better Auth creates tables automatically on first run. For production, generate migrations:
-
-```bash
-# Using Better Auth CLI
-npx better-auth generate
-```

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

@@ -1,126 +0,0 @@
-# Installation & Configuration
-
-## Install
-
-```bash
-pnpm add @onmax/nuxt-better-auth better-auth
-```
-
-**Version Requirements:**
-
-- `@onmax/nuxt-better-auth`: `^0.0.2-alpha.12` (alpha)
-- `better-auth`: `^1.0.0` (module tested with `1.4.7`)
-- `@nuxthub/core`: `^0.10.0` (optional, for database)
-
-## Module Setup
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@onmax/nuxt-better-auth'],
-  auth: {
-    serverConfig: 'server/auth.config',  // default
-    clientConfig: 'app/auth.config',     // default
-    clientOnly: false,                   // true for external auth backend
-    redirects: {
-      login: '/login',  // redirect when auth required
-      guest: '/'        // redirect when already logged in
-    }
-  }
-})
-```
-
-## Environment Variables
-
-```bash
-# Required (min 32 chars)
-BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters
-
-# Required in production for OAuth
-NUXT_PUBLIC_SITE_URL=https://your-domain.com
-```
-
-## Server Config
-
-```ts
-// server/auth.config.ts
-import { defineServerAuth } from '#auth/server'
-
-export default defineServerAuth(({ runtimeConfig, db }) => ({
-  emailAndPassword: { enabled: true },
-  // OAuth providers
-  socialProviders: {
-    github: {
-      clientId: runtimeConfig.github.clientId,
-      clientSecret: runtimeConfig.github.clientSecret
-    }
-  },
-  // Session configuration (optional)
-  session: {
-    expiresIn: 60 * 60 * 24 * 7,      // 7 days (default)
-    updateAge: 60 * 60 * 24,           // Update every 24h (default)
-    freshAge: 60 * 60 * 24,            // Consider fresh for 24h (default, 0 to disable)
-    cookieCache: {
-      enabled: true,
-      maxAge: 60 * 5                   // 5 minutes cookie cache
-    }
-  }
-}))
-```
-
-Context available in `defineServerAuth`:
-
-- `runtimeConfig` - Nuxt runtime config
-- `db` - Database adapter (when NuxtHub enabled)
-
-### Session Options
-
-| Option                  | Default            | Description                                   |
-| ----------------------- | ------------------ | --------------------------------------------- |
-| `expiresIn`             | `604800` (7 days)  | Session lifetime in seconds                   |
-| `updateAge`             | `86400` (24 hours) | How often to refresh session expiry           |
-| `freshAge`              | `86400` (24 hours) | Session considered "fresh" period (0 = never) |
-| `cookieCache.enabled`   | `false`            | Enable cookie caching to reduce DB queries    |
-| `cookieCache.maxAge`    | `300` (5 minutes)  | Cookie cache lifetime                         |
-| `disableSessionRefresh` | `false`            | Disable automatic session refresh             |
-
-## Client Config
-
-```ts
-// app/auth.config.ts
-import { createAppAuthClient } from '#auth/client'
-
-export default createAppAuthClient({
-  // Client-side plugin options (e.g., passkey, twoFactor)
-})
-```
-
-## NuxtHub Integration
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@nuxthub/core', '@onmax/nuxt-better-auth'],
-  hub: { database: true },
-  auth: {
-    secondaryStorage: true  // Enable KV for session caching
-  }
-})
-```
-
-See [references/database.md](database.md) for schema setup.
-
-## Client-Only Mode
-
-For external auth backends (microservices, separate servers):
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  auth: {
-    clientOnly: true,  // No local auth server
-  }
-})
-```
-
-See [references/client-only.md](client-only.md) for full setup.

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

@@ -1,138 +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 '#auth/server'
-
-export default defineServerAuth(({ runtimeConfig }) => ({
-  emailAndPassword: { enabled: true },
-  plugins: [
-    admin(),
-    twoFactor({ issuer: 'MyApp' }),
-    passkey(),
-    multiSession()
-  ]
-}))
-```
-
-## Client Plugin Setup
-
-```ts
-// app/auth.config.ts
-import { createAppAuthClient } from '#auth/client'
-import { adminClient, twoFactorClient, passkeyClient, multiSessionClient } from 'better-auth/client/plugins'
-
-export default createAppAuthClient({
-  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
-})
-```