@jasperoosthoek/zustand-auth-registry 0.0.1 → 0.0.3

package/README.md

@@ -1,24 +1,17 @@
 # zustand-auth-registry
 
-OAuth 2.0 compliant authentication state management library using Zustand and Axios with a type-safe registry pattern.
-
-## Overview
-
-`zustand-auth-registry` provides a simple, type-safe way to manage authentication state in React applications using Zustand. It supports both modern OAuth 2.0 standards and legacy authentication patterns, with automatic token refresh, Bearer token support, and comprehensive backward compatibility.
+Authentication state management library using Zustand and Axios with a type-safe registry pattern.
 
 ## Features
 
-- **OAuth 2.0 Compliance** - Industry-standard Bearer tokens, automatic refresh, token lifecycle management
 - **Authentication State Management** - User, token, and authentication status with reactive updates
 - **Registry Pattern** - Type-safe multiple auth stores per application
-- **Axios Integration** - Automatic authentication header management with configurable formats
-- **Token Lifecycle** - Automatic expiration detection, refresh workflows, and cleanup
-- **Auto-Refresh** - Configurable threshold-based token renewal (default: 5 minutes before expiry)
-- **Persistence** - Flexible storage options (localStorage, sessionStorage, custom) with OAuth token support
+- **Axios Integration** - Automatic authentication header management
+- **Token Lifecycle** - Automatic expiration detection and refresh workflows
+- **Cookie Authentication** - httpOnly cookie support with CSRF protection
+- **Typed Errors** - `AuthError` class with error codes for better error handling
+- **Persistence** - Flexible storage options (localStorage, sessionStorage, custom)
 - **Type-Safe** - Full TypeScript support with generics for user models
-- **Backward Compatible** - Seamless support for Django REST Framework and legacy APIs
-- **Flexible** - Support for multiple APIs with different authentication strategies
-- **Lightweight** - Simple API, no unnecessary complexity
 
 ## Installation
 
@@ -28,15 +21,13 @@ npm install @jasperoosthoek/zustand-auth-registry zustand axios react
 
 ## Quick Start
 
-### OAuth 2.0 Setup (Recommended)
-
 ```typescript
 import axios from 'axios';
 import { createAuthRegistry, useAuth } from '@jasperoosthoek/zustand-auth-registry';
 
 // 1. Define your user type
 type User = {
-  id: string;
+  id: number;
   email: string;
   name: string;
 };
@@ -49,350 +40,177 @@ const getAuthStore = createAuthRegistry<{
 // 3. Create axios instance
 const api = axios.create({ baseURL: 'https://api.example.com' });
 
-// 4. Create OAuth 2.0 compliant auth store
+// 4. Create auth store
 export const authStore = getAuthStore('main', {
   axios: api,
-  tokenUrl: '/oauth/token',
-  userInfoUrl: '/oauth/userinfo',
-  // Automatic OAuth token extraction (access_token, refresh_token, expires_in)
-  // Automatic Bearer header format
-  // Auto-refresh enabled by default
+  loginUrl: '/auth/login',
+  logoutUrl: '/auth/logout',
+  getUserUrl: '/users/me',
+  extractUser: 'user', // Extract user from response.data.user
 });
 
 // 5. Use in components
 function LoginForm() {
   const { login } = useAuth(authStore);
   const { user, isAuthenticated } = authStore((s) => s);
-  
+
   const handleLogin = async () => {
-    await login({ 
-      username: 'user@example.com', 
-      password: 'password' 
-    });
+    await login({ username: 'user@example.com', password: 'password' });
   };
-  
+
   if (isAuthenticated) {
     return <div>Welcome {user?.name}!</div>;
   }
-  
+
   return <button onClick={handleLogin}>Login</button>;
 }
 ```
 
