@bagelink/auth 1.7.72 → 1.7.76

package/README.md

@@ -1,6 +1,16 @@
 # @bagelink/auth
 
-Authentication library for Bagelink applications with built-in SSO support, route management, and Vue components.
+Modern authentication library for Bagelink applications with built-in SSO support, automatic redirect handling, and Vue components.
+
+## Features
+
+- 🔐 **Complete auth flow** - Login, signup, password reset, email verification
+- 🚀 **SSO ready** - Google, GitHub, Microsoft, Apple, Okta, Facebook
+- 🔄 **Auto-redirect** - Handles post-login navigation automatically
+- 🛡️ **Security built-in** - Protection against open redirect attacks
+- 🎨 **Vue components** - Pre-built forms and pages
+- 📱 **Type-safe** - Full TypeScript support
+- 🧩 **Router integration** - Smart guards for protected routes
 
 ## Installation
 
@@ -13,381 +23,459 @@ npm install @bagelink/auth
 ### 1. Initialize Auth
 
 ```typescript
+// main.ts
+import { createApp } from 'vue'
 import { createAuth } from '@bagelink/auth'
-
-createAuth({
-  baseURL: 'https://api.your-app.com'
+import router from './router'
+
+const auth = createAuth({
+  baseURL: 'https://api.your-app.com',
+  redirect: {
+    loginRoute: 'Login',
+    fallback: '/dashboard',
+    autoRedirect: true,  // Automatic post-login redirect
+  }
 })
+
+// Connect router (automatically sets up auth guard)
+auth.use(router)
+
+const app = createApp(App)
+app.use(router)
+app.use(auth)  // Optional: adds $auth globally
+app.mount('#app')
 ```
 
-### 2. Add Routes
+### 2. Define Routes
 
 ```typescript
-import { createRouter } from 'vue-router'
-import { createAuthRoutes, createAuthGuard } from '@bagelink/auth'
-
-const router = createRouter({
+// router/index.ts
+import { createRouter, createWebHistory } from 'vue-router'
+
+const routes = [
+  {
+    path: '/login',
+    name: 'Login',
+    component: () => import('@/views/Login.vue'),
+  },
+  {
+    path: '/dashboard',
+    name: 'Dashboard',
+    component: () => import('@/views/Dashboard.vue'),
+    meta: { auth: true },  // Protected route
+  },
+]
+
+export default createRouter({
   history: createWebHistory(),
-  routes: [
-    // Add auth routes
-    ...createAuthRoutes({
-      basePath: '/auth',
-      redirectTo: '/dashboard'
-    }),
-    
-    // Your app routes
-    {
-      path: '/dashboard',
-      component: Dashboard,
-      meta: { requiresAuth: true }
-    }
-  ]
+  routes,
 })
-
-// Add auth guard to redirect authenticated users
-router.beforeEach(createAuthGuard({ redirectTo: '/dashboard' }))
-
-export default router
 ```
 
 ### 3. Use in Components
 
 ```vue
-<script setup>
+<script setup lang="ts">
 import { useAuth } from '@bagelink/auth'
 
-const { user, logout, isAuthenticated } = useAuth()
+const auth = useAuth()
+
+async function handleLogin() {
+  await auth.login({
+    email: 'user@example.com',
+    password: 'password'
+  })
+  // Auto-redirect happens automatically! 🎉
+}
 </script>
 
 <template>
-  <div v-if="isAuthenticated">
-    <p>Welcome, {{ user.name }}</p>
-    <button @click="logout">Logout</button>
+  <div v-if="auth.user.value">
+    <p>Welcome, {{ auth.user.value.name }}!</p>
+    <button @click="auth.logout()">Logout</button>
   </div>
 </template>
 ```
 
-## Route Configuration
+## Documentation
+
+- **[REDIRECT_GUIDE.md](./REDIRECT_GUIDE.md)** - Complete redirect configuration guide
+- **[COMPLETE_EXAMPLE.md](./COMPLETE_EXAMPLE.md)** - Full working application example
+- **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** - Migration guide for breaking changes
 
-### Basic Setup
+## Core API
+
+### `createAuth(config)`
+
+Initialize the auth module with redirect configuration:
 
 ```typescript
-createAuthRoutes()
-// Creates routes: /login, /signup, /forgot-password, /reset-password, /callback
+createAuth({
+  baseURL: string,              // Required: Your API base URL
+  redirect?: {
+    loginRoute?: string,        // Login route name (default: 'Login')
+    fallback?: string,          // Default redirect after login (default: '/')
+    queryKey?: string,          // Query param for redirect URL (default: 'redirect')
+    autoRedirect?: boolean,     // Auto-redirect after login (default: true)
+    preserveRedirect?: boolean,   // Preserve original URL (default: true)
+    noAuthRoutes?: string[],    // Routes requiring no auth (default: ['Login', 'Signup', ...])
+    allowedPaths?: RegExp[],    // Optional: Restrict allowed redirects for security
+  }
+})
 ```
 
