vuethenticate 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,296 @@
+# Vuethenticate
+
+A Vue 3 authentication state management library using oidc-client-ts.
+
+## Features
+
+- 🔐 OIDC/OAuth2 authentication with automatic token management
+- ⚡ Vue 3 Composition API with reactive state
+- 🔄 Automatic token renewal
+- 📦 TypeScript support
+- 🎯 Minimal configuration required
+- 🎨 Customizable callback component
+
+## Installation
+
+```bash
+npm install vuethenticate
+```
+
+## Quick Start
+
+> **Important Setup Order**: Make sure to initialize `useAuth()` in your main App component or a parent component before any callback routes are accessible. The callback components depend on this initialization.
+
+### 1. Configure Authentication
+
+```vue
+<!-- App.vue - Main Application Component -->
+<script setup>
+import { useAuth } from 'vuethenticate'
+import { RouterView } from 'vue-router'
+
+// Initialize authentication in your main app component
+const { user, isAuthenticated, signIn, signOut } = useAuth({
+  authority: 'https://your-oidc-provider.com',
+  clientId: 'your-client-id'
+})
+</script>
+
+<template>
+  <div id="app">
+    <nav>
+      <div v-if="isAuthenticated">
+        <p>Welcome, {{ user.profile.name }}!</p>
+        <button @click="signOut">Sign Out</button>
+      </div>
+      <div v-else>
+        <button @click="signIn">Sign In</button>
+      </div>
+    </nav>
+    
+    <!-- Router outlet - callback routes will work properly now -->
+    <RouterView />
+  </div>
+</template>
+```
+
+### 2. Setup Callback Route
+
+```vue
+<!-- CallbackPage.vue -->
+<script setup>
+import { AuthCallback } from 'vuethenticate'
+
+function onSuccess(user, state) {
+  console.log('Authentication successful:', user)
+  console.log('State:', state)
+  // Redirect to app or show success message
+  window.location.href = '/dashboard'
+}
+
+function onError(error) {
+  console.error('Authentication failed:', error)
+  // Handle error - redirect to login or show error
+  window.location.href = '/login'
+}
+</script>
+
+<template>
+  <AuthCallback 
+    :onSuccess="onSuccess"
+    :onError="onError"
+  >
+    <div>Signing you in...</div>
+    
+    <template #error="{ error }">
+      <div>
+        <h2>Authentication Failed</h2>
+        <p>{{ error.message }}</p>
+      </div>
+    </template>
+  </AuthCallback>
+</template>
+```
+
+### 3. Add Route Configuration
+
+```javascript
+// router.js
+import { createRouter, createWebHistory } from 'vue-router'
+import CallbackPage from './CallbackPage.vue'
+import SilentCallbackPage from './SilentCallbackPage.vue'
+
+const routes = [
+  {
+    path: '/auth/callback',
+    component: CallbackPage
+  },
+  {
+    path: '/auth/silent-callback',
+    component: SilentCallbackPage
+  },
+  // ... other routes
+]
+
+export default createRouter({
+  history: createWebHistory(),
+  routes
+})
+```
+
+### 4. Setup Silent Callback (for Token Renewal)
+
+```vue
+<!-- SilentCallbackPage.vue -->
+<script setup>
+import { SilentCallback } from 'vuethenticate'
+
+function onError(error) {
+  console.error('Silent renewal failed:', error)
+}
+</script>
+
+<template>
+  <SilentCallback :onError="onError" />
+</template>
+```
+
+## URL State Support
+
+You can pass state through the authentication flow with full TypeScript support:
+
+```typescript
+// Define your state type
+interface MyAppState {
+  returnUrl: string;
+  theme: 'light' | 'dark';
+  userId?: string;
+}
+
+// Use with generic type parameter
+const auth = useAuth<MyAppState>(config);
+
+// Pass state during sign in
+await auth.signIn({
+  returnUrl: '/dashboard',
+  theme: 'dark'
+});
+
+// Pass state during sign out  
+await auth.signOut({
+  returnUrl: '/goodbye',
+  theme: 'light'
+});
+```
+
+### Receiving State in Callback
+
+```vue
+<script setup lang="ts">
+import { AuthCallback } from 'vuethenticate';
+
+interface MyAppState {
+  returnUrl: string;
+  theme: 'light' | 'dark';
+}
+
+const handleSuccess = (user: User, state?: MyAppState) => {
+  if (state?.returnUrl) {
+    router.push(state.returnUrl);
+  }
+  if (state?.theme) {
+    setTheme(state.theme);
+  }
+};
+</script>
+
+<template>
+  <AuthCallback<MyAppState>
+    @success="handleSuccess"
+  />
+</template>
+```
+
+> **Important**: Make sure to call `useAuth()` in your main App component or a parent component before rendering any callback components. The callback components rely on the authentication being initialized first.
+
+## API Reference
+
+### `useAuth(config)`
+
+The main composable for authentication state management.
+
+#### Configuration
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `authority` | `string` | ✓ | - | OIDC provider URL |
+| `clientId` | `string` | ✓ | - | Application client ID |
+| `redirectUri` | `string` | | `${origin}/auth/callback` | Callback URL |
+| `scope` | `string` | | `'openid profile'` | OIDC scopes |
+| `responseType` | `string` | | `'code'` | OAuth response type |
+| `storage` | `'localStorage' \| 'sessionStorage' \| 'memory'` | | `'localStorage'` | Storage type |
+| `automaticSilentRenew` | `boolean` | | `true` | Enable automatic token refresh |
+| `silentRedirectUri` | `string` | | `${origin}/auth/silent-callback` | Silent refresh callback URL |
+| `postLogoutRedirectUri` | `string` | | `${origin}` | Post-logout redirect URL |
+
+#### Event Callbacks
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `onError` | `(error: Error) => void` | Called when an error occurs |
+| `onUserLoaded` | `(user: User) => void` | Called when user is loaded |
+| `onUserUnloaded` | `() => void` | Called when user is unloaded |
+| `onAccessTokenExpired` | `() => void` | Called when access token expires |
+| `onAccessTokenExpiring` | `() => void` | Called before access token expires |
+
+#### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `user` | `Ref<User \| null>` | Current user object |
+| `isAuthenticated` | `Ref<boolean>` | Authentication status |
+| `isLoading` | `Ref<boolean>` | Loading state |
+| `error` | `Ref<Error \| null>` | Current error |
+| `accessToken` | `Ref<string \| null>` | Current access token |
+| `isExpired` | `Ref<boolean>` | Token expiration status |
+| `signIn` | `(state?: TState) => Promise<void>` | Initiate sign in with optional state |
+| `signOut` | `(state?: TState) => Promise<void>` | Sign out user with optional state |
+| `silentRenew` | `() => Promise<void>` | Manually renew token |
+| `clearError` | `() => void` | Clear current error |
+
+### `<AuthCallback>`
+
+Component for handling OAuth callback. **Note**: This component requires `useAuth()` to be called in a parent component first.
+
+#### Props
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `onSuccess` | `(user: User, state?: TState) => void` | | Success callback with typed state |
+| `onError` | `(error: Error) => void` | | Error callback |
+
+#### Slots
+
+| Slot | Props | Description |
+|------|-------|-------------|
+| `default` | - | Loading content |
+| `error` | `{ error: Error }` | Error content |
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `success` | `User, state?: TState` | Emitted on successful authentication with typed state |
+| `error` | `Error` | Emitted on authentication error |
+
+### `<SilentCallback>`
+
+Component for handling silent token renewal callbacks. This component should be mounted on a separate route (typically `/auth/silent-callback`) and is used internally by the library for automatic token refresh. **Note**: This component requires `useAuth()` to be called in a parent component first.
+
+#### Props
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `onError` | `(error: Error) => void` | | Error callback for silent renewal failures |
+
+#### Usage
+
+```vue
+<template>
+  <SilentCallback :onError="handleSilentError" />
+</template>
+
+<script setup>
+import { SilentCallback } from 'vuethenticate'
+
+function handleSilentError(error) {
+  console.error('Silent renewal failed:', error)
+}
+</script>
+```
+
+> **Note**: This component is primarily used in an iframe or popup for silent token renewal. It should be placed on a minimal page with no other content.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vuethenticate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A Vue 3 authentication state management library using oidc-client-ts",
   "keywords": [
     "vue",