-### Legacy/Django Setup (Backward Compatible)
-
-```typescript
-// Works with existing Django REST Framework patterns
-export const authStore = getAuthStore('main', {
-  axios: api,
-  loginUrl: '/api/token/login/',  // Legacy endpoint
-  logoutUrl: '/api/token/logout/',
-  getUserUrl: '/api/users/me/',
-  extractToken: (data) => data.auth_token, // Django field name
-  formatAuthHeader: (token) => `Token ${token}`, // Django format
-});
-```
-
-## Use Cases
-
-### OAuth 2.0 Provider Integration
-
-```typescript
-// Works with Auth0, Google, GitHub, or any OAuth 2.0 provider
-const auth0Store = getAuthStore('auth0', {
-  axios: api,
-  tokenUrl: 'https://your-domain.auth0.com/oauth/token',
-  userInfoUrl: 'https://your-domain.auth0.com/userinfo',
-  autoRefresh: true,
-  refreshThreshold: 300000, // Refresh 5 minutes before expiry
-  onTokenRefresh: (tokens) => {
-    console.log('Token refreshed, expires at:', new Date(tokens.expiresAt));
-  }
-});
-```
-
-### JWT Token Support
-
-```typescript
-// Automatic JWT expiration detection
-const jwtStore = getAuthStore('jwt', {
-  axios: api,
-  tokenUrl: '/api/auth/login',
-  extractTokens: (data) => {
-    const payload = JSON.parse(atob(data.access_token.split('.')[1]));
-    return {
-      accessToken: data.access_token,
-      expiresAt: payload.exp * 1000, // JWT exp is in seconds
-      tokenType: 'Bearer'
-    };
-  }
-});
-```
-
-### Multiple APIs with Different Authentication
+## Cookie Authentication
 
-```typescript
-const internalApi = axios.create({ baseURL: 'https://internal.app.com' });
-const partnerApi = axios.create({ baseURL: 'https://partner.api.com' });
-
-// Internal API uses legacy Token authentication
-const internalAuth = getAuthStore('internal', {
-  axios: internalApi,
-  loginUrl: '/api/token/login/',
-  extractToken: (data) => data.auth_token,
-  formatAuthHeader: (token) => `Token ${token}`,
-});
-
-// Partner API uses OAuth 2.0 Bearer authentication
-const partnerAuth = getAuthStore('partner', {
-  axios: partnerApi,
-  tokenUrl: '/oauth/token',
-  userInfoUrl: '/oauth/userinfo',
-  // Uses Bearer tokens and auto-refresh by default
-});
-```
-
-### Custom Storage Configuration
+For httpOnly cookie-based authentication (more secure against XSS):
 
 ```typescript
 const authStore = getAuthStore('main', {
   axios: api,
-  tokenUrl: '/oauth/token',
-  persistence: {
+  loginUrl: '/auth/login',
+  logoutUrl: '/auth/logout',
+  authCheckUrl: '/auth/check', // Required for cookie auth
+
+  cookieAuth: {
     enabled: true,
-    storage: sessionStorage, // Use sessionStorage instead of localStorage
-    tokenKey: 'access_token', // OAuth standard (default)
-    refreshTokenKey: 'refresh_token',
-    userKey: 'user_profile',
-    expiryKey: 'token_expires_at',
+    csrf: {
+      enabled: true,
+      headerName: 'X-CSRFToken',
+      cookieName: 'csrftoken',
+    },
   },
 });
-```
-
-### SSR/No Persistence
 
-```typescript
-const authStore = getAuthStore('main', {
-  axios: api,
-  tokenUrl: '/oauth/token',
-  persistence: {
-    enabled: false, // Disable persistence for SSR
-  },
-});
+// Check authentication status (reads httpOnly cookie server-side)
+const { checkAuth } = useAuth(authStore);
+const isAuthenticated = await checkAuth();
 ```
 