-### Custom Base Path
+### `useAuth()`
+
+Returns auth composable with:
 
 ```typescript
-createAuthRoutes({
-  basePath: '/auth'
-})
-// Creates routes: /auth/login, /auth/signup, etc.
+{
+  // State
+  user: Ref<User | null>
+  accountInfo: Ref<AccountInfo | null>
+  
+  // Authentication
+  login(credentials): Promise<AuthenticationResponse>
+  signup(data): Promise<AuthenticationResponse>
+  logout(): Promise<void>
+  checkAuth(): Promise<boolean>
+  
+  // SSO
+  sso: {
+    google: { redirect(), callback() }
+    github: { redirect(), callback() }
+    microsoft: { redirect(), callback() }
+    // ... more providers
+  }
+  
+  // Password Management
+  forgotPassword(email): Promise<void>
+  resetPassword(token, newPassword): Promise<void>
+  changePassword(current, new): Promise<void>
+  
+  // Profile
+  updateProfile(updates): Promise<void>
+  
+  // Getters
+  getFullName(): string
+  getIsLoggedIn(): boolean
+  getEmail(): string
+  getRoles(): string[]
+}
+```
+
+### Custom Guard Composition
+
+For multi-tenant apps or advanced permission logic, disable the auto-guard and compose your own:
+
+#### Option 1: Using `composeGuards` utility (recommended)
+
+```typescript
+import { composeGuards } from '@bagelink/auth'
+
+// Disable auto-guard
+auth.use(router, { guard: false })
+
+// Custom org access guard
+const orgAccessGuard = () => async (to, from, next) => {
+  if (to.meta.requiresOrg) {
+    const hasAccess = await checkOrgAccess(to.params.orgId)
+    if (!hasAccess) return next('/no-access')
+  }
+  next()
+}
+
+// Compose all guards in sequence
+router.beforeEach(composeGuards([
+  auth.routerGuard(),  // Auth first
+  orgAccessGuard(),    // Then org check
+]))
 ```
 
-### Custom Route Names
+#### Option 2: Multiple `beforeEach` calls
 
 ```typescript
-createAuthRoutes({
-  routeNames: {
-    login: 'UserLogin',
-    signup: 'UserRegister',
-    callback: 'OAuthCallback'
+auth.use(router, { guard: false })
+
+// Guards run in order they're registered
+router.beforeEach(auth.routerGuard())
+
+router.beforeEach(async (to, from, next) => {
+  // Custom org/tenant check
+  if (to.meta.requiresOrg && !await checkOrgAccess(to.params.orgId)) {
+    return next('/no-access')
   }
+  next()
 })
 ```
 
-### With Layout Component
+#### Option 3: Manual composition
 
 ```typescript
-import AuthLayout from './layouts/AuthLayout.vue'
+auth.use(router, { guard: false })
 
-createAuthRoutes({
-  layout: AuthLayout
+router.beforeEach(async (to, from, next) => {
+  // Run auth guard first
+  const authPassed = await new Promise<boolean>((resolve) => {
+    auth.routerGuard()(to, from, (result?: any) => {
+      if (result !== undefined) {
+        next(result)
+        resolve(false)
+      } else {
+        resolve(true)
+      }
+    })
+  })
+  
+  if (!authPassed) return
+  
+  // Your custom logic
+  if (to.meta.requiresOrg && !await checkOrgAccess(to.params.orgId)) {
+    return next('/no-access')
+  }
+  
+  next()
 })
 ```
 
 ## Components
 
-### Form Components
-
-Use these if you want to build custom pages:
+### Pre-built Pages
 
 ```vue
 <script setup>
-import { LoginForm, SignupForm } from '@bagelink/auth'
+import { LoginPage, SignupPage, ForgotPasswordPage } from '@bagelink/auth'
 </script>
 
 <template>
-  <LoginForm
+  <LoginPage
     :texts="{ title: 'Welcome Back' }"
-    :show-github="true"
-    :show-google="true"
-    @switch-form="handleFormSwitch"
+    card-width="400px"
   />
 </template>
 ```
 
-### Page Components
+### Form Components
 
-Pre-built page components with layout:
+For custom layouts:
 
 ```vue
 <script setup>
-import { LoginPage } from '@bagelink/auth'
+import { LoginForm, SignupForm } from '@bagelink/auth'
 </script>
 
 <template>
-  <LoginPage
-    :texts="{ title: 'Sign In' }"
-    card-width="500px"
-  />
+  <div class="custom-layout">
+    <LoginForm
+      :texts="{ title: 'Sign In' }"
+      :show-google="true"
+      :show-github="true"
+    />
+  </div>
 </template>
 ```
 
