@classic-homes/auth 0.1.43 → 0.1.44

package/dist/user-utils-BtLu_jhF.d.ts

@@ -0,0 +1,414 @@
+import { L as LoginCredentials, h as LoginResponse, j as LogoutResponse, R as RegisterData, k as RegisterResponse, U as User, u as ProfileUpdateData, l as Session, m as ApiKey, C as CreateApiKeyRequest, n as CreateApiKeyResponse, o as MFAStatus, M as MFASetupResponse, p as MFAChallengeData, D as Device, q as UserPreferences, s as LinkedAccount, t as SecurityEvent, P as Pagination } from './types-Ct5g1Nbj.js';
+
+/**
+ * Auth Service
+ *
+ * Business logic layer for authentication operations.
+ * Wraps authApi calls and provides a clean interface for components.
+ */
+
+interface LoginOptions {
+    /**
+     * Automatically update the auth store after successful login.
+     * Set to false to manually handle auth state.
+     * @default true
+     */
+    autoSetAuth?: boolean;
+    /**
+     * Required roles for login. If the user doesn't have any of these roles,
+     * a RoleDeniedError is thrown instead of completing the login.
+     * This prevents users from logging into apps they can't access.
+     *
+     * @example
+     * ```typescript
+     * await authService.login(credentials, {
+     *   allowedRoles: ['admin', 'manager', 'agent'],
+     * });
+     * ```
+     */
+    allowedRoles?: string[];
+    /**
+     * Redirect path to include in RoleDeniedError when role validation fails.
+     * Useful for redirecting to a specific error page.
+     *
+     * @example
+     * ```typescript
+     * await authService.login(credentials, {
+     *   allowedRoles: ['admin'],
+     *   onRoleDeniedRedirect: '/auth/login?error=insufficient_permissions',
+     * });
+     * ```
+     */
+    onRoleDeniedRedirect?: string;
+}
+interface MFAVerifyOptions {
+    /**
+     * Automatically update the auth store after successful MFA verification.
+     * Set to false to manually handle auth state.
+     * @default true
+     */
+    autoSetAuth?: boolean;
+    /**
+     * Required roles for login. If the user doesn't have any of these roles,
+     * a RoleDeniedError is thrown instead of completing the login.
+     */
+    allowedRoles?: string[];
+    /**
+     * Redirect path to include in RoleDeniedError when role validation fails.
+     */
+    onRoleDeniedRedirect?: string;
+}
+/**
+ * AuthService
+ *
+ * Provides a clean interface for authentication operations.
+ * Can be instantiated for testing or used via the singleton export.
+ */
+declare class AuthService {
+    /**
+     * Login with username and password.
+     * By default, automatically sets the auth state on successful login (unless MFA is required).
+     * @param credentials - Username and password
+     * @param options - Optional settings for login behavior
+     */
+    login(credentials: LoginCredentials, options?: LoginOptions): Promise<LoginResponse>;
+    /**
+     * Logout the current user.
+     * Returns SSO logout URL if applicable for SSO users.
+     */
+    logout(): Promise<LogoutResponse>;
+    /**
+     * Register a new user.
+     */
+    register(data: RegisterData): Promise<RegisterResponse>;
+    /**
+     * Request a password reset email.
+     */
+    forgotPassword(email: string): Promise<void>;
+    /**
+     * Reset password with a token.
+     */
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    /**
+     * Change the current user's password.
+     */
+    changePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Refresh the access token.
+     */
+    refreshToken(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    /**
+     * Initiate SSO login (redirects to SSO provider).
+     * @param options.callbackUrl - The URL where the SSO provider should redirect after auth
+     * @param options.redirectUrl - The final URL to redirect to after processing the callback
+     */
+    initiateSSOLogin(options?: {
+        callbackUrl?: string;
+        redirectUrl?: string;
+    }): void;
+    /**
+     * Get the current user's profile.
+     */
+    getProfile(customFetch?: typeof fetch): Promise<User>;
+    /**
+     * Update the current user's profile.
+     */
+    updateProfile(data: ProfileUpdateData): Promise<User>;
+    /**
+     * Resend email verification.
+     */
+    resendVerification(): Promise<void>;
+    /**
+     * Verify email with a token.
+     */
+    verifyEmail(token: string): Promise<{
+        message: string;
+        user?: User;
+    }>;
+    /**
+     * Get all active sessions.
+     */
+    getSessions(customFetch?: typeof fetch): Promise<{
+        sessions: Session[];
+        total: number;
+    }>;
+    /**
+     * Revoke a specific session.
+     */
+    revokeSession(sessionId: string): Promise<void>;
+    /**
+     * Revoke all sessions except the current one.
+     */
+    revokeAllSessions(): Promise<void>;
+    /**
+     * Get all API keys.
+     */
+    getApiKeys(customFetch?: typeof fetch): Promise<{
+        apiKeys: ApiKey[];
+    }>;
+    /**
+     * Create a new API key.
+     */
+    createApiKey(data: CreateApiKeyRequest): Promise<CreateApiKeyResponse>;
+    /**
+     * Revoke an API key.
+     */
+    revokeApiKey(keyId: string): Promise<void>;
+    /**
+     * Update an API key's name.
+     */
+    updateApiKey(keyId: string, name: string): Promise<void>;
+    /**
+     * Get MFA status for the current user.
+     */
+    getMFAStatus(): Promise<MFAStatus>;
+    /**
+     * Setup MFA (get QR code and backup codes).
+     */
+    setupMFA(): Promise<MFASetupResponse>;
+    /**
+     * Verify MFA setup with a code.
+     */
+    verifyMFASetup(code: string): Promise<void>;
+    /**
+     * Disable MFA.
+     */
+    disableMFA(password: string): Promise<void>;
+    /**
+     * Regenerate MFA backup codes.
+     */
+    regenerateBackupCodes(password: string): Promise<{
+        backupCodes: string[];
+    }>;
+    /**
+     * Verify MFA challenge during login.
+     * By default, automatically sets the auth state on successful verification.
+     * @param data - MFA challenge data including token and code
+     * @param options - Optional settings for verification behavior
+     */
+    verifyMFAChallenge(data: MFAChallengeData, options?: MFAVerifyOptions): Promise<LoginResponse>;
+    /**
+     * Get all devices.
+     */
+    getDevices(customFetch?: typeof fetch): Promise<{
+        devices: Device[];
+    }>;
+    /**
+     * Trust a device.
+     */
+    trustDevice(deviceId: string): Promise<void>;
+    /**
+     * Revoke device trust.
+     */
+    revokeDevice(deviceId: string): Promise<void>;
+    /**
+     * Remove a device completely.
+     */
+    removeDevice(deviceId: string): Promise<void>;
+    /**
+     * Approve a device with a token.
+     */
+    approveDevice(token: string): Promise<{
+        message: string;
+        device?: Device;
+    }>;
+    /**
+     * Block a device with a token.
+     */
+    blockDevice(token: string): Promise<{
+        message: string;
+        device?: Device;
+    }>;
+    /**
+     * Get user preferences.
+     */
+    getPreferences(customFetch?: typeof fetch): Promise<UserPreferences>;
+    /**
+     * Update user preferences.
+     */
+    updatePreferences(data: Partial<UserPreferences>): Promise<void>;
+    /**
+     * Get SSO linked accounts.
+     */
+    getLinkedAccounts(customFetch?: typeof fetch): Promise<LinkedAccount[]>;
+    /**
+     * Link an SSO account (redirects to SSO provider).
+     */
+    linkAccount(provider?: string): Promise<void>;
+    /**
+     * Unlink an SSO account.
+     */
+    unlinkAccount(provider: string, password?: string): Promise<void>;
+    /**
+     * Get security event history.
+     */
+    getSecurityEvents(params?: {
+        page?: number;
+        limit?: number;
+        type?: string;
+    }, customFetch?: typeof fetch): Promise<{
+        events: SecurityEvent[];
+        pagination: Pagination;
+    }>;
+}
+/** Singleton instance of AuthService */
+declare const authService: AuthService;
+
+/**
+ * Auth Errors
+ *
+ * Custom error types for authentication operations.
+ */
+
+/**
+ * Error thrown when a user successfully authenticates but doesn't have
+ * any of the required roles to access the application.
+ *
+ * This allows apps to validate roles during login and provide specific
+ * error handling (e.g., redirect with error message) rather than silently
+ * logging in users who can't access any features.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await authService.login(credentials, {
+ *     allowedRoles: ['admin', 'manager', 'agent'],
+ *   });
+ * } catch (error) {
+ *   if (error instanceof RoleDeniedError) {
+ *     // User authenticated but lacks required role
+ *     console.log('User roles:', error.user.roles);
+ *     console.log('Required roles:', error.requiredRoles);
+ *     goto('/auth/login?error=insufficient_permissions');
+ *   }
+ * }
+ * ```
+ */
+declare class RoleDeniedError extends Error {
+    readonly name = "RoleDeniedError";
+    /**
+     * The authenticated user (allows logging before redirect)
+     */
+    readonly user: User;
+    /**
+     * The roles that were required (user has none of these)
+     */
+    readonly requiredRoles: string[];
+    /**
+     * Optional redirect path for convenience
+     */
+    readonly redirectTo?: string;
+    constructor(user: User, requiredRoles: string[], redirectTo?: string);
+}
+/**
+ * Type guard to check if an error is a RoleDeniedError.
+ */
+declare function isRoleDeniedError(error: unknown): error is RoleDeniedError;
+
+/**
+ * User Display Utilities
+ *
+ * Helper functions for displaying user information in the UI.
+ */
+
+/**
+ * Get a display-friendly name for a user.
+ *
+ * Priority:
+ * 1. Full name (firstName + lastName) if both exist
+ * 2. First name only
+ * 3. Username
+ * 4. Email
+ * 5. "Unknown" as fallback
+ *
+ * @example
+ * ```typescript
+ * const name = getDisplayName(user);
+ * // "John Doe", "John", "johndoe", or "john@example.com"
+ * ```
+ */
+declare function getDisplayName(user: User | null | undefined): string;
+/**
+ * Get initials from a user's name for avatar fallbacks.
+ *
+ * - Full name: "JD" for "John Doe"
+ * - Single name: "J" for "John"
+ * - Unknown: "?"
+ *
+ * @param user - The user object
+ * @param maxLength - Maximum number of initials (default: 2)
+ *
+ * @example
+ * ```typescript
+ * const initials = getUserInitials(user);
+ * // "JD" or "J" or "?"
+ * ```
+ */
+declare function getUserInitials(user: User | null | undefined, maxLength?: number): string;
+/**
+ * Get avatar fallback text for a user.
+ * Alias for getUserInitials for semantic clarity.
+ *
+ * @example
+ * ```typescript
+ * <Avatar>
+ *   <AvatarFallback>{getAvatarFallback(user)}</AvatarFallback>
+ * </Avatar>
+ * ```
+ */
+declare function getAvatarFallback(user: User | null | undefined): string;
+/**
+ * Get the user's primary email for display.
+ * Returns a masked version if needed for privacy.
+ *
+ * @param user - The user object
+ * @param masked - Whether to mask the email (default: false)
+ *
+ * @example
+ * ```typescript
+ * getUserEmail(user);        // "john@example.com"
+ * getUserEmail(user, true);  // "j***@example.com"
+ * ```
+ */
+declare function getUserEmail(user: User | null | undefined, masked?: boolean): string;
+/**
+ * Get a greeting for the user based on time of day.
+ *
+ * @param user - The user object
+ * @param includeTime - Whether to include time-based greeting (default: true)
+ *
+ * @example
+ * ```typescript
+ * getGreeting(user);             // "Good morning, John"
+ * getGreeting(user, false);      // "Hello, John"
+ * ```
+ */
+declare function getGreeting(user: User | null | undefined, includeTime?: boolean): string;
+/**
+ * Format user roles for display.
+ *
+ * @param user - The user object
+ * @param options - Formatting options
+ *
+ * @example
+ * ```typescript
+ * formatUserRoles(user);                    // "Admin, Manager"
+ * formatUserRoles(user, { max: 1 });        // "Admin +1 more"
+ * formatUserRoles(user, { lowercase: true }); // "admin, manager"
+ * ```
+ */
+declare function formatUserRoles(user: User | null | undefined, options?: {
+    /** Maximum roles to show before "+N more" */
+    max?: number;
+    /** Separator between roles (default: ", ") */
+    separator?: string;
+    /** Convert to lowercase (default: false) */
+    lowercase?: boolean;
+    /** Capitalize first letter of each role (default: true) */
+    capitalize?: boolean;
+}): string;
+
+export { AuthService as A, type LoginOptions as L, type MFAVerifyOptions as M, RoleDeniedError as R, authService as a, getUserInitials as b, getAvatarFallback as c, getUserEmail as d, getGreeting as e, formatUserRoles as f, getDisplayName as g, isRoleDeniedError as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/auth",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "Authentication services and Svelte bindings for Classic Theme apps",
   "type": "module",
   "main": "dist/index.js",

package/dist/chunk-IAPPE4US.js

@@ -1,66 +0,0 @@
-import { authStore } from './chunk-7M4DUK45.js';
-
-// src/svelte/guards/auth-guard.ts
-function checkAuth(options = {}) {
-  const { roles, permissions, requireAllRoles, requireAllPermissions } = options;
-  if (!authStore.isAuthenticated) {
-    return {
-      allowed: false,
-      reason: "not_authenticated",
-      redirectTo: "/login"
-    };
-  }
-  if (roles && roles.length > 0) {
-    const hasRoles = requireAllRoles ? authStore.hasAllRoles(roles) : authStore.hasAnyRole(roles);
-    if (!hasRoles) {
-      return {
-        allowed: false,
-        reason: "missing_role",
-        redirectTo: "/unauthorized"
-      };
-    }
-  }
-  if (permissions && permissions.length > 0) {
-    const hasPermissions = requireAllPermissions ? authStore.hasAllPermissions(permissions) : authStore.hasAnyPermission(permissions);
-    if (!hasPermissions) {
-      return {
-        allowed: false,
-        reason: "missing_permission",
-        redirectTo: "/unauthorized"
-      };
-    }
-  }
-  return { allowed: true };
-}
-function createAuthGuard(options = {}) {
-  return (onDenied) => {
-    const result = checkAuth(options);
-    if (!result.allowed) {
-      onDenied(result.redirectTo ?? "/login", result.reason ?? "not_authenticated");
-      return false;
-    }
-    return true;
-  };
-}
-function requireAuth() {
-  return checkAuth();
-}
-function requireRole(roles, requireAll = false) {
-  const roleArray = Array.isArray(roles) ? roles : [roles];
-  return checkAuth({ roles: roleArray, requireAllRoles: requireAll });
-}
-function requirePermission(permissions, requireAll = false) {
-  const permArray = Array.isArray(permissions) ? permissions : [permissions];
-  return checkAuth({ permissions: permArray, requireAllPermissions: requireAll });
-}
-function protectedLoad(options, loadFn) {
-  return async (event) => {
-    const result = checkAuth(options);
-    if (!result.allowed) {
-      return { redirect: result.redirectTo ?? "/login" };
-    }
-    return loadFn(event);
-  };
-}
-
-export { checkAuth, createAuthGuard, protectedLoad, requireAuth, requirePermission, requireRole };

package/dist/config-C-iBNu07.d.ts

@@ -1,86 +0,0 @@
-/**
- * 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;
-    /** 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;
-
-export { type AuthConfig as A, type SSOConfig as S, isInitialized as a, getDefaultStorage as b, getStorage as c, getFetch as d, type StorageAdapter as e, getConfig as g, initAuth as i, resetConfig as r };