@oxyhq/auth 1.0.0

package/src/hooks/useFollow.types.ts

@@ -0,0 +1,33 @@
+// Type-only definition for the useFollow hook to allow context exposure without runtime import cycles.
+// Expand this as needed to better reflect the real return type.
+
+export type SingleFollowResult = {
+  isFollowing: boolean;
+  isLoading: boolean;
+  error: string | null;
+  toggleFollow: () => Promise<void>;
+  setFollowStatus: (following: boolean) => void;
+  fetchStatus: () => Promise<void>;
+  clearError: () => void;
+  followerCount: number | null;
+  followingCount: number | null;
+  isLoadingCounts: boolean;
+  fetchUserCounts: () => Promise<void>;
+  setFollowerCount: (count: number) => void;
+  setFollowingCount: (count: number) => void;
+};
+
+export type MultiFollowResult = {
+  followData: Record<string, { isFollowing: boolean; isLoading: boolean; error: string | null }>;
+  toggleFollowForUser: (userId: string) => Promise<void>;
+  setFollowStatusForUser: (userId: string, following: boolean) => void;
+  fetchStatusForUser: (userId: string) => Promise<void>;
+  fetchAllStatuses: () => Promise<void>;
+  clearErrorForUser: (userId: string) => void;
+  isAnyLoading: boolean;
+  hasAnyError: boolean;
+  allFollowing: boolean;
+  allNotFollowing: boolean;
+};
+
+export type UseFollowHook = (userId?: string | string[]) => SingleFollowResult | MultiFollowResult;

package/src/hooks/useQueryClient.ts

@@ -0,0 +1,17 @@
+import { useQueryClient as useTanStackQueryClient } from '@tanstack/react-query';
+import type { QueryClient } from '@tanstack/react-query';
+
+/**
+ * Custom hook to access the QueryClient
+ * Provides type safety and ensures client is available
+ */
+export const useQueryClient = (): QueryClient => {
+  const queryClient = useTanStackQueryClient();
+  
+  if (!queryClient) {
+    throw new Error('QueryClient is not available. Make sure OxyProvider is wrapping your app.');
+  }
+  
+  return queryClient;
+};
+

package/src/hooks/useSessionSocket.ts