-## Integration with zustand-crud-registry
-
-Works seamlessly with [@jasperoosthoek/zustand-crud-registry](https://github.com/jasperoosthoek/zustand-crud-registry):
+## Error Handling
 
 ```typescript
-import { createStoreRegistry } from '@jasperoosthoek/zustand-crud-registry';
-import { createAuthRegistry } from '@jasperoosthoek/zustand-auth-registry';
-
-// Shared axios instance
-const api = axios.create({ baseURL: 'https://api.example.com' });
+import { AuthError, AuthErrorCode } from '@jasperoosthoek/zustand-auth-registry';
 
-// Auth manages authentication with auto-refresh
-const auth = getAuthStore('main', { 
-  axios: api, 
-  tokenUrl: '/oauth/token',
-  autoRefresh: true 
+const authStore = getAuthStore('main', {
+  // ...
+  onError: (error) => {
+    if (AuthError.isAuthError(error)) {
+      switch (error.code) {
+        case AuthErrorCode.INVALID_CREDENTIALS:
+          alert('Invalid username or password');
+          break;
+        case AuthErrorCode.TOKEN_EXPIRED:
+          // Token expired, user needs to login again
+          break;
+        case AuthErrorCode.NETWORK_ERROR:
+          alert('Network error, please try again');
+          break;
+      }
+    }
+  },
 });
-
-// CRUD uses the same authenticated axios
-const getCrudStore = createStoreRegistry<{ user: User; post: Post }>();
-const users = getCrudStore('user', { axios: api, route: '/users' });
-
-// Login first, then use CRUD
-const { login } = useAuth(auth);
-const { list, getList } = useCrud(users);
-
-await login({ username: '...', password: '...' });
-await getList(); // Authenticated request with auto-refreshed tokens
 ```
 
 ## API Reference
 
-### `createAuthRegistry<Models>()`
-
-Creates a registry function for type-safe auth stores.
+### `AuthConfig<U>`
 
 ```typescript
-type Models = {
-  main: MainUser;
-  admin: AdminUser;
-};
-
-const getAuthStore = createAuthRegistry<Models>();
-```
-
-### `getAuthStore(key, config)`
+type AuthConfig<U> = {
+  axios: AxiosInstance;
 
-Creates or retrieves an auth store.
+  // Endpoints
+  loginUrl: string;
+  logoutUrl?: string;
+  refreshUrl?: string;
+  getUserUrl?: string;
+  authCheckUrl?: string; // For cookie auth
 
-**Parameters:**
-- `key`: Unique identifier for the store
-- `config`: Authentication configuration
+  // Token extraction from login response
+  extractTokens?: (data: any) => TokenData;
 
-**Returns:** Auth store with Zustand state and config metadata
+  // User extraction (function or string key)
+  extractUser?: ((data: any) => U | null) | string;
 
-### `AuthConfig<U>`
+  // Auth header format (default: "Bearer {token}")
+  formatAuthHeader?: (token: string, tokenType?: string) => string;
 
-Configuration object for authentication.
+  // Auto-refresh
+  autoRefresh?: boolean;        // Default: true
+  refreshThreshold?: number;    // Default: 300000 (5 minutes)
+
+  // Cookie auth
+  cookieAuth?: {
+    enabled: boolean;
+    csrf?: {
+      enabled: boolean;
+      headerName?: string;  // Default: 'X-CSRFToken'
+      cookieName?: string;  // Default: 'csrftoken'
+    };
+  };
 
-```typescript
-type AuthConfig<U> = {
-  // Required
-  axios: AxiosInstance;
-  
-  // OAuth 2.0 endpoints (recommended)
-  tokenUrl?: string;           // POST /oauth/token
-  revokeUrl?: string;          // POST /oauth/revoke  
-  userInfoUrl?: string;        // GET /oauth/userinfo
-  
-  // Legacy endpoints (backward compatibility)
-  loginUrl?: string;           // POST /api/token/login/
-  logoutUrl?: string;          // POST /api/token/logout/
-  getUserUrl?: string;         // GET /api/users/me/
-  
-  // OAuth 2.0 token extraction (automatic if not specified)
-  extractTokens?: (data: any) => TokenData;
-  
-  // Legacy token extraction (backward compatibility)
-  extractToken?: (data: any) => string;
-  
-  // Token formatting (defaults to Bearer)
-  formatAuthHeader?: (token: string, tokenType?: string) => string;
-  
-  // OAuth 2.0 features
-  autoRefresh?: boolean;       // Default: true
-  refreshThreshold?: number;   // Default: 300000ms (5 minutes)
-  
-  // Storage configuration
+  // Persistence
   persistence?: {
-    enabled?: boolean;         // Default: true
-    storage?: Storage;         // Default: localStorage
-    tokenKey?: string;         // Default: 'token'
-    refreshTokenKey?: string;  // Default: 'refresh_token'
-    userKey?: string;          // Default: 'user'
-    expiryKey?: string;        // Default: 'expires_at'
+    enabled: boolean;       // Default: false
+    storage?: Storage;      // Default: localStorage
+    tokenKey?: string;
+    refreshTokenKey?: string;
+    userKey?: string;
+    expiryKey?: string;
   };
-  
-  // Event callbacks
+
+  // Callbacks
   onError?: (error: any) => void;
   onLogin?: (user: U) => void;
   onLogout?: () => void;
-  onTokenRefresh?: (tokens: TokenData) => void;
 };
 ```
 
 ### `TokenData`
 
-OAuth 2.0 compliant token structure.
-
 ```typescript
 type TokenData = {
-  accessToken: string;      // OAuth 2.0 standard
-  refreshToken?: string;    // For token renewal
-  expiresAt?: number;      // Timestamp for expiration
-  tokenType: string;       // 'Bearer' (default) or custom
-  scope?: string[];        // OAuth scope support
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+  tokenType: string;  // Default: 'Bearer'
 };
 ```
 
 ### `useAuth(store)`
 
-React hook for authentication actions.
-
-**Returns:**
 ```typescript
-{
-  login: (credentials: Record<string, string>, callback?: () => void) => Promise<void>;
-  logout: () => Promise<void>;
-  getCurrentUser: () => Promise<void>;
-  refreshTokens: () => Promise<boolean>; // OAuth 2.0 token refresh
-}
+const { login, logout, getCurrentUser, refreshTokens, checkAuth } = useAuth(authStore);
 ```
 
-### Auth Store State
+- `login(credentials, callback?)` - Login with credentials
+- `logout()` - Logout and clear tokens
+- `getCurrentUser()` - Fetch current user
+- `refreshTokens()` - Refresh access token
+- `checkAuth()` - Check cookie authentication status
 
-Access auth state using the store:
+### Auth Store State
 
 ```typescript
-const { user, token, tokens, isAuthenticated } = authStore((s) => s);
+const { user, tokens, isAuthenticated, setBearerToken, setTokens } = authStore((s) => s);
 ```
 
 **State:**
-- `user: U | null` - Current user object
-- `token: string` - Authentication token (backward compatibility)
-- `tokens: TokenData | null` - OAuth 2.0 token structure
-- `isAuthenticated: boolean` - Whether user is authenticated (based on valid token)
-
-**Actions:**
-- `setToken(token: string)` - Set authentication token (backward compatibility)
-- `setTokens(tokens: TokenData)` - Set OAuth 2.0 tokens
-- `setUser(user: U)` - Set user object
-- `unsetUser()` - Clear user and tokens (logout)
-- `isTokenExpired(): boolean` - Check if current token is expired
-
-## Migration Guide
-
-### From Legacy to OAuth 2.0
+- `user: U | null` - Current user
+- `tokens: TokenData | null` - Token data (access token, refresh token, etc.)
+- `isAuthenticated: boolean` - Authentication status
 
-**Step 1: No changes required (existing code continues to work)**
-```typescript
-// Existing configurations work unchanged
-const authStore = getAuthStore('main', {
-  loginUrl: '/api/token/login/',
-  extractToken: (data) => data.auth_token,
-  formatAuthHeader: (token) => `Token ${token}`
-});
-```
-
-**Step 2: Gradual OAuth adoption**
-```typescript
-// Start using OAuth endpoints while keeping legacy token extraction
-const authStore = getAuthStore('main', {
-  tokenUrl: '/oauth/token',           // OAuth endpoint
-  extractToken: (data) => data.auth_token, // Legacy extraction
-  formatAuthHeader: (token) => `Token ${token}` // Legacy headers
-});
-```
-
-**Step 3: Full OAuth 2.0**
-```typescript
-// Complete OAuth 2.0 implementation
-const authStore = getAuthStore('main', {
-  tokenUrl: '/oauth/token',
-  revokeUrl: '/oauth/revoke',
-  userInfoUrl: '/oauth/userinfo',
-  // OAuth token extraction and Bearer headers are automatic
-  autoRefresh: true,
-  refreshThreshold: 300000 // 5 minutes
-});
-```
-
-## Development
-
-See [SETUP.md](./SETUP.md) for detailed setup and development instructions.
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Test (67 tests, 100% pass rate)
-npm test
-
-# Coverage
-npm run test:coverage
-```
-
-## OAuth 2.0 Compliance
-
-This library implements OAuth 2.0 (RFC 6749) standards with Bearer Token Authentication (RFC 6750), token refresh flows, proper token lifecycle management, and standard field names. For detailed implementation information and future roadmap, see [docs/OAUTH_ROADMAP.md](./docs/OAUTH_ROADMAP.md).
+**Methods:**
+- `setBearerToken(token)` - Convenience method for simple Bearer token auth
+- `setTokens(tokenData)` - Set full token data (access, refresh, expiry)
+- `setUser(user)` - Set user
+- `unsetUser()` - Clear user and tokens
 
 ## Related Projects
 
@@ -401,7 +219,3 @@ This library implements OAuth 2.0 (RFC 6749) standards with Bearer Token Authent
 ## License
 
 MIT
-
-## Author
-
-Jasper Oosthoek

package/dist/authConfig.d.ts

@@ -4,29 +4,30 @@ export type TokenData = {
     refreshToken?: string;
     expiresAt?: number;
     tokenType: string;
-    scope?: string[];
 };
-export type TokenExtractor = (data: any) => string | TokenData;
 export type AuthConfig<U> = {
     axios: AxiosInstance;
-    tokenUrl?: string;
-    revokeUrl?: string;
-    userInfoUrl?: string;
-    loginUrl?: string;
+    loginUrl: string;
     logoutUrl?: string;
+    refreshUrl?: string;
     getUserUrl?: string;
+    authCheckUrl?: string;
     extractTokens?: (data: any) => TokenData;
-    extractAccessToken?: (data: any) => string;
-    extractRefreshToken?: (data: any) => string | undefined;
-    extractExpiresIn?: (data: any) => number | undefined;
-    extractTokenType?: (data: any) => string;
-    extractScope?: (data: any) => string[] | undefined;
-    extractToken?: (data: any) => string;
+    extractUser?: ((data: any) => U | null) | string;
     formatAuthHeader?: (token: string, tokenType?: string) => string;
     autoRefresh?: boolean;
     refreshThreshold?: number;
+    cookieAuth?: {
+        enabled: boolean;
+        csrf?: {
+            enabled: boolean;
+            headerName?: string;
+            cookieName?: string;
+            getToken?: () => string | null;
+        };
+    };
     persistence?: {
-        enabled?: boolean;
+        enabled: boolean;
         storage?: Storage;
         tokenKey?: string;
         refreshTokenKey?: string;
@@ -36,21 +37,27 @@ export type AuthConfig<U> = {
     onError?: (error: any) => void;
     onLogin?: (user: U) => void;
     onLogout?: () => void;
-    onTokenRefresh?: (tokens: TokenData) => void;
 };
 export type ValidatedAuthConfig<U> = {
     axios: AxiosInstance;
-    tokenUrl: string;
-    revokeUrl?: string;
-    userInfoUrl?: string;
-    loginUrl?: string;
+    loginUrl: string;
     logoutUrl?: string;
+    refreshUrl?: string;
     getUserUrl?: string;
+    authCheckUrl?: string;
     extractTokens: (data: any) => TokenData;
-    extractToken?: (data: any) => string;
+    extractUser?: (data: any) => U | null;
     formatAuthHeader: (token: string, tokenType?: string) => string;
     autoRefresh: boolean;
     refreshThreshold: number;
+    cookieAuth?: {
+        enabled: boolean;
+        csrf: {
+            enabled: boolean;
+            headerName: string;
+            getToken: () => string | null;
+        };
+    };
     persistence: {
         enabled: boolean;
         storage: Storage;
@@ -62,6 +69,5 @@ export type ValidatedAuthConfig<U> = {
     onError?: (error: any) => void;
     onLogin?: (user: U) => void;
     onLogout?: () => void;
-    onTokenRefresh?: (tokens: TokenData) => void;
 };
 export declare const validateAuthConfig: <U>(config: AuthConfig<U>) => ValidatedAuthConfig<U>;

package/dist/authStore.d.ts

@@ -1,15 +1,15 @@
 import { StoreApi, UseBoundStore } from 'zustand';
 import { ValidatedAuthConfig, TokenData } from './authConfig';
 export type AuthState<U> = {
-    isAuthenticated: boolean;
+    isAuthenticated: boolean | null;
     user: U | null;
     tokens: TokenData | null;
     setTokens: (tokens: TokenData) => void;
+    setBearerToken: (token: string) => void;
+    setAuthenticated: (authenticated: boolean) => void;
     setUser: (user: U) => void;
     unsetUser: () => void;
     isTokenExpired: () => boolean;
-    token: string;
-    setToken: (token: string) => void;
 };
 export type AuthStore<U> = UseBoundStore<StoreApi<AuthState<U>>> & {
     config: ValidatedAuthConfig<U>;

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Authentication error codes
+ */
+export declare enum AuthErrorCode {
+    INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+    TOKEN_EXPIRED = "TOKEN_EXPIRED",
+    TOKEN_INVALID = "TOKEN_INVALID",
+    REFRESH_FAILED = "REFRESH_FAILED",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    USER_NOT_FOUND = "USER_NOT_FOUND",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    CSRF_TOKEN_MISSING = "CSRF_TOKEN_MISSING",
+    FORBIDDEN = "FORBIDDEN",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Typed authentication error
+ */
+export declare class AuthError extends Error {
+    code: AuthErrorCode;
+    originalError?: any;
+    constructor(code: AuthErrorCode, originalError?: any, message?: string);
+    /**
+     * Convert error to JSON (excludes originalError in production)
+     */
+    toJSON(): {
+        code: AuthErrorCode;
+        message: string;
+        name: string;
+    };
+    /**
+     * Check if error is an AuthError
+     */
+    static isAuthError(error: any): error is AuthError;
+}
+/**
+ * Create typed AuthError from any error
+ */
+export declare function createAuthError(error: any): AuthError;

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './authConfig';
 export * from './authStore';
 export * from './createAuthRegistry';
 export * from './useAuth';
+export * from './errors';