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

package/skills/nuxt-better-auth/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: nuxt-better-auth
+description: Use when implementing auth in Nuxt apps with @onmax/nuxt-better-auth - provides useUserSession composable, server auth helpers, route protection, and Better Auth plugins integration.
+license: MIT
+---
+
+# Nuxt Better Auth
+
+Authentication module for Nuxt 4+ built on [Better Auth](https://www.better-auth.com/). Provides composables, server utilities, and route protection.
+
+> **Alpha Status**: This module is currently in alpha (v0.0.2-alpha.12) and not recommended for production use. APIs may change.
+
+## When to Use
+
+- Installing/configuring `@onmax/nuxt-better-auth`
+- Implementing login/signup/signout flows
+- Protecting routes (client and server)
+- Accessing user session in API routes
+- Integrating Better Auth plugins (admin, passkey, 2FA)
+- Setting up database with NuxtHub
+- Using clientOnly mode for external auth backends
+
+**For Nuxt patterns:** use `nuxt` skill
+**For NuxtHub database:** use `nuxthub` skill
+
+## Available Guidance
+
+| File                                                                 | Topics                                                                 |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **[references/installation.md](references/installation.md)**         | Module setup, env vars, config files                                   |
+| **[references/client-auth.md](references/client-auth.md)**           | useUserSession, signIn/signUp/signOut, BetterAuthState, safe redirects |
+| **[references/server-auth.md](references/server-auth.md)**           | serverAuth, getUserSession, requireUserSession                         |
+| **[references/route-protection.md](references/route-protection.md)** | routeRules, definePageMeta, middleware                                 |
+| **[references/plugins.md](references/plugins.md)**                   | Better Auth plugins (admin, passkey, 2FA)                              |
+| **[references/database.md](references/database.md)**                 | NuxtHub integration, Drizzle schema                                    |
+| **[references/client-only.md](references/client-only.md)**           | External auth backend, clientOnly mode, CORS                           |
+| **[references/types.md](references/types.md)**                       | AuthUser, AuthSession, type augmentation                               |
+
+## Usage Pattern
+
+**Load based on context:**
+
+- Installing module? → [references/installation.md](references/installation.md)
+- Login/signup forms? → [references/client-auth.md](references/client-auth.md)
+- API route protection? → [references/server-auth.md](references/server-auth.md)
+- Route rules/page meta? → [references/route-protection.md](references/route-protection.md)
+- Using plugins? → [references/plugins.md](references/plugins.md)
+- Database setup? → [references/database.md](references/database.md)
+- External auth backend? → [references/client-only.md](references/client-only.md)
+- TypeScript types? → [references/types.md](references/types.md)
+
+**DO NOT read all files at once.** Load based on context.
+
+## Key Concepts
+
+| Concept                | Description                                                     |
+| ---------------------- | --------------------------------------------------------------- |
+| `useUserSession()`     | Client composable - user, session, loggedIn, signIn/Out methods |
+| `requireUserSession()` | Server helper - throws 401/403 if not authenticated             |
+| `auth` route mode      | `'user'`, `'guest'`, `{ user: {...} }`, or `false`              |
+| `serverAuth()`         | Get Better Auth instance in server routes                       |
+
+## Quick Reference
+
+```ts
+// Client: useUserSession()
+const { user, loggedIn, signIn, signOut } = useUserSession()
+await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
+```
+
+```ts
+// Server: requireUserSession()
+const { user } = await requireUserSession(event, { user: { role: 'admin' } })
+```
+
+```ts
+// nuxt.config.ts: Route protection
+routeRules: {
+  '/admin/**': { auth: { user: { role: 'admin' } } },
+  '/login': { auth: 'guest' },
+  '/app/**': { auth: 'user' }
+}
+```
+
+## Resources
+
+- [Module Docs](https://github.com/onmax/nuxt-better-auth)
+- [Better Auth Docs](https://www.better-auth.com/)
+
+---
+
+_Token efficiency: Main skill ~300 tokens, each sub-file ~800-1200 tokens_

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,87 @@
+# 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 { defineClientAuth } from '@onmax/nuxt-better-auth/config'
+
+export default defineClientAuth({
+  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 '@onmax/nuxt-better-auth/config'
+
+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 '@onmax/nuxt-better-auth/config'
+
+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,143 @@
+# 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 '@onmax/nuxt-better-auth/config'
+
+// Object syntax (simplest)
+export default defineServerAuth({
+  emailAndPassword: { enabled: true },
+  // OAuth providers
+  socialProviders: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID as string,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET as string
+    }
+  },
+})
+
+// Or function syntax (access context like runtimeConfig, db)
+export default defineServerAuth(({ runtimeConfig, db }) => ({
+  emailAndPassword: { enabled: true },
+  socialProviders: {
+    github: {
+      clientId: runtimeConfig.github.clientId,
+      clientSecret: runtimeConfig.github.clientSecret
+    }
+  },
+  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 { defineClientAuth } from '@onmax/nuxt-better-auth/config'
+
+// Object syntax (simplest)
+export default defineClientAuth({
+  // Client-side plugin options (e.g., passkey, twoFactor)
+})
+
+// Or function syntax (access context like siteUrl)
+export default defineClientAuth(({ siteUrl }) => ({
+  // siteUrl contains the resolved base URL
+}))
+```
+
+## 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.