@classic-homes/auth 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,631 @@
+import { L as LoginCredentials, a as LoginResponse, R as RegisterData, b as RegisterResponse, U as User, j as ProfileUpdateData, k as ChangePasswordData, S as Session, c as ApiKey, C as CreateApiKeyRequest, d as CreateApiKeyResponse, e as MFAStatus, M as MFASetupResponse, f as MFAChallengeData, D as Device, g as UserPreferences, h as LinkedAccount, i as SecurityEvent, P as Pagination } from '../types-exFUQyBX.js';
+export { A as AuthState, l as ResetPasswordData } from '../types-exFUQyBX.js';
+
+/**
+ * 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;
+
+/**
+ * HTTP Client
+ *
+ * A configurable HTTP client for making API requests.
+ * Handles authentication headers, token refresh, and error handling.
+ */
+interface ApiRequestOptions extends Omit<RequestInit, 'body'> {
+    /** Whether to include auth headers */
+    authenticated?: boolean;
+    /** Custom fetch implementation for this request */
+    customFetch?: typeof fetch;
+    /** Request body (will be JSON stringified) */
+    body?: unknown;
+}
+interface ApiResponse<T = unknown> {
+    data?: T;
+    meta?: {
+        status: string;
+        message?: string;
+    };
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * Get the current access token from storage.
+ */
+declare function getAccessToken(): string | null;
+/**
+ * Get the current refresh token from storage.
+ */
+declare function getRefreshToken(): string | null;
+/**
+ * Get the session token from storage.
+ */
+declare function getSessionToken(): string | null;
+/**
+ * Update stored tokens.
+ */
+declare function updateStoredTokens(accessToken: string, refreshToken: string): void;
+/**
+ * Clear stored auth data.
+ */
+declare function clearStoredAuth(): void;
+/**
+ * Helper to extract data from CHAPI response wrapper.
+ */
+declare function extractData<T>(response: {
+    data?: {
+        data?: T;
+    } | T;
+} | T): T;
+/**
+ * Make an API request.
+ */
+declare function apiRequest<T = unknown>(endpoint: string, options?: ApiRequestOptions): Promise<ApiResponse<T>>;
+/**
+ * Convenience methods for common HTTP methods.
+ */
+declare const api: {
+    get: <T = unknown>(endpoint: string, authenticated?: boolean, customFetch?: typeof fetch) => Promise<ApiResponse<T>>;
+    post: <T = unknown>(endpoint: string, body: unknown, authenticated?: boolean, customFetch?: typeof fetch) => Promise<ApiResponse<T>>;
+    put: <T = unknown>(endpoint: string, body: unknown, authenticated?: boolean, customFetch?: typeof fetch) => Promise<ApiResponse<T>>;
+    patch: <T = unknown>(endpoint: string, body: unknown, authenticated?: boolean, customFetch?: typeof fetch) => Promise<ApiResponse<T>>;
+    delete: <T = unknown>(endpoint: string, authenticated?: boolean, customFetch?: typeof fetch, body?: unknown) => Promise<ApiResponse<T>>;
+};
+
+/**
+ * Auth API
+ *
+ * API client methods for authentication endpoints.
+ */
+
+declare const authApi: {
+    /**
+     * Login with username and password.
+     */
+    login(credentials: LoginCredentials): Promise<LoginResponse>;
+    /**
+     * Logout the current user.
+     */
+    logout(): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Refresh the access token.
+     */
+    refreshToken(refreshToken: string): Promise<{
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    /**
+     * Initiate SSO login by redirecting to the SSO provider.
+     */
+    initiateSSOLogin(): void;
+    /**
+     * Get the current user's profile.
+     */
+    getProfile(customFetch?: typeof fetch): Promise<User>;
+    /**
+     * Update the current user's profile.
+     */
+    updateProfile(data: ProfileUpdateData): Promise<User>;
+    /**
+     * Change the current user's password.
+     */
+    changePassword(data: ChangePasswordData): Promise<void>;
+    /**
+     * 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, data: {
+        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.
+     */
+    verifyMFAChallenge(data: MFAChallengeData): 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.
+     */
+    getSSOAccounts(customFetch?: typeof fetch): Promise<LinkedAccount[]>;
+    /**
+     * Unlink an SSO account.
+     */
+    unlinkSSOAccount(provider: string, password?: string): Promise<void>;
+    /**
+     * Link an SSO account (redirects to SSO provider).
+     */
+    linkSSOAccount(provider?: string): Promise<void>;
+    /**
+     * Get security event history.
+     */
+    getSecurityEvents(params?: {
+        page?: number;
+        limit?: number;
+        type?: string;
+    }, customFetch?: typeof fetch): Promise<{
+        events: SecurityEvent[];
+        pagination: Pagination;
+    }>;
+};
+
+/**
+ * Auth Service
+ *
+ * Business logic layer for authentication operations.
+ * Wraps authApi calls and provides a clean interface for components.
+ */
+
+/**
+ * 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.
+     */
+    login(credentials: LoginCredentials): Promise<LoginResponse>;
+    /**
+     * Logout the current user.
+     */
+    logout(): Promise<void>;
+    /**
+     * 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).
+     */
+    initiateSSOLogin(): 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.
+     */
+    verifyMFAChallenge(data: MFAChallengeData): 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;
+
+/**
+ * JWT Utilities
+ *
+ * Simple JWT decoder utilities for extracting payload data.
+ * Note: These functions do NOT verify signatures - they only extract payloads.
+ */
+interface JWTPayload {
+    /** Subject (usually user ID) */
+    sub: string;
+    email?: string;
+    username?: string;
+    roles?: string[];
+    permissions?: string[];
+    /** Expiration time (Unix timestamp in seconds) */
+    exp?: number;
+    /** Issued at time (Unix timestamp in seconds) */
+    iat?: number;
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Decode a JWT token and extract its payload.
+ *
+ * @param token - The JWT token string
+ * @returns The decoded payload, or null if decoding fails
+ *
+ * @example
+ * ```typescript
+ * const payload = decodeJWT(accessToken);
+ * if (payload) {
+ *   console.log('User ID:', payload.sub);
+ *   console.log('Expires:', new Date(payload.exp! * 1000));
+ * }
+ * ```
+ */
+declare function decodeJWT(token: string): JWTPayload | null;
+/**
+ * Check if a JWT token is expired.
+ *
+ * @param token - The JWT token string
+ * @returns true if the token is expired or invalid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isTokenExpired(accessToken)) {
+ *   // Token needs refresh
+ * }
+ * ```
+ */
+declare function isTokenExpired(token: string): boolean;
+/**
+ * Get the remaining time until a JWT token expires.
+ *
+ * @param token - The JWT token string
+ * @returns Remaining time in milliseconds, or 0 if expired/invalid
+ *
+ * @example
+ * ```typescript
+ * const remaining = getTokenRemainingTime(accessToken);
+ * console.log(`Token expires in ${remaining / 1000} seconds`);
+ * ```
+ */
+declare function getTokenRemainingTime(token: string): number;
+/**
+ * Get the expiration date of a JWT token.
+ *
+ * @param token - The JWT token string
+ * @returns The expiration Date, or null if no expiration or invalid token
+ *
+ * @example
+ * ```typescript
+ * const expiry = getTokenExpiration(accessToken);
+ * if (expiry) {
+ *   console.log(`Token expires at ${expiry.toISOString()}`);
+ * }
+ * ```
+ */
+declare function getTokenExpiration(token: string): Date | null;
+/**
+ * Extract specific claims from a JWT token.
+ *
+ * @param token - The JWT token string
+ * @param claims - Array of claim names to extract
+ * @returns Object with requested claims, or null if token is invalid
+ *
+ * @example
+ * ```typescript
+ * const claims = extractClaims(token, ['sub', 'roles', 'permissions']);
+ * // { sub: '123', roles: ['admin'], permissions: ['read', 'write'] }
+ * ```
+ */
+declare function extractClaims<T extends string>(token: string, claims: T[]): Pick<JWTPayload, T> | null;
+
+export { ApiKey, type ApiRequestOptions, type ApiResponse, type AuthConfig, AuthService, ChangePasswordData, CreateApiKeyRequest, CreateApiKeyResponse, Device, type JWTPayload, LinkedAccount, LoginCredentials, LoginResponse, MFAChallengeData, MFASetupResponse, MFAStatus, Pagination, ProfileUpdateData, RegisterData, RegisterResponse, type SSOConfig, SecurityEvent, Session, type StorageAdapter, User, UserPreferences, api, apiRequest, authApi, authService, clearStoredAuth, decodeJWT, extractClaims, extractData, getAccessToken, getConfig, getDefaultStorage, getFetch, getRefreshToken, getSessionToken, getStorage, getTokenExpiration, getTokenRemainingTime, initAuth, isInitialized, isTokenExpired, resetConfig, updateStoredTokens };