@@ -0,0 +1,233 @@
+import { useEffect, useRef } from 'react';
+import io from 'socket.io-client';
+import { toast } from 'sonner';
+import { logger } from '@oxyhq/core';
+import { createDebugLogger } from '@oxyhq/core';
+
+const debug = createDebugLogger('SessionSocket');
+
+interface UseSessionSocketProps {
+  userId: string | null | undefined;
+  activeSessionId: string | null | undefined;
+  currentDeviceId: string | null | undefined;
+  refreshSessions: () => Promise<void>;
+  logout: () => Promise<void>;
+  clearSessionState: () => Promise<void>;
+  baseURL: string;
+  onRemoteSignOut?: () => void;
+  onSessionRemoved?: (sessionId: string) => void;
+}
+
+export function useSessionSocket({ userId, activeSessionId, currentDeviceId, refreshSessions, logout, clearSessionState, baseURL, onRemoteSignOut, onSessionRemoved }: UseSessionSocketProps) {
+  const socketRef = useRef<any>(null);
+  const joinedRoomRef = useRef<string | null>(null);
+  
+  // Store callbacks in refs to avoid re-joining when they change
+  const refreshSessionsRef = useRef(refreshSessions);
+  const logoutRef = useRef(logout);
+  const clearSessionStateRef = useRef(clearSessionState);
+  const onRemoteSignOutRef = useRef(onRemoteSignOut);
+  const onSessionRemovedRef = useRef(onSessionRemoved);
+  const activeSessionIdRef = useRef(activeSessionId);
+  const currentDeviceIdRef = useRef(currentDeviceId);
+
+  // Update refs when callbacks change
+  useEffect(() => {
+    refreshSessionsRef.current = refreshSessions;
+    logoutRef.current = logout;
+    clearSessionStateRef.current = clearSessionState;
+    onRemoteSignOutRef.current = onRemoteSignOut;
+    onSessionRemovedRef.current = onSessionRemoved;
+    activeSessionIdRef.current = activeSessionId;
+    currentDeviceIdRef.current = currentDeviceId;
+  }, [refreshSessions, logout, clearSessionState, onRemoteSignOut, onSessionRemoved, activeSessionId, currentDeviceId]);
+
+  useEffect(() => {
+    if (!userId || !baseURL) {
+      // Clean up if userId or baseURL becomes invalid
+      if (socketRef.current && joinedRoomRef.current) {
+        socketRef.current.emit('leave', { userId: joinedRoomRef.current });
+        joinedRoomRef.current = null;
+      }
+      return;
+    }
+
+    const roomId = `user:${userId}`;
+    
+    // Only create socket if it doesn't exist
+    if (!socketRef.current) {
+      socketRef.current = io(baseURL, {
+        transports: ['websocket'],
+      });
+    }
+    const socket = socketRef.current;
+
+    // Only join if we haven't already joined this room
+    if (joinedRoomRef.current !== roomId) {
+      // Leave previous room if switching users
+      if (joinedRoomRef.current) {
+        socket.emit('leave', { userId: joinedRoomRef.current });
+      }
+      
+      socket.emit('join', { userId: roomId });
+      joinedRoomRef.current = roomId;
+      
+      debug.log('Emitting join for room:', roomId);
+    }
+
+    // Set up event handlers (only once per socket instance)
+    const handleConnect = () => {
+      debug.log('Socket connected:', socket.id);
+    };
+
+    const handleSessionUpdate = async (data: {
+      type: string;
+      sessionId?: string;
+      deviceId?: string;
+      sessionIds?: string[]
+    }) => {
+      debug.log('Received session_update:', data);
+      
+      const currentActiveSessionId = activeSessionIdRef.current;
+      const currentDeviceId = currentDeviceIdRef.current;
+      
+      // Handle different event types
+      if (data.type === 'session_removed') {
+        // Track removed session
+        if (data.sessionId && onSessionRemovedRef.current) {
+          onSessionRemovedRef.current(data.sessionId);
+        }
+        
+        // If the removed sessionId matches the current activeSessionId, immediately clear state
+        if (data.sessionId === currentActiveSessionId) {
+          if (onRemoteSignOutRef.current) {
+            onRemoteSignOutRef.current();
+          } else {
+            toast.info('You have been signed out remotely.');
+          }
+          // Use clearSessionState since session was already removed server-side
+          // Await to ensure storage cleanup completes before continuing
+          try {
+            await clearSessionStateRef.current();
+          } catch (error) {
+            if (__DEV__) {
+              logger.error('Failed to clear session state after session_removed', error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
+            }
+          }
+        } else {
+          // Otherwise, just refresh the sessions list (with error handling)
+          refreshSessionsRef.current().catch((error) => {
+            // Silently handle errors from refresh - they're expected if sessions were removed
+            if (__DEV__) {
+              logger.debug('Failed to refresh sessions after session_removed', { component: 'useSessionSocket' }, error as unknown);
+            }
+          });
+        }
+      } else if (data.type === 'device_removed') {
+        // Track all removed sessions from this device
+        if (data.sessionIds && onSessionRemovedRef.current) {
+          for (const sessionId of data.sessionIds) {
+            onSessionRemovedRef.current(sessionId);
+          }
+        }
+        
+        // If the removed deviceId matches the current device, immediately clear state
+        if (data.deviceId && data.deviceId === currentDeviceId) {
+          if (onRemoteSignOutRef.current) {
+            onRemoteSignOutRef.current();
+          } else {
+            toast.info('This device has been removed. You have been signed out.');
+          }
+          // Use clearSessionState since sessions were already removed server-side
+          // Await to ensure storage cleanup completes before continuing
+          try {
+            await clearSessionStateRef.current();
+          } catch (error) {
+            if (__DEV__) {
+              logger.error('Failed to clear session state after device_removed', error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
+            }
+          }
+        } else {
+          // Otherwise, refresh sessions and device list (with error handling)
+          refreshSessionsRef.current().catch((error) => {
+            // Silently handle errors from refresh - they're expected if sessions were removed
+            if (__DEV__) {
+              logger.debug('Failed to refresh sessions after device_removed', { component: 'useSessionSocket' }, error as unknown);
+            }
+          });
+        }
+      } else if (data.type === 'sessions_removed') {
+        // Track all removed sessions
+        if (data.sessionIds && onSessionRemovedRef.current) {
+          for (const sessionId of data.sessionIds) {
+            onSessionRemovedRef.current(sessionId);
+          }
+        }
+        
+        // If the current activeSessionId is in the removed sessionIds list, immediately clear state
+        if (data.sessionIds && currentActiveSessionId && data.sessionIds.includes(currentActiveSessionId)) {
+          if (onRemoteSignOutRef.current) {
+            onRemoteSignOutRef.current();
+          } else {
+            toast.info('You have been signed out remotely.');
+          }
+          // Use clearSessionState since sessions were already removed server-side
+          // Await to ensure storage cleanup completes before continuing
+          try {
+            await clearSessionStateRef.current();
+          } catch (error) {
+            if (__DEV__) {
+              logger.error('Failed to clear session state after sessions_removed', error instanceof Error ? error : new Error(String(error)), { component: 'useSessionSocket' });
+            }
+          }
+        } else {
+          // Otherwise, refresh sessions list (with error handling)
+          refreshSessionsRef.current().catch((error) => {
+            // Silently handle errors from refresh - they're expected if sessions were removed
+            if (__DEV__) {
+              logger.debug('Failed to refresh sessions after sessions_removed', { component: 'useSessionSocket' }, error as unknown);
+            }
+          });
+        }
+      } else {
+        // For other event types (e.g., session_created), refresh sessions (with error handling)
+        refreshSessionsRef.current().catch((error) => {
+          // Log but don't throw - refresh errors shouldn't break the socket handler
+          if (__DEV__) {
+            logger.debug('Failed to refresh sessions after session_update', { component: 'useSessionSocket' }, error as unknown);
+          }
+        });
+        
+        // If the current session was logged out (legacy behavior), handle it specially
+        if (data.sessionId === currentActiveSessionId) {
+          if (onRemoteSignOutRef.current) {
+            onRemoteSignOutRef.current();
+          } else {
+            toast.info('You have been signed out remotely.');
+          }
+          // Use clearSessionState since session was already removed server-side
+          // Await to ensure storage cleanup completes before continuing
+          try {
+            await clearSessionStateRef.current();
+          } catch (error) {
+            debug.error('Failed to clear session state after session_update:', error);
+          }
+        }
+      }
+    };
+
+    socket.on('connect', handleConnect);
+    socket.on('session_update', handleSessionUpdate);
+
+    return () => {
+      socket.off('connect', handleConnect);
+      socket.off('session_update', handleSessionUpdate);
+      
+      // Only leave on unmount if we're still in this room
+      if (joinedRoomRef.current === roomId) {
+        socket.emit('leave', { userId: roomId });
+        joinedRoomRef.current = null;
+      }
+    };
+  }, [userId, baseURL]); // Only depend on userId and baseURL - callbacks are in refs
+} 

package/src/hooks/useWebSSO.ts

@@ -0,0 +1,187 @@
+/**
+ * Web SSO Hook
+ *
+ * Handles cross-domain SSO for web apps using FedCM (Federated Credential Management).
+ *
+ * FedCM is the modern, privacy-preserving standard for cross-domain identity federation.
+ * It works across completely different TLDs (alia.onl, mention.earth, homiio.com, etc.)
+ * without relying on third-party cookies.
+ *
+ * For browsers without FedCM support, users will need to click a sign-in button
+ * which triggers a popup-based authentication flow.
+ *
+ * This is called automatically by OxyContext on web platforms.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/FedCM_API
+ */
+
+import { useEffect, useRef, useCallback } from 'react';
+import type { OxyServices } from '@oxyhq/core';
+import type { SessionLoginResponse } from '@oxyhq/core';
+
+interface UseWebSSOOptions {
+  oxyServices: OxyServices;
+  onSessionFound: (session: SessionLoginResponse) => Promise<void>;
+  onSSOUnavailable?: () => void;
+  onError?: (error: Error) => void;
+  enabled?: boolean;
+}
+
+interface UseWebSSOResult {
+  /** Manually trigger SSO check */
+  checkSSO: () => Promise<SessionLoginResponse | null>;
+  /** Trigger interactive FedCM sign-in (shows browser UI) */
+  signInWithFedCM: () => Promise<SessionLoginResponse | null>;
+  /** Whether SSO check is in progress */
+  isChecking: boolean;
+  /** Whether FedCM is supported in this browser */
+  isFedCMSupported: boolean;
+}
+
+/**
+ * Check if we're running in a web browser environment (not React Native)
+ */
+function isWebBrowser(): boolean {
+  return typeof window !== 'undefined' &&
+         typeof document !== 'undefined' &&
+         typeof document.documentElement !== 'undefined';
+}
+
+/**
+ * Check if we're on the identity provider domain (where FedCM would authenticate against itself)
+ * Only auth.oxy.so is the IdP - accounts.oxy.so is a client app like any other
+ */
+function isIdentityProvider(): boolean {
+  if (!isWebBrowser()) return false;
+  const hostname = window.location.hostname;
+  return hostname === 'auth.oxy.so';
+}
+
+/**
+ * Hook for automatic cross-domain web SSO
+ *
+ * Uses FedCM (Federated Credential Management) - the modern browser-native
+ * identity federation API. This is the same technology that powers
+ * Google's cross-domain SSO (YouTube, Gmail, Maps, etc.).
+ *
+ * Key benefits:
+ * - Works across different TLDs (alia.onl ↔ mention.earth ↔ homiio.com)
+ * - No third-party cookies required
+ * - Privacy-preserving (browser mediates identity, IdP can't track)
+ * - Automatic silent sign-in after initial authentication
+ *
+ * For browsers without FedCM (Firefox, older browsers), automatic SSO
+ * is not possible. Users will see a sign-in button instead.
+ */
+export function useWebSSO({
+  oxyServices,
+  onSessionFound,
+  onSSOUnavailable,
+  onError,
+  enabled = true,
+}: UseWebSSOOptions): UseWebSSOResult {
+  const isCheckingRef = useRef(false);
+  const hasCheckedRef = useRef(false);
+
+  // Check FedCM support once
+  const fedCMSupported = isWebBrowser() && (oxyServices as any).isFedCMSupported?.();
+
+  const checkSSO = useCallback(async (): Promise<SessionLoginResponse | null> => {
+    if (!isWebBrowser() || isCheckingRef.current) {
+      return null;
+    }
+
+    // Don't use FedCM on the auth domain itself - it would authenticate against itself
+    if (isIdentityProvider()) {
+      onSSOUnavailable?.();
+      return null;
+    }
+
+    // FedCM is the only reliable cross-domain SSO mechanism
+    if (!fedCMSupported) {
+      onSSOUnavailable?.();
+      return null;
+    }
+
+    isCheckingRef.current = true;
+
+    try {
+      const session = await (oxyServices as any).silentSignInWithFedCM?.();
+
+      if (session) {
+        await onSessionFound(session);
+        return session;
+      }
+
+      onSSOUnavailable?.();
+      return null;
+    } catch (error) {
+      onSSOUnavailable?.();
+      onError?.(error instanceof Error ? error : new Error(String(error)));
+      return null;
+    } finally {
+      isCheckingRef.current = false;
+    }
+  }, [oxyServices, onSessionFound, onSSOUnavailable, onError, fedCMSupported]);
+
+  /**
+   * Trigger interactive FedCM sign-in
+   * This shows the browser's native "Sign in with Oxy" prompt.
+   * Use this when silent mediation fails (user hasn't previously consented).
+   */
+  const signInWithFedCM = useCallback(async (): Promise<SessionLoginResponse | null> => {
+    if (!isWebBrowser() || isCheckingRef.current) {
+      return null;
+    }
+
+    if (!fedCMSupported) {
+      onError?.(new Error('FedCM is not supported in this browser'));
+      return null;
+    }
+
+    isCheckingRef.current = true;
+
+    try {
+      const session = await (oxyServices as any).signInWithFedCM?.();
+
+      if (session) {
+        await onSessionFound(session);
+        return session;
+      }
+
+      return null;
+    } catch (error) {
+      onError?.(error instanceof Error ? error : new Error(String(error)));
+      return null;
+    } finally {
+      isCheckingRef.current = false;
+    }
+  }, [oxyServices, onSessionFound, onError, fedCMSupported]);
+
+  // Auto-check SSO on mount (web only, FedCM only, not on auth domain)
+  useEffect(() => {
+    if (!enabled || !isWebBrowser() || hasCheckedRef.current || isIdentityProvider()) {
+      if (isIdentityProvider()) {
+        onSSOUnavailable?.();
+      }
+      return;
+    }
+
+    hasCheckedRef.current = true;
+
+    if (fedCMSupported) {
+      checkSSO();
+    } else {
+      onSSOUnavailable?.();
+    }
+  }, [enabled, checkSSO, fedCMSupported, onSSOUnavailable]);
+
+  return {
+    checkSSO,
+    signInWithFedCM,
+    isChecking: isCheckingRef.current,
+    isFedCMSupported: fedCMSupported,
+  };
+}
+
+export { isWebBrowser };

package/src/index.ts

@@ -0,0 +1,144 @@
+/**
+ * @oxyhq/auth — OxyHQ Web Authentication SDK
+ *
+ * Headless authentication for React web apps (Next.js, Vite, CRA).
+ * Zero React Native / Expo dependencies.
+ *
+ * @example
+ * ```tsx
+ * import { WebOxyProvider, useAuth } from '@oxyhq/auth';
+ *
+ * function App() {
+ *   return (
+ *     <WebOxyProvider baseURL="https://api.oxy.so">
+ *       <YourApp />
+ *     </WebOxyProvider>
+ *   );
+ * }
+ *
+ * function YourApp() {
+ *   const { user, isAuthenticated, signIn, signOut } = useAuth();
+ *   // ...
+ * }
+ * ```
+ */
+
+// --- Provider & Hooks ---
+export { WebOxyProvider, useWebOxy, useAuth } from './WebOxyProvider';
+export type {
+  WebOxyProviderProps,
+  WebAuthState,
+  WebAuthActions,
+  WebOxyContextValue,
+} from './WebOxyProvider';
+
+// --- Stores ---
+export { useAuthStore } from './stores/authStore';
+export {
+  useAssetStore,
+  useAssets as useAssetsStore,
+  useAsset,
+  useUploadProgress,
+  useAssetLoading,
+  useAssetErrors,
+  useAssetsByApp,
+  useAssetsByEntity,
+  useAssetUsageCount,
+  useIsAssetLinked,
+} from './stores/assetStore';
+
+// --- Query Hooks ---
+export {
+  useUserProfile,
+  useUserProfiles,
+  useCurrentUser,
+  useUserById,
+  useUserByUsername,
+  useUsersBySessions,
+  usePrivacySettings,
+  useSessions,
+  useSession,
+  useDeviceSessions,
+  useUserDevices,
+  useSecurityInfo,
+  useSecurityActivity,
+  useRecentSecurityActivity,
+} from './hooks/queries';
+
+// --- Mutation Hooks ---
+export {
+  useUpdateProfile,
+  useUploadAvatar,
+  useUpdateAccountSettings,
+  useUpdatePrivacySettings,
+  useUploadFile,
+  useSwitchSession,
+  useLogoutSession,
+  useLogoutAll,
+  useUpdateDeviceName,
+  useRemoveDevice,
+} from './hooks/mutations';
+
+export {
+  createProfileMutation,
+  createGenericMutation,
+} from './hooks/mutations/mutationFactory';
+export type {
+  ProfileMutationConfig,
+  GenericMutationConfig,
+} from './hooks/mutations/mutationFactory';
+
+// --- Custom Hooks ---
+export { useSessionSocket } from './hooks/useSessionSocket';
+export { useAssets, setOxyAssetInstance } from './hooks/useAssets';
+export { useFileDownloadUrl, setOxyFileUrlInstance } from './hooks/useFileDownloadUrl';
+export { useFollow, useFollowerCounts } from './hooks/useFollow';
+export { useFileFiltering } from './hooks/useFileFiltering';
+export type { ViewMode, SortBy, SortOrder } from './hooks/useFileFiltering';
+
+// --- Auth Helpers ---
+export {
+  ensureValidToken,
+  withAuthErrorHandling,
+  authenticatedApiCall,
+  isAuthenticationError,
+  SessionSyncRequiredError,
+  AuthenticationFailedError,
+} from './utils/authHelpers';
+export type { HandleApiErrorOptions } from './utils/authHelpers';
+
+// --- Error Handlers ---
+export {
+  handleAuthError,
+  isInvalidSessionError,
+  isTimeoutOrNetworkError,
+  extractErrorMessage,
+} from './utils/errorHandlers';
+export type { HandleAuthErrorOptions } from './utils/errorHandlers';
+
+// Re-export core for convenience
+export {
+  OxyServices,
+  CrossDomainAuth,
+  AuthManager,
+  createAuthManager,
+  createCrossDomainAuth,
+} from '@oxyhq/core';
+
+export type {
+  User,
+  LoginResponse,
+  ApiError,
+  SessionLoginResponse,
+  ClientSession,
+  MinimalUserData,
+  OxyConfig,
+  StorageAdapter,
+  AuthStateChangeCallback,
+  AuthMethod,
+  AuthManagerConfig,
+  CrossDomainAuthOptions,
+} from '@oxyhq/core';
+
+import { WebOxyProvider as _WebOxyProvider } from './WebOxyProvider';
+export default _WebOxyProvider;