@classic-homes/auth 0.1.43 → 0.1.44

package/dist/svelte/index.d.ts

@@ -1,4 +1,8 @@
-import { A as AuthState, U as User } from '../types-DGN45Uih.js';
+import { f as AuthState, U as User, A as AuthConfig } from '../types-Ct5g1Nbj.js';
+export { i as initAuth, a as isInitialized } from '../types-Ct5g1Nbj.js';
+import { a as authService } from '../user-utils-BtLu_jhF.js';
+export { R as RoleDeniedError, f as formatUserRoles, c as getAvatarFallback, g as getDisplayName, e as getGreeting, d as getUserEmail, b as getUserInitials, i as isRoleDeniedError } from '../user-utils-BtLu_jhF.js';
+import { RequestEvent, Handle } from '@sveltejs/kit';
 
 /**
  * Auth Store
@@ -53,6 +57,14 @@ declare class AuthStore {
     logoutWithSSO(): Promise<{
         ssoLogoutUrl?: string;
     }>;
+    /**
+     * Handle session expiration (e.g., token refresh failure).
+     * Clears auth state and calls the onSessionExpired callback if configured.
+     *
+     * Use this instead of logout() when the session expires unexpectedly,
+     * to trigger different handling (e.g., redirect with error message).
+     */
+    handleSessionExpired(): void;
     /**
      * Check if user has a specific permission.
      */
@@ -81,6 +93,22 @@ declare class AuthStore {
      * Re-hydrate state from storage (useful after config changes).
      */
     rehydrate(): void;
+    /**
+     * Reset the store to initial state and clear all storage.
+     * Primarily intended for testing scenarios where auth needs to be fully reset.
+     *
+     * Unlike logout(), this also clears all subscribers and doesn't
+     * dispatch events or call config callbacks.
+     *
+     * @example
+     * ```typescript
+     * // In test setup/teardown
+     * beforeEach(() => {
+     *   authStore.reset();
+     * });
+     * ```
+     */
+    reset(): void;
 }
 /** Singleton auth store instance */
 declare const authStore: AuthStore;
