@classic-homes/auth 0.1.0

package/README.md

@@ -0,0 +1,255 @@
+# @classic-homes/auth
+
+Framework-agnostic authentication core with Svelte bindings for the Classic Theme design system.
+
+## Features
+
+- JWT-based authentication with automatic token refresh
+- SSO (Single Sign-On) support with configurable providers
+- Multi-factor authentication (MFA/TOTP) support
+- Pluggable storage adapter (localStorage, sessionStorage, or custom)
+- Svelte reactive stores for authentication state
+- Route guards for protected pages
+- TypeScript-first with full type safety
+
+## Installation
+
+```bash
+npm install @classic-homes/auth
+```
+
+## Quick Start
+
+### 1. Initialize Authentication
+
+In your app's entry point (e.g., `hooks.client.ts` for SvelteKit):
+
+```typescript
+import { initAuth } from '@classic-homes/auth';
+
+initAuth({
+  baseUrl: 'https://api.example.com',
+  storage: {
+    getItem: (key) => localStorage.getItem(key),
+    setItem: (key, value) => localStorage.setItem(key, value),
+    removeItem: (key) => localStorage.removeItem(key),
+  },
+  onAuthError: (error) => {
+    console.error('Auth error:', error);
+  },
+});
+```
+
+### 2. Use the Auth Store (Svelte)
+
+```svelte
+<script lang="ts">
+  import { authStore, authActions } from '@classic-homes/auth/svelte';
+
+  async function handleLogin() {
+    await authActions.login({
+      email: 'user@example.com',
+      password: 'password123',
+    });
+  }
+
+  async function handleLogout() {
+    await authActions.logout();
+  }
+</script>
+
+{#if $authStore.isAuthenticated}
+  <p>Welcome, {$authStore.user?.email}</p>
+  <button onclick={handleLogout}>Logout</button>
+{:else}
+  <button onclick={handleLogin}>Login</button>
+{/if}
+```
+
+### 3. Protect Routes
+
+```typescript
+// src/routes/dashboard/+page.ts
+import { authGuard } from '@classic-homes/auth/svelte';
+
+export const load = authGuard({
+  redirectTo: '/login',
+});
+```
+
+## API Reference
+
+### Core Exports
+
+```typescript
+import {
+  // Initialization
+  initAuth,
+  getAuthConfig,
+
+  // Service
+  authService,
+  AuthService,
+
+  // API
+  authApi,
+
+  // Types
+  type User,
+  type AuthTokens,
+  type LoginCredentials,
+  type RegisterData,
+  type AuthConfig,
+} from '@classic-homes/auth';
+```
+
+### Svelte Exports
+
+```typescript
+import {
+  // Store
+  authStore,
+  isAuthenticated,
+  currentUser,
+
+  // Actions
+  authActions,
+
+  // Guards
+  authGuard,
+  roleGuard,
+} from '@classic-homes/auth/svelte';
+```
+
+## Configuration Options
+
+```typescript
+interface AuthConfig {
+  /** Base URL for the auth API */
+  baseUrl: string;
+
+  /** Storage adapter for tokens */
+  storage?: {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+  };
+
+  /** SSO configuration */
+  sso?: {
+    enabled: boolean;
+    provider: string;
+    authorizeUrl?: string;
+    tokenUrl?: string;
+  };
+
+  /** Callback when auth errors occur */
+  onAuthError?: (error: Error) => void;
+
+  /** Custom headers for API requests */
+  headers?: Record<string, string>;
+}
+```
+
+## Auth Actions
+
+The `authActions` object provides methods for authentication operations:
+
+```typescript
+// Login with email/password
+await authActions.login({ email, password, rememberMe });
+
+// Register new user
+await authActions.register({ email, password, fullName });
+
+// Logout
+await authActions.logout();
+
+// Refresh session
+await authActions.refreshSession();
+
+// Change password
+await authActions.changePassword({ currentPassword, newPassword });
+
+// MFA operations
+await authActions.verifyMfa({ code, trustDevice });
+await authActions.setupMfa({ secret, code });
+await authActions.disableMfa({ password });
+
+// SSO
+await authActions.initiateSSO();
+await authActions.handleSSOCallback(code);
+```
+
+## Auth Store State
+
+```typescript
+interface AuthState {
+  user: User | null;
+  tokens: AuthTokens | null;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  error: string | null;
+  mfaRequired: boolean;
+  mfaToken: string | null;
+}
+```
+
+## Route Guards
+
+### Basic Auth Guard
+
+```typescript
+import { authGuard } from '@classic-homes/auth/svelte';
+
+export const load = authGuard({
+  redirectTo: '/login',
+  returnUrl: true, // Append ?returnUrl= to redirect
+});
+```
+
+### Role-Based Guard
+
+```typescript
+import { roleGuard } from '@classic-homes/auth/svelte';
+
+export const load = roleGuard({
+  roles: ['admin', 'manager'],
+  redirectTo: '/unauthorized',
+});
+```
+
+## Using with @classic-homes/theme-svelte
+
+The auth package integrates with the form validation from `@classic-homes/theme-svelte`:
+
+```svelte
+<script lang="ts">
+  import { useForm, loginSchema } from '@classic-homes/theme-svelte';
+  import { authActions } from '@classic-homes/auth/svelte';
+
+  const form = useForm({
+    schema: loginSchema,
+    initialValues: {
+      email: '',
+      password: '',
+      rememberMe: false,
+    },
+    onSubmit: async (data) => {
+      await authActions.login(data);
+    },
+  });
+</script>
+
+<form onsubmit={form.handleSubmit}>
+  <input bind:value={form.data.email} />
+  {#if form.errors.email}
+    <span class="error">{form.errors.email}</span>
+  {/if}
+  <!-- ... -->
+</form>
+```
+
+## License
+
+MIT