@arow-software/auth-client 1.1.0

package/README.md

@@ -0,0 +1,342 @@
+# @arow-software/auth-client
+
+Reusable authentication package for ArowAuth SSO integration. Provides React context, hooks, and utilities for seamless SSO authentication with automatic token refresh.
+
+## Features
+
+- 🔐 **Token Management** - Secure storage, automatic refresh, JWT decoding
+- 🔄 **API Interceptors** - Axios interceptors with 401 handling and request queuing
+- ⚛️ **React Integration** - Context provider and hooks for easy auth state management
+- 🎯 **TypeScript** - Full type definitions included
+- 📦 **Lightweight** - Peer dependencies only (React, Axios)
+
+## Installation
+
+```bash
+# npm
+npm install @arow-software/auth-client
+
+# yarn
+yarn add @arow-software/auth-client
+
+# pnpm
+pnpm add @arow-software/auth-client
+```
+
+### Peer Dependencies
+
+Make sure you have these installed:
+
+```bash
+npm install react axios
+```
+
+## Quick Start
+
+### 1. Wrap your app with AuthProvider
+
+```tsx
+// App.tsx
+import { AuthProvider } from '@arow-software/auth-client';
+
+function App() {
+  return (
+    <AuthProvider
+      ssoBaseUrl="https://sso.arowsoftware.co.uk"
+      clientId="arowtrades"
+      apiBaseUrl="http://localhost:5001"
+    >
+      <YourApp />
+    </AuthProvider>
+  );
+}
+```
+
+### 2. Use the useAuth hook
+
+```tsx
+// LoginButton.tsx
+import { useAuth } from '@arow-software/auth-client';
+
+function LoginButton() {
+  const { isAuthenticated, isLoading, user, login, logout } = useAuth();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (isAuthenticated) {
+    return (
+      <div>
+        <span>Welcome, {user?.displayName || user?.email}!</span>
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => login()}>Login with SSO</button>;
+}
+```
+
+### 3. Make authenticated API calls
+
+```tsx
+// DataComponent.tsx
+import { useAuthClient } from '@arow-software/auth-client';
+import { useState, useEffect } from 'react';
+
+function DataComponent() {
+  const client = useAuthClient();
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    const fetchData = async () => {
+      try {
+        const response = await client.get('/api/data');
+        setData(response.data);
+      } catch (error) {
+        console.error('Failed to fetch data', error);
+      }
+    };
+    
+    fetchData();
+  }, [client]);
+
+  return <div>{JSON.stringify(data)}</div>;
+}
+```
+
+## API Reference
+
+### AuthProvider Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `ssoBaseUrl` | `string` | ✅ | Base URL of ArowAuth SSO server |
+| `clientId` | `string` | ✅ | Client ID registered with ArowAuth |
+| `apiBaseUrl` | `string` | ❌ | Base URL for your API (for axios client) |
+| `redirectUri` | `string` | ❌ | Custom redirect URI (defaults to origin + /callback) |
+| `scopes` | `string[]` | ❌ | OAuth scopes (defaults to ['openid', 'email', 'profile']) |
+| `storagePrefix` | `string` | ❌ | Storage key prefix (defaults to 'arowauth') |
+| `useSessionStorage` | `boolean` | ❌ | Use sessionStorage instead of localStorage |
+| `onTokenRefresh` | `function` | ❌ | Callback when tokens are refreshed |
+| `onAuthError` | `function` | ❌ | Callback when auth error occurs |
+| `onLogout` | `function` | ❌ | Callback when user is logged out |
+
+### useAuth Hook
+
+Returns an object with:
+
+```typescript
+{
+  user: User | null;           // Current user object
+  isAuthenticated: boolean;    // Whether user is logged in
+  isLoading: boolean;          // Initial auth check in progress
+  error: string | null;        // Any auth error message
+  login: (redirectPath?: string) => void;  // Redirect to SSO login
+  logout: () => Promise<void>; // Clear tokens and logout
+  refreshUser: () => Promise<void>;  // Refresh user from token
+}
+```
+
+### User Object
+
+```typescript
+interface User {
+  id: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  avatarUrl?: string;
+  emailVerified: boolean;
+  roles?: string[];
+  permissions?: string[];
+}
+```
+
+### useAuthClient Hook
+
+Returns a configured Axios instance that:
+- Automatically attaches Bearer token to all requests
+- Handles 401 responses by refreshing tokens and retrying
+- Queues concurrent requests during token refresh
+
+### Token Manager Functions
+
+For advanced use cases, you can import token management functions directly:
+
+```typescript
+import {
+  getAccessToken,
+  getRefreshToken,
+  setTokens,
+  clearTokens,
+  isTokenExpired,
+  hasValidToken,
+  getUserFromToken,
+  refreshTokens,
+  getValidAccessToken,
+  decodeJwt,
+} from '@arow-software/auth-client';
+
+// Check if token exists and is valid
+if (hasValidToken()) {
+  const user = getUserFromToken();
+  console.log('Current user:', user);
+}
+
+// Manually refresh tokens
+const newTokens = await refreshTokens();
+
+// Decode JWT without verification
+const payload = decodeJwt(token);
+```
+
+### createApiClient Function
+
+Create a standalone axios instance with auth interceptors:
+
+```typescript
+import axios from 'axios';
+import { createAuthClient, initTokenManager } from '@arow-software/auth-client';
+
+// Initialize token manager
+initTokenManager({
+  ssoBaseUrl: 'https://sso.arowsoftware.co.uk',
+  clientId: 'myapp',
+});
+
+// Add auth to existing axios instance
+const myAxios = axios.create({ baseURL: 'http://api.example.com' });
+const authAxios = createAuthClient(myAxios, {
+  ssoBaseUrl: 'https://sso.arowsoftware.co.uk',
+  clientId: 'myapp',
+});
+```
+
+## SSO Callback Setup
+
+Create a callback route in your app to handle the SSO redirect:
+
+```tsx
+// pages/callback.tsx (or wherever your callback route is)
+import { useEffect } from 'react';
+import { useAuth } from '@arow-software/auth-client';
+import { useNavigate } from 'react-router-dom';
+
+function CallbackPage() {
+  const { isAuthenticated, isLoading } = useAuth();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    // AuthProvider automatically handles token extraction from URL hash
+    // Just wait for auth to complete and redirect
+    if (!isLoading) {
+      if (isAuthenticated) {
+        navigate('/dashboard');
+      } else {
+        navigate('/login?error=auth_failed');
+      }
+    }
+  }, [isAuthenticated, isLoading, navigate]);
+
+  return <div>Completing login...</div>;
+}
+```
+
+## Protected Routes
+
+Example with React Router:
+
+```tsx
+import { useAuth } from '@arow-software/auth-client';
+import { Navigate, useLocation } from 'react-router-dom';
+
+function ProtectedRoute({ children }: { children: React.ReactNode }) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const location = useLocation();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!isAuthenticated) {
+    // Save the attempted location for redirect after login
+    return <Navigate to="/login" state={{ from: location }} replace />;
+  }
+
+  return <>{children}</>;
+}
+
+// Usage
+<Route 
+  path="/dashboard" 
+  element={
+    <ProtectedRoute>
+      <Dashboard />
+    </ProtectedRoute>
+  } 
+/>
+```
+
+## Role-Based Access
+
+```tsx
+import { useAuth } from '@arow-software/auth-client';
+
+function AdminPanel() {
+  const { user, isAuthenticated } = useAuth();
+  
+  if (!isAuthenticated) return null;
+  
+  const isAdmin = user?.roles?.includes('admin');
+  
+  if (!isAdmin) {
+    return <div>Access denied. Admin role required.</div>;
+  }
+  
+  return <div>Admin Panel Content</div>;
+}
+```
+
+## Error Handling
+
+```tsx
+<AuthProvider
+  ssoBaseUrl="https://sso.arowsoftware.co.uk"
+  clientId="arowtrades"
+  onAuthError={(error) => {
+    console.error('Auth error:', error);
+    // Show notification, redirect to login, etc.
+  }}
+  onLogout={() => {
+    // Redirect to home, clear app state, etc.
+    window.location.href = '/';
+  }}
+>
+  <App />
+</AuthProvider>
+```
+
+## Environment Variables
+
+For Vite projects:
+
+```env
+VITE_SSO_BASE_URL=https://sso.arowsoftware.co.uk
+VITE_SSO_CLIENT_ID=arowtrades
+VITE_API_BASE_URL=http://localhost:5001
+```
+
+```tsx
+<AuthProvider
+  ssoBaseUrl={import.meta.env.VITE_SSO_BASE_URL}
+  clientId={import.meta.env.VITE_SSO_CLIENT_ID}
+  apiBaseUrl={import.meta.env.VITE_API_BASE_URL}
+>
+```
+
+## License
+
+MIT © ArowSoftware