@@ -96,6 +124,7 @@ declare const authActions: {
     logoutWithSSO: () => Promise<{
         ssoLogoutUrl?: string;
     }>;
+    handleSessionExpired: () => void;
     hasPermission: (permission: string) => boolean;
     hasRole: (role: string) => boolean;
     hasAnyRole: (roles: string[]) => boolean;
@@ -103,6 +132,7 @@ declare const authActions: {
     hasAnyPermission: (permissions: string[]) => boolean;
     hasAllPermissions: (permissions: string[]) => boolean;
     rehydrate: () => void;
+    reset: () => void;
 };
 /**
  * Derived stores for common auth values.
@@ -197,19 +227,55 @@ declare function requirePermission(permissions: string | string[], requireAll?:
 /**
  * Utility to protect a load function.
  *
+ * **Important:** This returns a plain object with `{ redirect: string }` when auth fails,
+ * NOT a SvelteKit redirect exception. You must handle the redirect in your load function
+ * or use `checkAuth()` directly with SvelteKit's `redirect()` function.
+ *
+ * @returns A wrapped load function that returns either:
+ *   - Your load function's result (when authenticated)
+ *   - `{ redirect: string }` object (when not authenticated)
+ *
  * @example
  * ```typescript
+ * // Option 1: Handle redirect in +page.svelte
  * // In +page.ts
  * import { protectedLoad } from '@classic-homes/auth/svelte';
  *
  * export const load = protectedLoad(
  *   { roles: ['admin'] },
  *   async ({ fetch }) => {
- *     // This only runs if auth check passes
  *     const data = await fetch('/api/admin/data');
  *     return { data };
  *   }
  * );
+ *
+ * // In +page.svelte - check for redirect property
+ * <script>
+ *   export let data;
+ *   import { goto } from '$app/navigation';
+ *   import { onMount } from 'svelte';
+ *
+ *   onMount(() => {
+ *     if ('redirect' in data) goto(data.redirect);
+ *   });
+ * </script>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Option 2 (Recommended): Use checkAuth with SvelteKit's redirect
+ * // In +page.ts
+ * import { checkAuth } from '@classic-homes/auth/svelte';
+ * import { redirect } from '@sveltejs/kit';
+ *
+ * export async function load({ fetch }) {
+ *   const result = checkAuth({ roles: ['admin'] });
+ *   if (!result.allowed) {
+ *     throw redirect(302, result.redirectTo ?? '/login');
+ *   }
+ *   const data = await fetch('/api/admin/data');
+ *   return { data };
+ * }
  * ```
  */
 declare function protectedLoad<T>(options: AuthGuardOptions, loadFn: (event: {
@@ -220,4 +286,371 @@ declare function protectedLoad<T>(options: AuthGuardOptions, loadFn: (event: {
     redirect: string;
 }>;
 
-export { type AuthGuardOptions, type AuthGuardResult, AuthState, User, authActions, authStore, checkAuth, createAuthGuard, currentUser, isAuthenticated, protectedLoad, requireAuth, requirePermission, requireRole };
+/**
+ * Auth Client Factory
+ *
+ * Simplified initialization API that bundles configuration and rehydration.
+ * Use this for a one-liner auth setup in your app.
+ */
+
+/**
+ * Options for createAuthClient, extending AuthConfig with client-specific options.
+ */
+interface CreateAuthClientOptions extends AuthConfig {
+    /**
+     * Automatically rehydrate auth state from storage on creation.
+     * Set to false if you want to control when rehydration happens.
+     * @default true
+     */
+    autoRehydrate?: boolean;
+}
+/**
+ * Return type for createAuthClient.
+ */
+interface AuthClient {
+    /** The auth store (Svelte store contract) */
+    authStore: typeof authStore;
+    /** Actions for modifying auth state */
+    authActions: typeof authActions;
+    /** Service for API calls */
+    authService: typeof authService;
+    /** Derived store for isAuthenticated */
+    isAuthenticated: typeof isAuthenticated;
+    /** Derived store for currentUser */
+    currentUser: typeof currentUser;
+}
+/**
+ * Create and initialize the auth client.
+ *
+ * This is a convenience function that:
+ * 1. Initializes the auth configuration (if not already done)
+ * 2. Rehydrates auth state from storage (unless disabled)
+ * 3. Returns all auth utilities in one object
+ *
+ * @param options - Configuration options
+ * @returns Auth client with stores and services
+ *
+ * @example
+ * ```typescript
+ * // In your app's auth setup file (e.g., lib/auth.ts)
+ * import { createAuthClient } from '@classic-homes/auth/svelte';
+ * import { PUBLIC_API_URL } from '$env/static/public';
+ *
+ * export const {
+ *   authStore,
+ *   authActions,
+ *   authService,
+ *   isAuthenticated,
+ *   currentUser,
+ * } = createAuthClient({
+ *   baseUrl: PUBLIC_API_URL,
+ *   storageKey: 'my_app_auth',
+ *   sso: { enabled: true, provider: 'authentik' },
+ *   onSessionExpired: (currentPath) => {
+ *     window.location.href = `/login?redirect=${encodeURIComponent(currentPath)}`;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a Svelte component
+ * <script>
+ *   import { isAuthenticated, currentUser } from '$lib/auth';
+ * </script>
+ *
+ * {#if $isAuthenticated}
+ *   <p>Welcome, {$currentUser?.firstName}</p>
+ * {/if}
+ * ```
+ */
+declare function createAuthClient(options: CreateAuthClientOptions): AuthClient;
+
+/**
+ * Navigation Filtering Utilities
+ *
+ * Filter navigation items based on user roles and permissions.
+ * Works with any navigation structure that includes roles/permissions arrays.
+ */
+
+/**
+ * Interface for items that can be filtered by role/permission.
+ * Navigation items should include these optional arrays to restrict access.
+ */
+interface RoleRestrictedItem {
+    /** Optional item identifier */
+    id?: string;
+    /**
+     * Roles that can see this item.
+     * By default, user needs ANY of these roles (use requireAllRoles for ALL).
+     * If empty/undefined, item is visible to all authenticated users.
+     */
+    roles?: string[];
+    /**
+     * Permissions that can see this item.
+     * By default, user needs ANY of these permissions (use requireAllPermissions for ALL).
+     * If empty/undefined, item is visible without permission check.
+     */
+    permissions?: string[];
+    /** Allow additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for filtering behavior.
+ */
+interface NavFilterOptions {
+    /**
+     * If true, user needs ALL specified roles to see item (default: false = any role)
+     */
+    requireAllRoles?: boolean;
+    /**
+     * If true, user needs ALL specified permissions to see item (default: false = any permission)
+     */
+    requireAllPermissions?: boolean;
+    /**
+     * If true, items without roles/permissions are hidden for unauthenticated users.
+     * If false (default), items without restrictions are visible to everyone.
+     */
+    hideUnrestrictedForGuests?: boolean;
+}
+/**
+ * Filter navigation items based on user roles and permissions.
+ *
+ * @param items - Array of navigation items
+ * @param user - Current user (null for unauthenticated)
+ * @param options - Filter options
+ * @returns Filtered array of items the user can access
+ *
+ * @example
+ * ```typescript
+ * const navItems = [
+ *   { id: 'dashboard', label: 'Dashboard' },
+ *   { id: 'users', label: 'Users', roles: ['admin', 'manager'] },
+ *   { id: 'settings', label: 'Settings', permissions: ['settings:read'] },
+ * ];
+ *
+ * const filtered = filterByAccess(navItems, user);
+ * // Returns items the user can see based on their roles/permissions
+ * ```
+ */
+declare function filterByAccess<T extends RoleRestrictedItem>(items: T[], user: User | null, options?: NavFilterOptions): T[];
+/**
+ * Filter navigation sections (groups with nested items).
+ * Removes empty sections after filtering items.
+ *
+ * @param sections - Array of navigation sections with items
+ * @param user - Current user (null for unauthenticated)
+ * @param options - Filter options
+ * @returns Filtered sections with non-empty items
+ *
+ * @example
+ * ```typescript
+ * const sections = [
+ *   {
+ *     title: 'Main',
+ *     items: [
+ *       { id: 'dashboard', label: 'Dashboard' },
+ *       { id: 'analytics', label: 'Analytics', roles: ['admin'] },
+ *     ],
+ *   },
+ *   {
+ *     title: 'Admin',
+ *     items: [
+ *       { id: 'users', label: 'Users', roles: ['admin'] },
+ *     ],
+ *   },
+ * ];
+ *
+ * const filtered = filterNavSections(sections, user);
+ * // Admin section removed entirely if user isn't admin
+ * ```
+ */
+declare function filterNavSections<TItem extends RoleRestrictedItem, TSection extends {
+    items: TItem[];
+}>(sections: TSection[], user: User | null, options?: NavFilterOptions): TSection[];
+/**
+ * Check if a user can access a specific item.
+ * Useful for conditional rendering of individual items.
+ *
+ * @param item - The item to check access for
+ * @param user - Current user (null for unauthenticated)
+ * @param options - Filter options
+ * @returns true if user can access the item
+ *
+ * @example
+ * ```typescript
+ * const adminItem = { id: 'admin', roles: ['admin'] };
+ *
+ * if (canAccess(adminItem, user)) {
+ *   // Show admin link
+ * }
+ * ```
+ */
+declare function canAccess(item: RoleRestrictedItem, user: User | null, options?: NavFilterOptions): boolean;
+/**
+ * Create a pre-configured filter function with fixed options.
+ * Useful when you want consistent filtering behavior across the app.
+ *
+ * @param defaultOptions - Default filter options
+ * @returns A filter function with the options pre-applied
+ *
+ * @example
+ * ```typescript
+ * // In a config file
+ * export const filterNav = createNavFilter({ requireAllRoles: false });
+ *
+ * // In components
+ * const filtered = filterNav(items, user);
+ * ```
+ */
+declare function createNavFilter(defaultOptions?: NavFilterOptions): <T extends RoleRestrictedItem>(items: T[], user: User | null, options?: NavFilterOptions) => T[];
+
+/**
+ * SvelteKit Auth Hook
+ *
+ * Server-side authentication middleware for SvelteKit.
+ * Use this in hooks.server.ts to protect routes at the server level.
+ */
+
+/**
+ * Options for the auth hook.
+ */
+interface AuthHookOptions {
+    /**
+     * Path to redirect unauthenticated users.
+     * @default '/login'
+     */
+    loginPath?: string;
+    /**
+     * Routes that always require authentication.
+     * Matched against pathname using regex.
+     * If not specified and publicRoutes is set, all non-public routes require auth.
+     *
+     * @example [/^\/dashboard/, /^\/api\/protected/]
+     */
+    protectedRoutes?: RegExp[];
+    /**
+     * Routes that don't require authentication.
+     * Matched against pathname using regex.
+     *
+     * @example [/^\/auth\//, /^\/public\//]
+     * @default [/^\/auth\//, /^\/api\/auth\//]
+     */
+    publicRoutes?: RegExp[];
+    /**
+     * Cookie name where the auth token is stored.
+     * The hook checks for this cookie to determine if user is authenticated.
+     *
+     * @default 'classic_auth'
+     */
+    cookieName?: string;
+    /**
+     * Alternative: header name to check for auth token.
+     * Useful for API routes that use Authorization header.
+     */
+    headerName?: string;
+    /**
+     * Query parameter to use for redirect URL.
+     * @default 'redirect'
+     */
+    redirectParam?: string;
+    /**
+     * Custom function to determine if a request is authenticated.
+     * Use this for advanced auth checks (e.g., validating token with API).
+     *
+     * @param event - The SvelteKit request event
+     * @returns true if authenticated, false otherwise
+     */
+    isAuthenticated?: (event: RequestEvent) => boolean | Promise<boolean>;
+    /**
+     * Custom function to handle unauthenticated requests.
+     * By default, redirects to loginPath with redirect parameter.
+     *
+     * @param event - The SvelteKit request event
+     * @returns Response to send (typically a redirect)
+     */
+    onUnauthenticated?: (event: RequestEvent) => Response | Promise<Response>;
+    /**
+     * Callback when authentication check is performed.
+     * Useful for logging or analytics.
+     */
+    onAuthCheck?: (event: RequestEvent, isAuthenticated: boolean) => void;
+}
+/**
+ * Create a SvelteKit handle function for authentication.
+ *
+ * @param options - Configuration options
+ * @returns SvelteKit Handle function
+ *
+ * @example
+ * ```typescript
+ * // src/hooks.server.ts
+ * import { createAuthHook } from '@classic-homes/auth/svelte';
+ * import { sequence } from '@sveltejs/kit/hooks';
+ *
+ * const authHook = createAuthHook({
+ *   loginPath: '/auth/login',
+ *   publicRoutes: [/^\/auth\//, /^\/api\/health/],
+ *   cookieName: 'my_app_auth',
+ * });
+ *
+ * export const handle = sequence(authHook);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom authentication check
+ * const authHook = createAuthHook({
+ *   isAuthenticated: async (event) => {
+ *     const token = event.cookies.get('auth_token');
+ *     if (!token) return false;
+ *
+ *     // Validate token with your API
+ *     const response = await fetch('/api/auth/validate', {
+ *       headers: { Authorization: `Bearer ${token}` },
+ *     });
+ *     return response.ok;
+ *   },
+ * });
+ * ```
+ */
+declare function createAuthHook(options?: AuthHookOptions): Handle;
+/**
+ * Helper to check if a pathname matches any pattern in a list.
+ *
+ * @param pathname - The pathname to check
+ * @param patterns - Array of regex patterns
+ * @returns true if pathname matches any pattern
+ */
+declare function matchesRoute(pathname: string, patterns: RegExp[]): boolean;
+/**
+ * Create common route patterns for convenience.
+ */
+declare const routePatterns: {
+    /** Match all /auth/* routes */
+    auth: RegExp;
+    /** Match all /api/* routes */
+    api: RegExp;
+    /** Match all /api/auth/* routes */
+    apiAuth: RegExp;
+    /** Match all /public/* routes */
+    public: RegExp;
+    /** Match all /admin/* routes */
+    admin: RegExp;
+    /** Match exact root path */
+    root: RegExp;
+    /** Match health check endpoints */
+    health: RegExp;
+    /**
+     * Create a pattern for a specific path prefix.
+     * @param prefix - Path prefix (e.g., '/dashboard')
+     */
+    prefix: (prefix: string) => RegExp;
+    /**
+     * Create a pattern for exact path match.
+     * @param path - Exact path (e.g., '/about')
+     */
+    exact: (path: string) => RegExp;
+};
+
+export { type AuthClient, type AuthGuardOptions, type AuthGuardResult, type AuthHookOptions, AuthState, type CreateAuthClientOptions, type NavFilterOptions, type RoleRestrictedItem, User, authActions, authStore, canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, currentUser, filterByAccess, filterNavSections, isAuthenticated, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns };

package/dist/svelte/index.js

@@ -1,4 +1,5 @@
-export { checkAuth, createAuthGuard, protectedLoad, requireAuth, requirePermission, requireRole } from '../chunk-IAPPE4US.js';
-export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-7M4DUK45.js';
-import '../chunk-BDIQSTES.js';
-import '../chunk-DCGC6CNV.js';
+export { canAccess, checkAuth, createAuthClient, createAuthGuard, createAuthHook, createNavFilter, filterByAccess, filterNavSections, matchesRoute, protectedLoad, requireAuth, requirePermission, requireRole, routePatterns } from '../chunk-YTMFXVJR.js';
+export { RoleDeniedError, formatUserRoles, getAvatarFallback, getDisplayName, getGreeting, getUserEmail, getUserInitials, isRoleDeniedError } from '../chunk-XSQYERC6.js';
+export { authActions, authStore, currentUser, isAuthenticated } from '../chunk-DSNTNK6T.js';
+import '../chunk-ES4UOD62.js';
+export { initAuth, isInitialized } from '../chunk-DCGC6CNV.js';

package/dist/testing/index.d.ts

@@ -1,5 +1,4 @@
-import { U as User, a as LoginResponse, b as LogoutResponse, c as RegisterResponse, M as MFASetupResponse, f as MFAStatus, S as Session, D as Device, d as ApiKey, i as LinkedAccount, j as SecurityEvent, h as UserPreferences, A as AuthState } from '../types-DGN45Uih.js';
-import { e as StorageAdapter, A as AuthConfig } from '../config-C-iBNu07.js';
+import { U as User, h as LoginResponse, j as LogoutResponse, k as RegisterResponse, M as MFASetupResponse, o as MFAStatus, l as Session, D as Device, m as ApiKey, s as LinkedAccount, t as SecurityEvent, q as UserPreferences, e as StorageAdapter, f as AuthState, A as AuthConfig } from '../types-Ct5g1Nbj.js';
 
 /**
  * User Fixtures

package/dist/{types-DGN45Uih.d.ts → types-Ct5g1Nbj.d.ts}

@@ -1,3 +1,103 @@
+/**
+ * Auth Configuration
+ *
+ * Manages global configuration for the auth package.
+ * Must be initialized via initAuth() before using auth services.
+ */
+interface SSOConfig {
+    /** Whether SSO is enabled */
+    enabled: boolean;
+    /** SSO provider name (e.g., 'authentik', 'okta') */
+    provider: string;
+    /** Override the default authorize URL (defaults to /auth/sso/authorize) */
+    authorizeUrl?: string;
+}
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+interface AuthConfig {
+    /** Base URL for the API (e.g., 'https://api.example.com/v1') */
+    baseUrl: string;
+    /** Custom fetch implementation (useful for SSR or testing) */
+    fetch?: typeof fetch;
+    /** Storage adapter for token persistence (defaults to localStorage in browser) */
+    storage?: StorageAdapter;
+    /** Storage key prefix for auth data */
+    storageKey?: string;
+    /** Callback when auth errors occur (e.g., for logging or analytics) */
+    onAuthError?: (error: Error) => void;
+    /** Callback when tokens are refreshed */
+    onTokenRefresh?: (tokens: {
+        accessToken: string;
+        refreshToken: string;
+    }) => void;
+    /** Callback when user is logged out (e.g., for redirect) */
+    onLogout?: () => void;
+    /**
+     * Callback when the session expires (e.g., token refresh fails).
+     * Receives the current path for redirect handling.
+     *
+     * @example
+     * ```typescript
+     * initAuth({
+     *   baseUrl: 'https://api.example.com',
+     *   onSessionExpired: (currentPath) => {
+     *     goto(`/auth/login?redirect=${encodeURIComponent(currentPath)}&error=session_expired`);
+     *   },
+     * });
+     * ```
+     */
+    onSessionExpired?: (currentPath: string) => void;
+    /** SSO configuration */
+    sso?: SSOConfig;
+}
+/**
+ * Initialize the auth package with configuration.
+ * Must be called before using any auth services.
+ *
+ * @example
+ * ```typescript
+ * import { initAuth } from '@classic-homes/auth';
+ *
+ * initAuth({
+ *   baseUrl: import.meta.env.PUBLIC_API_URL,
+ *   sso: {
+ *     enabled: true,
+ *     provider: 'authentik',
+ *   },
+ * });
+ * ```
+ */
+declare function initAuth(options: AuthConfig): void;
+/**
+ * Get the current auth configuration.
+ * Throws if initAuth() has not been called.
+ */
+declare function getConfig(): AuthConfig;
+/**
+ * Check if auth has been initialized.
+ */
+declare function isInitialized(): boolean;
+/**
+ * Reset the auth configuration (useful for testing).
+ */
+declare function resetConfig(): void;
+/**
+ * Get the default storage adapter.
+ * Returns localStorage in browser, or a no-op adapter in SSR.
+ */
+declare function getDefaultStorage(): StorageAdapter;
+/**
+ * Get the storage adapter from config or use default.
+ */
+declare function getStorage(): StorageAdapter;
+/**
+ * Get the fetch implementation from config or use global fetch.
+ */
+declare function getFetch(): typeof fetch;
+
 /**
  * Auth Types
  *
@@ -202,4 +302,4 @@ interface ResetPasswordData {
     newPassword: string;
 }
 
-export type { AuthState as A, CreateApiKeyRequest as C, Device as D, LoginCredentials as L, MFASetupResponse as M, Pagination as P, RegisterData as R, Session as S, User as U, LoginResponse as a, LogoutResponse as b, RegisterResponse as c, ApiKey as d, CreateApiKeyResponse as e, MFAStatus as f, MFAChallengeData as g, UserPreferences as h, LinkedAccount as i, SecurityEvent as j, ProfileUpdateData as k, ChangePasswordData as l, ResetPasswordData as m };
+export { type AuthConfig as A, type CreateApiKeyRequest as C, type Device as D, type LoginCredentials as L, type MFASetupResponse as M, type Pagination as P, type RegisterData as R, type SSOConfig as S, type User as U, isInitialized as a, getDefaultStorage as b, getStorage as c, getFetch as d, type StorageAdapter as e, type AuthState as f, getConfig as g, type LoginResponse as h, initAuth as i, type LogoutResponse as j, type RegisterResponse as k, type Session as l, type ApiKey as m, type CreateApiKeyResponse as n, type MFAStatus as o, type MFAChallengeData as p, type UserPreferences as q, resetConfig as r, type LinkedAccount as s, type SecurityEvent as t, type ProfileUpdateData as u, type ChangePasswordData as v, type ResetPasswordData as w };