-## SSO Configuration
+## SSO Integration
 
-### Available Providers
-
-- GitHub
-- Google
-- Microsoft
-- Apple
-- Okta
-- Facebook
-
-### Usage
+### Quick SSO Login
 
 ```typescript
 const { sso } = useAuth()
 
-// Initiate SSO login
-await sso.login('github')
-
-// Handle callback (automatically handled in /callback route)
-await sso.handleCallback()
-
-// Link additional account
-await sso.linkAccount('google')
+// Redirect to Google OAuth
+await sso.google.redirect({
+  redirect_uri: `${window.location.origin}/auth/callback`
+})
 ```
 
-### Customizing SSO Buttons
+### SSO Callback Route
 
-```vue
-<LoginForm
-  :show-github="true"
-  :show-google="true"
-  :show-microsoft="false"
-  :sso-outline="true"
-  :sso-show-value="true"
-  :sso-brand-background="true"
-/>
+```typescript
+// router.ts
+{
+  path: '/auth/callback',
+  name: 'Callback',
+  component: () => import('@bagelink/auth').then(m => m.Callback),
+}
 ```
 
-## API
-
-### `useAuth()`
-
-Returns the authentication composable with:
+### Available Providers
 
-- `user` - Current user object (reactive)
-- `isAuthenticated` - Boolean indicating auth status (computed)
-- `accountInfo` - Extended account information (reactive)
-- `login(email, password)` - Login with credentials
-- `signup(data)` - Create new account
-- `logout()` - Logout current user
-- `forgotPassword(email)` - Request password reset
-- `resetPassword(token, password)` - Reset password with token
-- `sso` - SSO methods object
+- Google
+- GitHub  
+- Microsoft
+- Apple
+- Okta
+- Facebook
 
-### `createAuth(config)`
+## Advanced Configuration
 
-Initialize the auth module:
+### Security: Restrict Redirect Paths
 
 ```typescript
 createAuth({
-  baseURL: string      // Required: Your API endpoint
+  baseURL: 'https://api.example.com',
+  redirect: {
+    allowedPaths: [
+      /^\/dashboard/,
+      /^\/profile/,
+      /^\/settings/,
+    ],
+    // Only these paths can be redirect targets
+  }
 })
 ```
 
-### `createAuthRoutes(config)`
+### Disable Auto-Redirect
 
-Create auth routes for Vue Router:
+For custom logic:
 
 ```typescript
