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

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

@@ -0,0 +1,153 @@
+# Client-Side Authentication
+
+## useUserSession()
+
+Main composable for auth state and methods.
+
+```ts
+const {
+  user,           // Ref<AuthUser | null>
+  session,        // Ref<AuthSession | null>
+  loggedIn,       // ComputedRef<boolean>
+  ready,          // ComputedRef<boolean> - session fetch complete
+  client,         // Better Auth client (client-side only)
+  signIn,         // Proxy to client.signIn
+  signUp,         // Proxy to client.signUp
+  signOut,        // Sign out and clear session
+  fetchSession,   // Manually refresh session
+  updateUser      // Optimistic local user update
+} = useUserSession()
+```
+
+## Sign In
+
+```ts
+// Email/password
+await signIn.email({
+  email: 'user@example.com',
+  password: 'password123'
+}, {
+  onSuccess: () => navigateTo('/dashboard')
+})
+
+// OAuth
+await signIn.social({ provider: 'github' })
+```
+
+## Sign Up
+
+```ts
+await signUp.email({
+  email: 'user@example.com',
+  password: 'password123',
+  name: 'John Doe'
+}, {
+  onSuccess: () => navigateTo('/welcome')
+})
+```
+
+## Sign Out
+
+```ts
+await signOut()
+// or with redirect
+await signOut({ redirect: '/login' })
+```
+
+## Check Auth State
+
+```vue
+<script setup>
+const { user, loggedIn, ready } = useUserSession()
+</script>
+
+<template>
+  <div v-if="!ready">Loading...</div>
+  <div v-else-if="loggedIn">Welcome, {{ user?.name }}</div>
+  <div v-else>Please log in</div>
+</template>
+```
+
+## Safe Redirects
+
+Always validate redirect URLs from query params to prevent open redirects:
+
+```ts
+function getSafeRedirect() {
+  const redirect = route.query.redirect as string
+  // Must start with / and not // (prevents protocol-relative URLs)
+  if (!redirect?.startsWith('/') || redirect.startsWith('//')) {
+    return '/'
+  }
+  return redirect
+}
+
+await signIn.email({
+  email, password
+}, {
+  onSuccess: () => navigateTo(getSafeRedirect())
+})
+```
+
+## Wait for Session
+
+Useful when needing session before rendering:
+
+```ts
+await waitForSession() // 5s timeout
+if (loggedIn.value) {
+  // Session is ready
+}
+```
+
+## Manual Session Refresh
+
+```ts
+// Refetch from server
+await fetchSession({ force: true })
+```
+
+## Session Management
+
+Additional session management via Better Auth client:
+
+```ts
+const { client } = useUserSession()
+
+// List all active sessions for current user
+const sessions = await client.listSessions()
+
+// Revoke a specific session
+await client.revokeSession({ sessionId: 'xxx' })
+
+// Revoke all sessions except current
+await client.revokeOtherSessions()
+
+// Revoke all sessions (logs out everywhere)
+await client.revokeSessions()
+```
+
+These methods require the user to be authenticated.
+
+## BetterAuthState Component
+
+Renders once session hydration completes (`ready === true`), with loading placeholder support.
+
+```vue
+<BetterAuthState>
+  <template #default="{ loggedIn, user, session, signOut }">
+    <p v-if="loggedIn">Hi {{ user?.name }}</p>
+    <button v-else @click="navigateTo('/login')">Sign in</button>
+  </template>
+  <template #placeholder>
+    <p>Loading…</p>
+  </template>
+</BetterAuthState>
+```
+
+**Slots:**
+
+- `default` - Renders when `ready === true`, provides `{ loggedIn, user, session, signOut }`
+- `placeholder` - Renders while session hydrates
+
+Useful in clientOnly mode or for graceful SSR loading states.

package/skills/nuxt-better-auth/references/client-only.md

@@ -0,0 +1,89 @@
+# Client-Only Mode (External Auth Backend)
+
+When Better Auth runs on a separate backend (microservices, standalone server), use `clientOnly` mode.
+
+## Configuration
+
+### 1. Enable in nuxt.config.ts
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@onmax/nuxt-better-auth'],
+  auth: {
+    clientOnly: true,
+  },
+})
+```
+
+### 2. Point client to external server
+
+```ts [app/auth.config.ts]
+import { createAuthClient } from 'better-auth/vue'
+
+export function createAppAuthClient(_baseURL: string) {
+  return createAuthClient({
+    baseURL: 'https://auth.example.com', // External auth server
+  })
+}
+```
+
+### 3. Set frontend URL
+
+```ini [.env]
+NUXT_PUBLIC_SITE_URL="https://your-frontend.com"
+```
+
+## What Changes
+
+| Feature                                                                       | Full Mode       | Client-Only       |
+| ----------------------------------------------------------------------------- | --------------- | ----------------- |
+| `server/auth.config.ts`                                                       | Required        | Not needed        |
+| `/api/auth/**` handlers                                                       | Auto-registered | Skipped           |
+| `NUXT_BETTER_AUTH_SECRET`                                                     | Required        | Not needed        |
+| Server utilities (`serverAuth()`, `getUserSession()`, `requireUserSession()`) | Available       | **Not available** |
+| SSR session hydration                                                         | Server-side     | Client-side only  |
+| `useUserSession()`, route protection, `<BetterAuthState>`                     | Works           | Works             |
+
+## CORS Requirements
+
+Ensure external auth server:
+
+- Allows requests from frontend (CORS with `credentials: true`)
+- Uses `SameSite=None; Secure` cookies (HTTPS required)
+- Includes frontend URL in `trustedOrigins`
+
+## SSR Considerations
+
+Session fetched client-side only:
+
+- Server-rendered pages render as "unauthenticated" initially
+- Hydrates with session data on client
+- Use `<BetterAuthState>` for loading states
+
+```vue
+<BetterAuthState v-slot="{ isLoading, user }">
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="user">Welcome, {{ user.name }}</div>
+  <div v-else>Please log in</div>
+</BetterAuthState>
+```
+
+## Use Cases
+
+- **Microservices**: Auth service is separate deployment
+- **Shared auth**: Multiple frontends share one auth backend
+- **Existing backend**: Already have Better Auth server running elsewhere
+
+## Architecture Example
+
+```
+┌─────────────────┐     ┌─────────────────┐
+│   Nuxt App      │────▶│  Auth Server    │
+│  (clientOnly)   │     │ (Better Auth)   │
+│                 │◀────│                 │
+└─────────────────┘     └────────┬────────┘
+                                 │
+                        ┌────────▼────────┐
+                        │    Database     │
+                        └─────────────────┘
+```

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

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

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

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