@xenterprises/nuxt-x-auth-better 0.1.1

package/LICENSE

@@ -0,0 +1,60 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 X Enterprises LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of X Enterprises LLC, a Washington limited liability
+company.
+
+TERMS AND CONDITIONS
+
+1. OWNERSHIP
+   All rights, title, and interest in and to the Software, including all
+   intellectual property rights, are and shall remain the exclusive property
+   of X Enterprises LLC.
+
+2. RESTRICTIONS
+   Without the prior written consent of X Enterprises LLC, you may not:
+   - Copy, modify, or distribute the Software
+   - Reverse engineer, decompile, or disassemble the Software
+   - Sublicense, sell, lease, or otherwise transfer the Software
+   - Remove or alter any proprietary notices or labels
+
+3. AUTHORIZED USE
+   Use of this Software is limited to authorized employees, contractors, and
+   agents of X Enterprises LLC, solely for purposes approved by X Enterprises
+   LLC.
+
+4. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+   X ENTERPRISES LLC BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF,
+   OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.
+
+5. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL X ENTERPRISES LLC BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+   OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. GOVERNING LAW
+   This license shall be governed by and construed in accordance with the laws
+   of the State of Washington, United States, without regard to its conflict
+   of law provisions.
+
+7. TERMINATION
+   This license is effective until terminated. X Enterprises LLC may terminate
+   this license at any time without notice. Upon termination, you must destroy
+   all copies of the Software in your possession.
+
+For licensing inquiries, contact: legal@x.enterprises
+
+---
+X Enterprises LLC
+Bothell, Washington, United States

package/README.md