-createAuthRoutes({
-  basePath?: string              // Base path for routes (default: '')
-  namePrefix?: string            // Prefix for route names (default: '')
-  routeNames?: {                 // Custom route names
-    login?: string
-    signup?: string
-    forgotPassword?: string
-    resetPassword?: string
-    callback?: string
+createAuth({
+  redirect: {
+    autoRedirect: false,  // Manual control
   }
-  redirectTo?: string            // Redirect after auth (default: '/')
-  layout?: Component             // Wrapper layout component
 })
-```
 
-### `createAuthGuard(config)`
+// Then in login handler:
+import { performRedirect, getRedirectConfig } from '@bagelink/auth'
+
+await auth.login(credentials)
+await performRedirect(router, getRedirectConfig())
+```
 
-Create a navigation guard:
+### Custom Route Meta Key
 
 ```typescript
-createAuthGuard({
-  redirectTo?: string  // Where to redirect authenticated users (default: '/')
+createAuth({
+  redirect: {
+    authMetaKey: 'requiresAuth',  // Default: 'auth'
+  }
 })
+
+// Then in routes:
+{
+  path: '/dashboard',
+  meta: { requiresAuth: true }  // Custom meta key
+}
 ```
 
-## Customization
+## Event System
 
-### Text Customization
+Listen to auth events:
 
-All forms support custom text via the `texts` prop:
+```typescript
+import { createAuth, AuthState } from '@bagelink/auth'
 
-```vue
-<LoginForm
-  :texts="{
-    title: 'Sign In',
-    emailLabel: 'Email Address',
-    passwordLabel: 'Password',
-    loginButton: 'Continue',
-    githubButton: 'Continue with GitHub'
-  }"
-/>
-```
+const auth = createAuth({ ... })
 
-### Multi-language Support
+auth.on(AuthState.LOGIN, () => {
+  console.log('User logged in')
+})
 
-```vue
-<script setup>
-import { ref, computed } from 'vue'
-import { LoginForm } from '@bagelink/auth'
-
-const locale = ref('en')
-
-const texts = computed(() => {
-  if (locale.value === 'he') {
-    return {
-      title: 'התחברות',
-      emailLabel: 'אימייל',
-      passwordLabel: 'סיסמה',
-      loginButton: 'התחברות'
-    }
-  }
-  return {
-    title: 'Login',
-    emailLabel: 'Email',
-    passwordLabel: 'Password',
-    loginButton: 'Login'
-  }
+auth.on(AuthState.LOGOUT, () => {
+  console.log('User logged out')
 })
-</script>
 
-<template>
-  <LoginForm :texts="texts" />
-</template>
+auth.on(AuthState.PROFILE_UPDATE, () => {
+  console.log('Profile updated')
+})
 ```
 
-### Custom Layout
-
-Create a layout wrapper:
+Available events:
+- `LOGIN`
+- `LOGOUT`
+- `SIGNUP`
+- `PASSWORD_RESET`
+- `PASSWORD_CHANGE`
+- `PROFILE_UPDATE`
+- `AUTH_CHECK`
+- `EMAIL_VERIFIED`
+- `SESSION_REFRESH`
 
-```vue
-<!-- AuthLayout.vue -->
-<template>
-  <div class="auth-layout">
-    <header>
-      <img src="/logo.png" alt="Logo">
-    </header>
-    <main>
-      <router-view />
-    </main>
-    <footer>
-      © 2024 Your Company
-    </footer>
-  </div>
-</template>
-```
+## TypeScript Support
 
-Then use it:
+Full type definitions included:
 
 ```typescript
-import AuthLayout from './AuthLayout.vue'
-
-createAuthRoutes({
-  layout: AuthLayout
-})
+import type {
+  User,
+  AccountInfo,
+  AuthState,
+  SSOProvider,
+  RedirectConfig,
+  LoginTexts,
+  SignupTexts,
+} from '@bagelink/auth'
 ```
 
-## Advanced Usage
+## Examples
 
-### Protected Routes
+### Protected Route Flow
 
-```typescript
-router.beforeEach(async (to, from, next) => {
-  const { isAuthenticated } = useAuth()
-  
-  if (to.meta.requiresAuth && !isAuthenticated.value) {
-    next('/login')
-  } else {
-    next()
-  }
-})
-```
+1. User visits `/dashboard` (protected)
+2. Not authenticated → redirected to `/login?redirect=/dashboard`
+3. User logs in
+4. Auto-redirected to `/dashboard`
 
-### Programmatic Navigation
+### Custom Login Page
 
-```typescript
-import { useRouter } from 'vue-router'
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
 import { useAuth } from '@bagelink/auth'
 
-const router = useRouter()
-const { login } = useAuth()
+const auth = useAuth()
+const email = ref('')
+const password = ref('')
+const error = ref('')
 
 async function handleLogin() {
   try {
-    await login(email, password)
-    router.push('/dashboard')
-  } catch (error) {
-    console.error('Login failed:', error)
+    await auth.login({ email: email.value, password: password.value })
+    // Auto-redirect happens automatically!
+  } catch (err: any) {
+    error.value = err.response?.data?.message || 'Login failed'
   }
 }
+</script>
+
+<template>
+  <form @submit.prevent="handleLogin">
+    <input v-model="email" type="email" placeholder="Email" />
+    <input v-model="password" type="password" placeholder="Password" />
+    <button type="submit">Login</button>
+    <p v-if="error" class="error">{{ error }}</p>
+  </form>
+</template>
 ```
 
-### Custom Error Handling
+### Role-Based Access
 
 ```typescript
-const { login } = useAuth()
-
-try {
-  await login(email, password)
-} catch (error) {
-  if (error.code === 'INVALID_CREDENTIALS') {
-    // Handle invalid credentials
-  } else if (error.code === 'NETWORK_ERROR') {
-    // Handle network error
-  }
-}
-```
+import { useAuth } from '@bagelink/auth'
 
-## TypeScript Support
+const auth = useAuth()
 
-Full TypeScript support with exported types:
+// Check if user has admin role
+if (auth.getRoles().includes('admin')) {
+  // Allow access
+}
 
-```typescript
-import type {
-  AuthState,
-  User,
-  AccountInfo,
-  SSOProvider,
-  LoginTexts,
-  SignupTexts,
-  AuthRouteConfig
-} from '@bagelink/auth'
+// Or in route guard
+router.beforeEach((to, from, next) => {
+  if (to.meta.requiresAdmin && !auth.getRoles().includes('admin')) {
+    next('/unauthorized')
+  } else {
+    next()
+  }
+})
 ```
 
+## Migration
+
+See [BREAKING_CHANGES.md](./BREAKING_CHANGES.md) for migration guide from previous versions.
+
 ## License
 
 MIT