package/dist/index.d.mts

@@ -0,0 +1,251 @@
+import React, { ReactNode } from 'react';
+import { AxiosInstance } from 'axios';
+
+/**
+ * User object returned from ArowAuth
+ */
+interface User {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    emailVerified: boolean;
+    roles?: string[];
+    permissions?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * JWT token payload structure
+ */
+interface JwtPayload {
+    sub: string;
+    email: string;
+    given_name?: string;
+    family_name?: string;
+    name?: string;
+    picture?: string;
+    email_verified?: boolean;
+    roles?: string[];
+    permissions?: string[];
+    iat: number;
+    exp: number;
+    iss: string;
+    aud: string | string[];
+}
+/**
+ * Token pair returned from auth endpoints
+ */
+interface TokenPair {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn?: number;
+    tokenType?: string;
+}
+/**
+ * Auth context state
+ */
+interface AuthState {
+    user: User | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    error: string | null;
+}
+/**
+ * Auth context value including actions
+ */
+interface AuthContextValue extends AuthState {
+    login: (redirectPath?: string) => void;
+    logout: () => Promise<void>;
+    refreshUser: () => Promise<void>;
+}
+/**
+ * Configuration for the auth client
+ */
+interface AuthConfig {
+    /**
+     * Base URL of the ArowAuth SSO server
+     * @example "https://sso.arowsoftware.co.uk"
+     */
+    ssoBaseUrl: string;
+    /**
+     * Client ID registered with ArowAuth
+     * @example "arowtrades"
+     */
+    clientId: string;
+    /**
+     * Base URL of your API that will validate tokens
+     * @example "http://localhost:5001"
+     */
+    apiBaseUrl?: string;
+    /**
+     * Custom redirect URI after SSO login (defaults to current origin + /callback)
+     */
+    redirectUri?: string;
+    /**
+     * Scopes to request from SSO (defaults to ['openid', 'email', 'profile'])
+     */
+    scopes?: string[];
+    /**
+     * Storage key prefix (defaults to 'arowauth')
+     */
+    storagePrefix?: string;
+    /**
+     * Use sessionStorage instead of localStorage (defaults to false)
+     */
+    useSessionStorage?: boolean;
+    /**
+     * Callback when tokens are refreshed
+     */
+    onTokenRefresh?: (tokens: TokenPair) => void;
+    /**
+     * Callback when auth error occurs
+     */
+    onAuthError?: (error: Error) => void;
+    /**
+     * Callback when user is logged out
+     */
+    onLogout?: () => void;
+}
+/**
+ * Props for AuthProvider component
+ */
+interface AuthProviderProps extends AuthConfig {
+    children: ReactNode;
+}
+
+/**
+ * Initialize token manager with configuration
+ */
+declare function initTokenManager(authConfig: AuthConfig): void;
+/**
+ * Decode a JWT token without verification
+ */
+declare function decodeJwt(token: string): JwtPayload | null;
+/**
+ * Get the access token from storage
+ */
+declare function getAccessToken(): string | null;
+/**
+ * Get the refresh token from storage
+ */
+declare function getRefreshToken(): string | null;
+/**
+ * Store tokens in storage
+ */
+declare function setTokens(accessToken: string, refreshToken: string): void;
+/**
+ * Clear all tokens from storage
+ */
+declare function clearTokens(): void;
+/**
+ * Check if the access token is expired or about to expire
+ */
+declare function isTokenExpired(token?: string | null): boolean;
+/**
+ * Check if we have a valid (non-expired) access token
+ */
+declare function hasValidToken(): boolean;
+/**
+ * Get user info from the current access token
+ */
+declare function getUserFromToken(): JwtPayload | null;
+/**
+ * Refresh tokens using the refresh token
+ * Handles concurrent refresh requests by returning the same promise
+ */
+declare function refreshTokens(): Promise<TokenPair | null>;
+/**
+ * Get a valid access token, refreshing if necessary
+ */
+declare function getValidAccessToken(): Promise<string | null>;
+
+/**
+ * Create and configure axios instance with auth interceptors
+ */
+declare function createAuthClient(axiosInstance: AxiosInstance, config: AuthConfig): AxiosInstance;
+/**
+ * Create a new axios instance with auth interceptors
+ */
+declare function createApiClient(config: AuthConfig): AxiosInstance;
+
+declare const AuthContext: React.Context<AuthContextValue | undefined>;
+/**
+ * AuthProvider component - wraps app with auth context
+ */
+declare function AuthProvider(props: AuthProviderProps): React.ReactElement;
+
+/**
+ * Hook to access auth state and actions
+ *
+ * @returns Auth context value with user, isAuthenticated, login, logout, etc.
+ * @throws Error if used outside of AuthProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { user, isAuthenticated, login, logout, isLoading } = useAuth();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   if (!isAuthenticated) {
+ *     return <button onClick={() => login()}>Login</button>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <p>Welcome, {user?.displayName || user?.email}!</p>
+ *       <button onClick={logout}>Logout</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAuth(): AuthContextValue;
+/**
+ * Hook to check if user is authenticated (convenience wrapper)
+ *
+ * @returns Boolean indicating if user is authenticated
+ */
+declare function useIsAuthenticated(): boolean;
+/**
+ * Hook to get current user (convenience wrapper)
+ *
+ * @returns Current user or null
+ */
+declare function useUser(): User | null;
+
+/**
+ * Hook to get a configured axios instance with auth interceptors
+ *
+ * The returned axios instance will:
+ * - Automatically attach Bearer token to requests
+ * - Handle 401 responses by refreshing tokens and retrying
+ * - Queue concurrent requests during token refresh
+ *
+ * @returns Configured axios instance
+ * @throws Error if used outside of AuthProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const client = useAuthClient();
+ *
+ *   const fetchData = async () => {
+ *     try {
+ *       const response = await client.get('/api/data');
+ *       console.log(response.data);
+ *     } catch (error) {
+ *       console.error('Failed to fetch data', error);
+ *     }
+ *   };
+ *
+ *   return <button onClick={fetchData}>Fetch Data</button>;
+ * }
+ * ```
+ */
+declare function useAuthClient(): AxiosInstance;
+
+export { type AuthConfig, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthState, type JwtPayload, type TokenPair, type User, clearTokens, createApiClient, createAuthClient, decodeJwt, getAccessToken, getRefreshToken, getUserFromToken, getValidAccessToken, hasValidToken, initTokenManager, isTokenExpired, refreshTokens, setTokens, useAuth, useAuthClient, useIsAuthenticated, useUser };