@xenterprises/nuxt-x-auth-better 0.2.5 → 0.3.0

package/README.md

@@ -1,19 +1,8 @@
 # @xenterprises/nuxt-x-auth-better
 
-BetterAuth authentication layer for Nuxt 4.
+BetterAuth authentication layer for Nuxt 4. Pre-built UI components, route protection, OAuth, magic link, and password reset flows — all configurable via `app.config.ts`.
 
-## Features
-
-- **Better Auth integration** - Industry-standard authentication with Better Auth
-- **OAuth providers** - Google, GitHub, and more
-- **Magic link authentication** - Passwordless login via email
-- **Secure token storage** - HttpOnly cookies with SameSite protection
-- **Field normalization** - Unified user object across providers
-- **Pre-built UI components** - Login, Signup, Forgot Password, Magic Link, OAuth
-- **Route protection** - Global middleware for authenticated routes
-- **Responsive design** - Built with Nuxt UI v4
-
-## Installation
+## Install
 
 ```bash
 npm install @xenterprises/nuxt-x-auth-better better-auth
@@ -26,36 +15,30 @@ npm install @xenterprises/nuxt-x-auth-better better-auth
 ```ts
 // nuxt.config.ts
 export default defineNuxtConfig({
-  extends: ['@xenterprises/nuxt-x-auth-better']
+  extends: ['@xenterprises/nuxt-x-auth-better'],
 })
 ```
 
-### 2. Configure your provider
+### 2. Configure
 
 ```ts
 // app.config.ts
 export default defineAppConfig({
   xAuth: {
-    tokens: {
-      accessCookie: 'x_auth_access',
-      refreshCookie: 'x_auth_refresh',
-      hasRefresh: true,
-    },
-    redirects: {
-      login: '/auth/login',
-      signup: '/auth/signup',
-      afterLogin: '/dashboard',
-      afterSignup: '/dashboard',
-      afterLogout: '/auth/login',
-      forgotPassword: '/auth/forgot-password',
-    },
     features: {
       oauth: true,
       magicLink: true,
       forgotPassword: true,
       signup: true,
     },
-    oauthProviders: ['google', 'github'],
+    redirects: {
+      afterLogin: '/dashboard',
+      afterSignup: '/dashboard',
+    },
+    oauthProviders: [
+      { id: 'google', label: 'Google', icon: 'i-simple-icons-google' },
+      { id: 'github', label: 'GitHub', icon: 'i-simple-icons-github' },
+    ],
     ui: {
       showLogo: true,
       logoUrl: '/logo.svg',
@@ -73,127 +56,232 @@ NUXT_PUBLIC_X_AUTH_BASE_URL=https://api.example.com
 
 ## Usage
 
-### Composable
-
 ```vue
 <script setup>
 const {
   user,
+  isAuthenticated,
+  isLoading,
   login,
-  logout,
   signup,
-  loginWithOAuth,
+  logout,
+  loginWithProvider,
   sendMagicLink,
   forgotPassword,
-  isLoading,
-  isAuthenticated
+  resetPassword,
+  changePassword,
+  updateUser,
+  deleteAccount,
+  getToken,
+  getAuthHeaders,
 } = useXAuth()
 
-// Email/password login
 await login('email@example.com', 'password')
-
-// OAuth login
-await loginWithOAuth('google')
-
-// Magic link
+await loginWithProvider('google')
 await sendMagicLink('email@example.com')
-
-// Signup
-await signup('email@example.com', 'password', { name: 'John' })
-
-// Password reset
+await signup('email@example.com', 'password', 'John Doe')
 await forgotPassword('email@example.com')
-
-// Logout
+await changePassword('oldpass', 'newpass')
+await updateUser({ name: 'New Name' })
 await logout()
 </script>
 ```
 
-### Normalized User Object
-
-Better Auth returns a normalized user object:
+## Options (app.config.ts)
+
+### `xAuth.tokens`
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `accessCookie` | `string` | `"x_auth_access"` | Cookie name for access token |
+| `refreshCookie` | `string` | `"x_auth_refresh"` | Cookie name for refresh token |
+| `hasRefresh` | `boolean` | `true` | Enable refresh token storage |
+
+### `xAuth.redirects`
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `login` | `string` | `"/auth/login"` | Login page path |
+| `signup` | `string` | `"/auth/signup"` | Signup page path |
+| `afterLogin` | `string` | `"/"` | Redirect after successful login |
+| `afterSignup` | `string` | `"/"` | Redirect after successful signup |
+| `afterLogout` | `string` | `"/auth/login"` | Redirect after logout |
+| `forgotPassword` | `string` | `"/auth/forgot-password"` | Forgot password page path |
+
+### `xAuth.features`
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `oauth` | `boolean` | `false` | Enable OAuth provider buttons |
+| `magicLink` | `boolean` | `false` | Enable magic link authentication |
+| `otp` | `boolean` | `false` | Enable OTP authentication |
+| `forgotPassword` | `boolean` | `true` | Enable forgot password flow |
+| `signup` | `boolean` | `true` | Enable signup form and link |
+
+### `xAuth.oauthProviders`
+
+Array of `{ id, label, icon }` objects. Supported provider IDs: `google`, `github`, `microsoft`, `facebook`, `twitter`, `apple`, `linkedin`, `discord`, `spotify`.
+
+### `xAuth.ui`
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `showLogo` | `boolean` | `true` | Show logo in auth layout |
+| `showBrandName` | `boolean` | `true` | Show brand name below logo |
+| `logoUrl` | `string` | `""` | URL to logo image |
+| `brandName` | `string` | `""` | Brand name text |
+| `tagline` | `string` | `""` | Tagline below brand name |
+| `layout` | `"centered" \| "split"` | `"centered"` | Auth page layout style |
+| `background.enabled` | `boolean` | `true` | Enable background image |
+| `background.imageUrl` | `string` | `""` | Custom background image URL (random default if empty) |
+| `background.overlayOpacity` | `number` | `55` | Overlay opacity (0-100) |
+| `background.blur` | `boolean` | `true` | Blur background image |
+| `card.glass` | `boolean` | `false` | Glass morphism effect on card |
+| `card.logoUrl` | `string` | `""` | Logo shown inside the auth card |
+| `form.showSeparator` | `boolean` | `true` | Show "or" separator between OAuth and form |
+| `legal.copyright` | `string` | `""` | Footer copyright text |
+| `legal.links` | `Array<{label, to}>` | `[]` | Footer legal links |
+
+## Composable: `useXAuth()`
+
+### Reactive State
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `user` | `Ref<AuthUser \| null>` | Current authenticated user |
+| `isAuthenticated` | `Ref<boolean>` | Whether user is authenticated |
+| `isLoading` | `Ref<boolean>` | Whether session is loading |
+| `emailSent` | `Ref<boolean>` | Whether magic link / reset email was sent |
+| `codeSent` | `Ref<boolean>` | Whether OTP code was sent |
+| `session` | `Ref<SessionData>` | Raw Better Auth session data |
+| `sessionError` | `Ref<Error>` | Session error if any |
+| `config` | `Ref<AuthConfig>` | Current auth configuration |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `login(email, password)` | `AuthUser \| null` | Email/password sign in |
+| `signup(email, password, name?)` | `AuthUser \| null` | Create account |
+| `logout()` | `boolean` | Sign out and redirect |
+| `loginWithProvider(provider)` | `boolean` | Start OAuth flow |
+| `sendMagicLink(email, options?)` | `boolean` | Send magic link email |
+| `forgotPassword(email)` | `boolean` | Send password reset email |
+| `resetPassword(token, newPassword)` | `true \| { error }` | Reset password with token |
+| `changePassword(current, new)` | `true \| { error }` | Change password (authenticated) |
+| `updateUser({ name?, image? })` | `true \| { error }` | Update user profile |
+| `deleteAccount()` | `boolean` | Permanently delete account |
+| `getCurrentUser()` | `AuthUser \| null` | Get current user (fetches if needed) |
+| `getToken()` | `string \| null` | Get access token |
+| `getAuthHeaders()` | `Record<string, string>` | Get `{ Authorization: 'Bearer ...' }` |
+| `handleMagicLinkCallback(token)` | `true \| { error }` | Verify magic link token |
+| `resetState()` | `void` | Reset emailSent / codeSent flags |
+
+### AuthUser Type
 
 ```ts
-{
-  id: 'user-123',
-  email: 'user@example.com',
-  name: 'John Doe',
-  avatar: 'https://example.com/avatar.jpg',
-  emailVerified: true,
-  metadata: { /* provider-specific data */ }
+interface AuthUser {
+  id: string
+  email: string
+  name: string
+  avatar?: string
+  emailVerified: boolean
+  metadata?: Record<string, any>
 }
 ```
 
-### Protected Routes
-
-Routes are automatically protected by the global middleware.
-
-**Route types:**
-- **Guest-only routes** - `/auth/login`, `/auth/signup`, `/auth/forgot-password`, `/auth/magic-link` (redirects logged-in users)
-- **Public routes** - `/auth/handler/*`, `/auth/logout` (accessible by anyone)
-- **Protected routes** - Everything else (requires authentication)
-
 ## Components
 
 | Component | Description |
 |-----------|-------------|
-| `XAuthLogin` | Email/password login form |
-| `XAuthSignup` | Registration form |
-| `XAuthForgotPassword` | Password reset request |
-| `XAuthMagicLink` | Magic link authentication |
-| `XAuthOAuthButton` | Single OAuth provider button |
-| `XAuthOAuthButtonGroup` | All configured OAuth buttons |
-| `XAuthHandler` | OAuth callback handler |
+| `XAuthLogin` | Email/password login form with OAuth, magic link, and forgot password links |
+| `XAuthSignup` | Registration form with terms/privacy links |
+| `XAuthForgotPassword` | Password reset request form with success state |
+| `XAuthMagicLink` | Magic link email form with success state |
+| `XAuthOAuthButton` | Single OAuth provider button with brand icon |
+| `XAuthOAuthButtonGroup` | All configured OAuth provider buttons |
+| `XAuthHandler` | Callback handler for OAuth, magic link, password reset, email verification |
 
-## Pages (Auto-registered)
+## Pages (auto-registered)
 
-- `/auth/login` - Login page
-- `/auth/signup` - Registration page
-- `/auth/forgot-password` - Password reset
-- `/auth/magic-link` - Magic link authentication
-- `/auth/logout` - Logout handler
-- `/auth/handler/*` - OAuth callback handlers
+| Path | Description | Route Type |
+|------|-------------|------------|
+| `/auth/login` | Login page | Guest-only |
+| `/auth/signup` | Registration page | Guest-only |
+| `/auth/forgot-password` | Password reset request | Guest-only |
+| `/auth/magic-link` | Magic link authentication | Guest-only |
+| `/auth/reset-password` | Set new password (with token) | Guest-only |
+| `/auth/logout` | Logout handler | Public |
+| `/auth/handler/*` | OAuth / magic link / password reset callbacks | Public |
 
-## OAuth Providers
+All other routes are **protected** (require authentication).
 
-Configure which OAuth providers to show:
+## Environment Variables
 
-```ts
-// app.config.ts
-export default defineAppConfig({
-  xAuth: {
-    oauthProviders: ['google', 'github', 'microsoft', 'apple'],
-  },
-})
-```
+| Name | Required | Description |
+|------|----------|-------------|
+| `NUXT_PUBLIC_X_AUTH_BASE_URL` | Yes | Base URL of your Better Auth backend (e.g. `https://api.example.com`) |
 
-Available providers depend on your Better Auth backend configuration.
+The auth path is configurable via `runtimeConfig.public.x.auth.authPath` (default: `/auth`).
 
-## Token Storage
+## Error Reference
 
-Tokens are stored in secure cookies:
-- `HttpOnly` - Not accessible via JavaScript
-- `Secure` - Only sent over HTTPS in production
-- `SameSite=Lax` - CSRF protection
+All errors are displayed as toast notifications. Methods return `null`, `false`, or `{ error: string }` on failure.
 
-Cookie names are configurable via `tokens.accessCookie` and `tokens.refreshCookie`.
+| Context | Error | When |
+|---------|-------|------|
+| Login | "Please enter both email and password." | Empty email or password |
+| Login | "Invalid credentials." | Wrong email/password (from API) |
+| Signup | "Please enter both email and password." | Empty email or password |
+| Signup | "Could not create account." | API error (e.g. email exists) |
+| Forgot Password | "Please enter your email address." | Empty email |
+| Reset Password | "Token and new password are required" | Missing token or password |
+| Change Password | "Please enter both current and new passwords." | Empty input |
+| Magic Link | "Please enter your email address." | Empty email |
+| OAuth | "`{provider}` Login Failed" | OAuth flow error |
+| Logout | "Failed to sign out." | API error |
+| Update Profile | "Could not update profile." | API error |
+| Delete Account | "Could not delete account." | API error |
+
+## How It Works
+
+This layer uses Better Auth's official Vue client (`better-auth/vue`) via `createAuthClient`. The client communicates with your Better Auth backend using cookie-based sessions (`credentials: 'include'`).
+
+1. **Session management**: `createAuthClient` is instantiated once (singleton) and provides a reactive `useSession()` ref that auto-updates. The composable wraps this with convenience methods.
+
+2. **Route protection**: A global middleware (`auth.global.ts`) runs on every navigation. It classifies routes as public, guest-only, or protected, then calls `getCurrentUser()` to check auth state.
+
+3. **Auth layout**: All `/auth/*` pages use the `auth` layout which provides a card-style UI with background image, branding, and animations.
+
+4. **OAuth flow**: `loginWithProvider()` calls Better Auth's `signIn.social()` which redirects to the provider. The callback lands on `/auth/handler/oauth-callback` where the Handler component refreshes the session.
+
+5. **Token access**: `getToken()` and `getAuthHeaders()` extract the access token from the Better Auth session for use with your own API calls.
+
+## Layer Architecture
+
+- **`nuxt.config.ts`**: Registers `@nuxt/ui` module, loads the auth CSS, and defines `runtimeConfig.public.x.auth` for base URL and auth path.
+- **`app/app.config.ts`**: Defines all configurable options (tokens, redirects, features, OAuth providers, UI settings) with defaults. Consumer apps override these in their own `app.config.ts`.
+- **`app/composables/useXAuth.ts`**: Core composable wrapping Better Auth's Vue client with typed methods for all auth flows.
+- **`app/middleware/auth.global.ts`**: Global route middleware for auth-based route protection.
+- **`app/plugins/auth-token.ts`**: Provides `$getAuthToken` for use in other plugins/composables.
+- **`app/layouts/auth.vue`**: Visual auth layout with card design, background image, and branding.
+- **`app/components/XAuth/*`**: Pre-built form components using Nuxt UI's `UAuthForm`.
+- **`app/pages/auth/*`**: Auto-registered auth pages.
+- **`app/utils/`**: Cookie storage helper and field normalization utilities.
 
 ## Testing
 
 ```bash
-# Unit tests
-npm run test
-
-# E2E tests
-npx playwright test
+npm run test        # Watch mode
+npm run test:run    # Single run
 ```
 
 ## Requirements
 
 - Nuxt 4+
 - Better Auth 1.0+
-- @nuxt/ui v4+ (included)
+- @nuxt/ui v4+ (included as dependency)
 
 ## License
 
-MIT
+UNLICENSED

package/app/app.config.ts

@@ -37,9 +37,10 @@ export default defineAppConfig({
       tagline: "",
       layout: "centered" as "centered" | "split",
       background: {
-        type: "gradient" as "gradient" | "image" | "solid",
+        enabled: true,
         imageUrl: "",
-        overlayOpacity: 50,
+        overlayOpacity: 55,
+        blur: true,
       },
       card: {
         glass: false,

package/app/components/XAuth/Handler.vue

@@ -92,7 +92,7 @@ const props = defineProps({
 const config = useAppConfig();
 const router = useRouter();
 const route = useRoute();
-const { handleMagicLinkCallback, resetPassword } = useXAuth();
+const { handleMagicLinkCallback, resetPassword, getCurrentUser } = useXAuth();
 
 const isLoading = ref(true);
 const error = ref(null);
@@ -128,12 +128,9 @@ onMounted(async () => {
         return; // Don't redirect for password reset
 
       case "oauth":
-        // OAuth callbacks are typically handled automatically
-        // Just check if we're authenticated after the callback
-        const result = await handleMagicLinkCallback(url);
-        if (result?.error) {
-          throw new Error(result.error);
-        }
+        // OAuth callbacks are handled by Better Auth automatically via cookies.
+        // Refresh the session to pick up the new auth state.
+        await getCurrentUser();
         break;
 
       case "email-verification":
@@ -153,17 +150,13 @@ onMounted(async () => {
     let redirectPath = props.redirectTo || config.xAuth?.redirects?.afterLogin || "/";
 
     // Check if there's a redirect_to in the query or state parameter
-    if (route.query.redirect_to) {
-      redirectPath = route.query.redirect_to;
-    } else if (route.query.state) {
-      try {
-        const stateObj = JSON.parse(route.query.state);
-        if (stateObj.redirect_to) {
-          redirectPath = stateObj.redirect_to;
-        }
-      } catch {
-        // Ignore invalid state parameter
-      }
+    const candidateRedirect = route.query.redirect_to
+      || (() => { try { return JSON.parse(route.query.state)?.redirect_to; } catch { return null; } })();
+
+    // Validate redirect path to prevent open redirects — only allow relative paths
+    if (candidateRedirect && typeof candidateRedirect === 'string'
+      && candidateRedirect.startsWith('/') && !candidateRedirect.startsWith('//')) {
+      redirectPath = candidateRedirect;
     }
 
     // Redirect after delay

package/app/components/XAuth/Login.vue

@@ -120,35 +120,3 @@ async function handleOAuth(providerId) {
 }
 </script>
 
-<style scoped>
-.password-strength {
-  display: flex;
-  gap: 0.25rem;
-  margin-top: 0.5rem;
-}
-
-.password-strength__bar {
-  flex: 1;
-  height: 3px;
-  border-radius: 9999px;
-  background: rgb(var(--color-neutral-200));
-  transition: background 0.2s ease;
-}
-
-.dark .password-strength__bar {
-  background: rgb(var(--color-neutral-800));
-}
-
-.password-strength[data-strength="weak"] .password-strength__bar:nth-child(1) {
-  background: rgb(var(--color-error-500));
-}
-
-.password-strength[data-strength="medium"] .password-strength__bar:nth-child(1),
-.password-strength[data-strength="medium"] .password-strength__bar:nth-child(2) {
-  background: rgb(var(--color-warning-500));
-}
-
-.password-strength[data-strength="strong"] .password-strength__bar {
-  background: rgb(var(--color-success-500));
-}
-</style>

package/app/composables/useXAuth.ts

@@ -4,6 +4,13 @@ import type { AuthUser, AuthConfig } from './types';
 
 let authClientInstance: ReturnType<typeof createAuthClient> | null = null;
 
+function getOrigin(): string {
+  if (import.meta.client) {
+    return window.location.origin;
+  }
+  return '';
+}
+
 export function useXAuth() {
   const config = useRuntimeConfig();
   const appConfig = useAppConfig();
@@ -152,7 +159,7 @@ export function useXAuth() {
     try {
       const result = await authClient.resetPassword({
         email,
-        redirectTo: `${window.location.origin}/auth/reset-password`,
+        redirectTo: `${getOrigin()}/auth/handler/password-reset`,
       });
 
       emailSent.value = true;
@@ -166,8 +173,13 @@ export function useXAuth() {
   };
 
   const resetPassword = async (token: string, newPassword: string) => {
+    if (!token || !newPassword) {
+      return { error: 'Token and new password are required' };
+    }
+
     try {
       const result = await authClient.resetPassword({
+        token,
         newPassword,
       });
 
@@ -184,7 +196,7 @@ export function useXAuth() {
 
   const loginWithProvider = async (providerName: string) => {
     try {
-      const callbackUrl = `${window.location.origin}/auth/handler/oauth-callback`;
+      const callbackUrl = `${getOrigin()}/auth/handler/oauth-callback`;
 
       await authClient.signIn.social({
         provider: providerName as any,
@@ -286,6 +298,74 @@ export function useXAuth() {
     }
   };
 
+  const changePassword = async (currentPassword: string, newPassword: string) => {
+    if (!currentPassword || !newPassword) {
+      showError('Change Password Failed', 'Please enter both current and new passwords.');
+      return { error: 'Both current and new passwords are required' };
+    }
+
+    try {
+      const result = await authClient.changePassword({
+        currentPassword,
+        newPassword,
+      });
+
+      if (result.error) {
+        showError('Change Password Failed', result.error.message || 'Could not change password.');
+        return { error: result.error.message || 'Could not change password' };
+      }
+
+      showSuccess('Password Changed', 'Your password has been updated successfully.');
+      return true;
+    } catch (err: any) {
+      showError('Change Password Failed', err.message || 'An error occurred.');
+      return { error: err.message || 'An error occurred' };
+    }
+  };
+
+  const updateUser = async (data: { name?: string; image?: string }) => {
+    try {
+      const result = await authClient.updateUser(data);
+
+      if (result.error) {
+        showError('Update Failed', result.error.message || 'Could not update profile.');
+        return { error: result.error.message || 'Could not update profile' };
+      }
+
+      await authClient.getSession();
+      showSuccess('Profile Updated', 'Your profile has been updated.');
+      return true;
+    } catch (err: any) {
+      showError('Update Failed', err.message || 'An error occurred.');
+      return { error: err.message || 'An error occurred' };
+    }
+  };
+
+  const deleteAccount = async () => {
+    try {
+      const result = await authClient.deleteUser();
+
+      if (result.error) {
+        showError('Delete Failed', result.error.message || 'Could not delete account.');
+        return false;
+      }
+
+      showSuccess('Account Deleted', 'Your account has been permanently deleted.');
+
+      const redirectTo = authConfig.value?.redirects?.afterLogout || '/auth/login';
+      if (import.meta.client) {
+        window.location.href = redirectTo;
+      } else {
+        await navigateTo(redirectTo, { replace: true });
+      }
+
+      return true;
+    } catch (err: any) {
+      showError('Delete Failed', err.message || 'An error occurred.');
+      return false;
+    }
+  };
+
   const resetState = () => {
     emailSent.value = false;
     codeSent.value = false;
@@ -311,6 +391,9 @@ export function useXAuth() {
     getToken,
     getAuthHeaders,
     handleMagicLinkCallback,
+    changePassword,
+    updateUser,
+    deleteAccount,
     resetState,
     authClient,
   };

package/app/layouts/auth.vue

@@ -139,10 +139,16 @@ const logoUrl = computed(() => config.xAuth?.ui?.logoUrl || '')
 const brandName = computed(() => config.xAuth?.ui?.brandName || '')
 const loading = computed(() => isLoading.value)
 
-// Background Config
-const bgConfig = computed(() => config.xAuth?.ui?.background || {})
-const isBgEnabled = computed(() => bgConfig.value.enabled !== false)
-const overlayBlur = computed(() => bgConfig.value.blur !== false)
+// Background Config - with robust defaults that survive config overrides
+const bgConfig = computed(() => ({
+  enabled: config.xAuth?.ui?.background?.enabled ?? true,
+  imageUrl: config.xAuth?.ui?.background?.imageUrl ?? '',
+  overlayOpacity: config.xAuth?.ui?.background?.overlayOpacity ?? 55,
+  blur: config.xAuth?.ui?.background?.blur ?? true,
+}))
+
+const isBgEnabled = computed(() => bgConfig.value.enabled)
+const overlayBlur = computed(() => bgConfig.value.blur)
 
 const footerTextColorClass = computed(() => {
   if (backgroundImageUrl.value && isImageLoaded.value) {

package/app/middleware/auth.global.ts

@@ -10,6 +10,8 @@ export default defineNuxtRouteMiddleware(async (to) => {
     "/auth/login",
     "/auth/signup",
     "/auth/forgot-password",
+    "/auth/magic-link",
+    "/auth/reset-password",
   ];
 
   const publicRoutes = [

package/app/pages/auth/reset-password.vue

@@ -0,0 +1,121 @@
+<template>
+  <div>
+    <Transition
+      enter-active-class="transition-all duration-300 ease-out"
+      enter-from-class="opacity-0 translate-y-2"
+      enter-to-class="opacity-100 translate-y-0"
+      leave-active-class="transition-all duration-200 ease-in"
+      leave-from-class="opacity-100 translate-y-0"
+      leave-to-class="opacity-0 -translate-y-2"
+      mode="out-in"
+    >
+      <UAuthForm
+        v-if="!resetDone"
+        key="form"
+        title="Set a new password"
+        description="Enter your new password below"
+        :fields="fields"
+        :schema="schema"
+        :loading="isSubmitting"
+        :submit="{ label: 'Reset password' }"
+        @submit="handleReset"
+      >
+        <template v-if="formError" #footer>
+          <div class="p-3 rounded-lg bg-error/10 ring-1 ring-error/20">
+            <p class="text-sm text-error">{{ formError }}</p>
+          </div>
+        </template>
+      </UAuthForm>
+
+      <article v-else key="success" class="text-center space-y-6">
+        <figure class="mx-auto flex size-16 items-center justify-center rounded-full bg-success/10 ring-1 ring-success/20">
+          <UIcon name="i-lucide-check" class="size-8 text-success" />
+        </figure>
+
+        <header class="space-y-2">
+          <h3 class="text-xl font-semibold tracking-tight text-highlighted">
+            Password reset
+          </h3>
+          <p class="text-sm text-muted">
+            Your password has been changed successfully.
+          </p>
+        </header>
+
+        <UButton
+          label="Sign in"
+          block
+          size="lg"
+          @click="goToLogin"
+        />
+      </article>
+    </Transition>
+  </div>
+</template>
+
+<script setup>
+import { z } from "zod"
+
+definePageMeta({
+  layout: 'auth'
+})
+
+const config = useAppConfig()
+const route = useRoute()
+const router = useRouter()
+const { resetPassword } = useXAuth()
+
+const isSubmitting = ref(false)
+const resetDone = ref(false)
+const formError = ref('')
+
+const token = computed(() => route.query.token || '')
+
+const fields = [
+  {
+    name: "password",
+    type: "password",
+    label: "New Password",
+    placeholder: "At least 8 characters",
+    required: true,
+  },
+  {
+    name: "confirmPassword",
+    type: "password",
+    label: "Confirm Password",
+    placeholder: "Re-enter your password",
+    required: true,
+  },
+]
+
+const schema = z.object({
+  password: z.string().min(8, "Password must be at least 8 characters"),
+  confirmPassword: z.string().min(1, "Please confirm your password"),
+}).refine(data => data.password === data.confirmPassword, {
+  message: "Passwords do not match",
+  path: ["confirmPassword"],
+})
+
+async function handleReset(payload) {
+  if (!token.value) {
+    formError.value = 'Invalid or missing reset token. Please request a new password reset.'
+    return
+  }
+
+  isSubmitting.value = true
+  formError.value = ''
+
+  const result = await resetPassword(token.value, payload.data.password)
+
+  isSubmitting.value = false
+
+  if (result === true) {
+    resetDone.value = true
+  } else {
+    formError.value = result?.error || 'Failed to reset password. Please try again.'
+  }
+}
+
+function goToLogin() {
+  router.push(config.xAuth?.redirects?.login || '/auth/login')
+}
+</script>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/nuxt-x-auth-better",
   "type": "module",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "BetterAuth authentication layer for Nuxt",
   "license": "UNLICENSED",
   "author": "X Enterprises",