@@ -0,0 +1,199 @@
+# @xenterprises/nuxt-x-auth-better
+
+BetterAuth authentication layer for Nuxt 4.
+
+## 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
+
+```bash
+npm install @xenterprises/nuxt-x-auth-better better-auth
+```
+
+## Setup
+
+### 1. Extend the layer
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@xenterprises/nuxt-x-auth-better']
+})
+```
+
+### 2. Configure your provider
+
+```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'],
+    ui: {
+      showLogo: true,
+      logoUrl: '/logo.svg',
+      brandName: 'My App',
+    },
+  },
+})
+```
+
+### 3. Set environment variables
+
+```env
+NUXT_PUBLIC_BETTER_AUTH_BASE_URL=https://api.example.com
+```
+
+## Usage
+
+### Composable
+
+```vue
+<script setup>
+const { 
+  user, 
+  login, 
+  logout, 
+  signup, 
+  loginWithOAuth,
+  sendMagicLink,
+  forgotPassword,
+  isLoading,
+  isAuthenticated 
+} = useXAuth()
+
+// Email/password login
+await login('email@example.com', 'password')
+
+// OAuth login
+await loginWithOAuth('google')
+
+// Magic link
+await sendMagicLink('email@example.com')
+
+// Signup
+await signup('email@example.com', 'password', { name: 'John' })
+
+// Password reset
+await forgotPassword('email@example.com')
+
+// Logout
+await logout()
+</script>
+```
+
+### Normalized User Object
+
+Better Auth returns a normalized user object:
+
+```ts
+{
+  id: 'user-123',
+  email: 'user@example.com',
+  name: 'John Doe',
+  avatar: 'https://example.com/avatar.jpg',
+  emailVerified: true,
+  metadata: { /* provider-specific data */ }
+}
+```
+
+### 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 |
+
+## 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
+
+## OAuth Providers
+
+Configure which OAuth providers to show:
+
+```ts
+// app.config.ts
+export default defineAppConfig({
+  xAuth: {
+    oauthProviders: ['google', 'github', 'microsoft', 'apple'],
+  },
+})
+```
+
+Available providers depend on your Better Auth backend configuration.
+
+## Token Storage
+
+Tokens are stored in secure cookies:
+- `HttpOnly` - Not accessible via JavaScript
+- `Secure` - Only sent over HTTPS in production
+- `SameSite=Lax` - CSRF protection
+
+Cookie names are configurable via `tokens.accessCookie` and `tokens.refreshCookie`.
+
+## Testing
+
+```bash
+# Unit tests
+npm run test
+
+# E2E tests
+npx playwright test
+```
+
+## Requirements
+
+- Nuxt 4+
+- Better Auth 1.0+
+- @nuxt/ui v4+ (included)
+
+## License
+
+MIT

package/app/app.config.ts

@@ -0,0 +1,66 @@
+export default defineAppConfig({
+  xAuth: {
+    tokens: {
+      accessCookie: "x_auth_access",
+      refreshCookie: "x_auth_refresh",
+      hasRefresh: true,
+    },
+
+    redirects: {
+      login: "/auth/login",
+      signup: "/auth/signup",
+      afterLogin: "/",
+      afterSignup: "/",
+      afterLogout: "/auth/login",
+      forgotPassword: "/auth/forgot-password",
+    },
+
+    features: {
+      oauth: false,
+      magicLink: false,
+      otp: false,
+      forgotPassword: true,
+      signup: true,
+    },
+
+    oauthProviders: [] as Array<{
+      id: string;
+      label: string;
+      icon: string;
+    }>,
+
+    ui: {
+      showLogo: true,
+      showBrandName: true,
+      logoUrl: "",
+      brandName: "",
+      tagline: "",
+      layout: "centered" as "centered" | "split",
+      background: {
+        type: "gradient" as "gradient" | "image" | "solid",
+        imageUrl: "",
+        overlayOpacity: 50,
+      },
+      card: {
+        glass: false,
+        glassIntensity: "medium" as "subtle" | "medium" | "strong",
+        logoUrl: "",
+      },
+      legal: {
+        copyright: "",
+        links: [] as Array<{ label: string; to: string }>,
+      },
+      split: {
+        heroPosition: "left" as "left" | "right",
+        heroImageUrl: "",
+        headline: "",
+        subheadline: "",
+        features: [] as string[],
+      },
+      form: {
+        icon: "",
+        showSeparator: true,
+      },
+    },
+  },
+});

package/app/assets/css/main.css

@@ -0,0 +1,118 @@
+@import "tailwindcss";
+@import "@nuxt/ui";
+
+:focus-visible {
+  outline: 2px solid rgb(var(--color-primary-500));
+  outline-offset: 2px;
+}
+
+.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));
+}
+
+@keyframes skeleton-pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+.skeleton {
+  animation: skeleton-pulse 1.5s ease-in-out infinite;
+  background: rgb(var(--color-neutral-200));
+  border-radius: 0.375rem;
+}
+
+.dark .skeleton {
+  background: rgb(var(--color-neutral-800));
+}
+
+@keyframes shake {
+  0%, 100% { transform: translateX(0); }
+  10%, 30%, 50%, 70%, 90% { transform: translateX(-4px); }
+  20%, 40%, 60%, 80% { transform: translateX(4px); }
+}
+
+.auth-error {
+  animation: shake 0.5s ease-in-out;
+}
+
+@keyframes checkmark {
+  0% {
+    stroke-dashoffset: 100;
+  }
+  100% {
+    stroke-dashoffset: 0;
+  }
+}
+
+.auth-success-check {
+  stroke-dasharray: 100;
+  stroke-dashoffset: 100;
+  animation: checkmark 0.5s ease-out forwards;
+}
+
+.page-enter-active,
+.page-leave-active {
+  transition: opacity 0.3s ease, transform 0.3s ease;
+}
+
+.page-enter-from {
+  opacity: 0;
+  transform: translateY(10px);
+}
+
+.page-leave-to {
+  opacity: 0;
+  transform: translateY(-10px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
+@media print {
+  .auth-layout {
+    background: white !important;
+  }
+
+  .auth-bg,
+  .auth-hero {
+    display: none !important;
+  }
+}

package/app/components/XAuth/ForgotPassword.vue

@@ -0,0 +1,91 @@
+<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="!emailSent"
+        key="form"
+        title="Reset your password"
+        description="We'll send you a link to reset it"
+        :fields="fields"
+        :schema="schema"
+        :loading="isLoading"
+        :submit="{ label: 'Send reset link' }"
+        @submit="sendResetEmail"
+      >
+        <template #footer>
+          <ULink
+            :to="config.xAuth?.redirects?.login || '/auth/login'"
+            class="inline-flex items-center gap-1.5 text-sm text-muted hover:text-highlighted transition-colors"
+          >
+            <UIcon name="i-lucide-arrow-left" class="size-4" />
+            Back to sign in
+          </ULink>
+        </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">
+            Check your email
+          </h3>
+          <p class="text-sm text-muted">
+            If an account exists for <strong class="text-highlighted">{{ sentEmail }}</strong>,
+            we've sent password reset instructions.
+          </p>
+        </header>
+
+        <UButton
+          label="Return to sign in"
+          block
+          size="lg"
+          @click="goToLogin"
+        />
+      </article>
+    </Transition>
+  </div>
+</template>
+
+<script setup>
+import { z } from "zod"
+
+const config = useAppConfig()
+const router = useRouter()
+const { forgotPassword, isLoading, emailSent } = useXAuth()
+
+const sentEmail = ref("")
+
+const fields = [
+  {
+    name: "email",
+    type: "email",
+    label: "Email",
+    placeholder: "you@example.com",
+    required: true,
+  },
+]
+
+const schema = z.object({
+  email: z.string().email("Please enter a valid email address"),
+})
+
+async function sendResetEmail(payload) {
+  sentEmail.value = payload.data.email
+  await forgotPassword(payload.data.email)
+}
+
+function goToLogin() {
+  router.push(config.xAuth?.redirects?.login || "/auth/login")
+}
+</script>