@oxyhq/services 5.16.29 → 5.16.31

package/src/core/services/TokenService.ts

@@ -8,17 +8,17 @@
  * - Single storage location (no duplication)
  * - Automatic token refresh when expiring soon
  * - Type-safe token payload handling
- * - userId is always MongoDB ObjectId, never publicKey
+ * - publicKey is the canonical user identity
  */
 
 import { jwtDecode } from 'jwt-decode';
 
 /**
  * AccessTokenPayload - Matches the token payload structure from API
- * userId is always MongoDB ObjectId (24 hex characters), never publicKey
+ * publicKey is the canonical user identity (ECDSA secp256k1 public key)
  */
 interface AccessTokenPayload {
-  userId: string;      // MongoDB ObjectId - PRIMARY IDENTIFIER
+  publicKey: string;   // User's public key - CANONICAL USER IDENTITY
   sessionId: string;   // Session UUID
   deviceId: string;   // Device identifier
   type: 'access';
@@ -116,21 +116,29 @@ class TokenService {
   }
 
   /**
-   * Get userId from current access token
-   * Returns MongoDB ObjectId (never publicKey)
+   * Get publicKey from current access token
+   * Returns the user's public key (canonical user identity)
    */
-  getUserIdFromToken(): string | null {
+  getPublicKeyFromToken(): string | null {
     const token = this.tokenStore.accessToken;
     if (!token) return null;
 
     try {
       const decoded = jwtDecode<AccessTokenPayload>(token);
-      return decoded.userId || null;
+      return decoded.publicKey || null;
     } catch {
       return null;
     }
   }
 
+  /**
+   * @deprecated Use getPublicKeyFromToken() instead. This method is kept for backward compatibility.
+   * Get userId from current access token (returns publicKey, not MongoDB ObjectId)
+   */
+  getUserIdFromToken(): string | null {
+    return this.getPublicKeyFromToken();
+  }
+
   /**
    * Refresh access token if expiring soon
    * Returns promise that resolves when token is refreshed (or already valid)
@@ -193,10 +201,10 @@ class TokenService {
         throw new Error('No access token in refresh response');
       }
 
-      // Validate new token has correct userId format (ObjectId)
+      // Validate new token has publicKey (canonical user identity)
       const newDecoded = jwtDecode<AccessTokenPayload>(newToken);
-      if (newDecoded.userId && !/^[0-9a-fA-F]{24}$/.test(newDecoded.userId)) {
-        throw new Error(`Invalid userId format in refreshed token: ${newDecoded.userId.substring(0, 20)}...`);
+      if (!newDecoded.publicKey) {
+        throw new Error('Token missing publicKey after refresh');
       }
 
       this.setTokens(newToken);

package/src/index.ts

@@ -137,6 +137,8 @@ export {
 export { useSessionSocket } from './ui/hooks/useSessionSocket';
 export { useAssets, setOxyAssetInstance } from './ui/hooks/useAssets';
 export { useFileDownloadUrl, setOxyFileUrlInstance } from './ui/hooks/useFileDownloadUrl';
+export { useUsernameValidation, USERNAME_MIN_LENGTH, USERNAME_REGEX, USERNAME_FORMAT_ERROR, USERNAME_DEBOUNCE_MS } from './ui/hooks/auth';
+export type { UsernameValidationResult } from './ui/hooks/auth';
 
 // UI hooks - Query hooks (TanStack Query)
 export {
@@ -148,6 +150,8 @@ export {
   useUserByUsername,
   useUsersBySessions,
   usePrivacySettings,
+  useBlockedUsers,
+  useRestrictedUsers,
   // Service queries
   useSessions,
   useSession,
@@ -167,6 +171,8 @@ export {
   useUpdateAccountSettings,
   useUpdatePrivacySettings,
   useUploadFile,
+  useUnblockUser,
+  useUnrestrictUser,
   // Service mutations
   useSwitchSession,
   useLogoutSession,

package/src/models/interfaces.ts

@@ -25,19 +25,20 @@ export interface OxyConfig {
  * User Model
  * 
  * IMPORTANT: 
- * - id: MongoDB ObjectId (24 hex characters) - PRIMARY IDENTIFIER for all internal operations
- * - publicKey: Cryptographic public key (130 hex characters) - LOOKUP KEY for authentication and identity operations
+ * - id: Public key (ECDSA secp256k1 public key, 130 hex characters) - CANONICAL USER IDENTITY
+ * - publicKey: Same as id (kept for backward compatibility and explicit clarity)
  * 
- * Never use publicKey as an ID. Always use id (ObjectId) for:
- * - Database queries
- * - Session userId
- * - Token userId
- * - Socket room names
- * - API route parameters (unless explicitly doing publicKey lookup)
+ * publicKey is the canonical user identity across the ecosystem because it's:
+ * - Globally unique
+ * - Local-first (stored in Accounts app)
+ * - Avoids device-bound artifacts
+ * 
+ * MongoDB _id remains internal to backend only and is not exposed in the User interface.
+ * Backend may use MongoDB ObjectId internally for database operations, but client always uses publicKey.
  */
 export interface User {
-  id: string;           // MongoDB ObjectId - PRIMARY IDENTIFIER (always 24 hex chars)
-  publicKey: string;    // Cryptographic public key - LOOKUP KEY (130 hex chars for secp256k1)
+  id: string;           // Public key - CANONICAL USER IDENTITY (130 hex chars for secp256k1)
+  publicKey: string;    // Same as id (kept for backward compatibility)
   username: string;
   email?: string;
   // Avatar file id (asset id)

package/src/models/session.ts

@@ -2,15 +2,17 @@
  * Client Session Model
  * 
  * IMPORTANT:
- * - userId: MongoDB ObjectId (24 hex characters), never publicKey
- * - Used for session management and user identification
+ * - publicKey: Canonical user identity (ECDSA secp256k1 public key) - PRIMARY IDENTIFIER
+ * - userId: MongoDB ObjectId (kept for backward compatibility, but publicKey is canonical)
+ * - Sessions are bound to the local identity (publicKey) stored in Accounts app
  */
 export interface ClientSession {
   sessionId: string;
   deviceId: string;
   expiresAt: string;
   lastActive: string;
-  userId?: string;  // MongoDB ObjectId - PRIMARY IDENTIFIER (never publicKey)
+  publicKey: string;  // Canonical user identity - PRIMARY IDENTIFIER
+  userId?: string;     // MongoDB ObjectId (internal backend reference, optional for compatibility)
   isCurrent?: boolean;
 }
 

package/src/ui/context/OxyContext.tsx

@@ -222,7 +222,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         // CRITICAL: Invalidate cache on app startup to ensure fresh state check
         // This prevents stale cache from previous session from showing incorrect state
         KeyManager.invalidateCache();
-        
+
         // Check if identity exists and verify integrity
         const hasIdentity = await KeyManager.hasIdentity();
         if (hasIdentity) {
@@ -421,7 +421,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       if (pendingTransfers.length > 0) {
         const activeTransferId = getActiveTransferId();
         const hasActiveTransfer = activeTransferId && pendingTransfers.some((t: { transferId: string; data: any }) => t.transferId === activeTransferId);
-        
+
         if (hasActiveTransfer) {
           throw new Error(
             'Cannot delete identity: An active identity transfer is in progress. ' +
@@ -485,11 +485,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         if (wasOffline) {
           const now = Date.now();
           const timeSinceLastLog = now - lastReconnectionLog;
-          
+
           if (timeSinceLastLog >= RECONNECTION_LOG_DEBOUNCE_MS) {
             logger('Network reconnected, checking identity sync...');
             lastReconnectionLog = now;
-            
+
             // Sync identity first (if not synced)
             try {
               const hasIdentityValue = await hasIdentity();
@@ -520,7 +520,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             // This is handled by useCheckPendingTransfers hook which runs automatically
             // when authenticated and online
           }
-          
+
           // TanStack Query will automatically retry pending mutations
           // Reset flag immediately after processing (whether logged or not)
           wasOffline = false;
@@ -580,6 +580,22 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     setTokenReady(false);
 
     try {
+      // CRITICAL: Get current local identity (publicKey) before restoring sessions
+      // Sessions must belong to the current local identity stored in Accounts app
+      let currentPublicKey: string | null = null;
+      try {
+        if (Platform.OS !== 'web') {
+          // Only check identity on native platforms (web doesn't have local identity)
+          // KeyManager is already imported at the top of the file
+          currentPublicKey = await KeyManager.getPublicKey();
+        }
+      } catch (identityError) {
+        if (__DEV__) {
+          logger('Failed to get current local identity during session restoration', identityError);
+        }
+        // Continue without identity check if it fails (e.g., on web platform)
+      }
+
       const storedSessionIdsJson = await storage.getItem(storageKeys.sessionIds);
       const storedSessionIds: string[] = storedSessionIdsJson ? JSON.parse(storedSessionIdsJson) : [];
       const storedActiveSessionId = await storage.getItem(storageKeys.activeSessionId);
@@ -592,12 +608,25 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
             const validation = await oxyServices.validateSession(sessionId, { useHeaderValidation: true });
             if (validation?.valid && validation.user) {
               const now = new Date();
+              // user.id is now publicKey (canonical identity)
+              const sessionPublicKey = validation.user.publicKey || validation.user.id || '';
+
+              // IDENTITY BINDING: Only restore sessions that match current local identity
+              // If we have a current local identity, filter out sessions that don't match
+              if (currentPublicKey && sessionPublicKey !== currentPublicKey) {
+                if (__DEV__) {
+                  logger(`Skipping session ${sessionId.substring(0, 8)}... - belongs to different identity (${sessionPublicKey.substring(0, 16)}... vs ${currentPublicKey.substring(0, 16)}...)`);
+                }
+                continue; // Skip this session - it belongs to a different identity
+              }
+
               validSessions.push({
                 sessionId,
                 deviceId: '',
                 expiresAt: new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString(),
                 lastActive: now.toISOString(),
-                userId: validation.user.id?.toString() ?? '',
+                publicKey: sessionPublicKey, // Canonical user identity
+                userId: validation.user.id?.toString(), // Optional MongoDB ObjectId for backward compatibility
                 isCurrent: sessionId === storedActiveSessionId,
               });
             }
@@ -615,6 +644,13 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
 
         if (validSessions.length > 0) {
           updateSessions(validSessions, { merge: false });
+        } else if (currentPublicKey && storedSessionIds.length > 0) {
+          // All sessions were filtered out due to identity mismatch - clear stored sessions
+          if (__DEV__) {
+            logger('All stored sessions belong to different identity - clearing session storage');
+          }
+          await storage.removeItem(storageKeys.sessionIds);
+          await storage.removeItem(storageKeys.activeSessionId);
         }
       }
 
@@ -726,9 +762,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     return isAuthenticatedFromStore || isAuthenticatedFromSessions;
   }, [isAuthenticatedFromStore, isAuthenticatedFromSessions]);
 
-  // Get userId from JWT token (MongoDB ObjectId) for socket room matching
-  // user.id is set to publicKey for compatibility, but socket rooms use MongoDB ObjectId
-  // The JWT token's userId field contains the MongoDB ObjectId
+  // Get userId from JWT token for socket room matching
+  // Note: JWT token may contain MongoDB ObjectId internally, but user.id is publicKey (canonical identity)
+  // Socket rooms may need internal mapping from publicKey to MongoDB ObjectId if backend requires it
   const userId = oxyServices.getCurrentUserId() || user?.id;
 
   // Use Zustand store for transfer state management
@@ -748,16 +784,16 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         // Load transfer codes
         const storedCodes = await storage.getItem(TRANSFER_CODES_STORAGE_KEY);
         const storedActiveTransferId = await storage.getItem(ACTIVE_TRANSFER_STORAGE_KEY);
-        
+
         const parsedCodes = storedCodes ? JSON.parse(storedCodes) : {};
         const activeTransferId = storedActiveTransferId || null;
-        
+
         // Restore to Zustand store (store handles validation and expiration)
         restoreFromStorage(parsedCodes, activeTransferId);
         markRestored();
-        
+
         if (__DEV__ && Object.keys(parsedCodes).length > 0) {
-          logger('Restored transfer codes from storage', { 
+          logger('Restored transfer codes from storage', {
             count: Object.keys(parsedCodes).length,
             hasActiveTransfer: !!activeTransferId,
           });
@@ -782,7 +818,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     const persistTransferCodes = async () => {
       try {
         await storage.setItem(TRANSFER_CODES_STORAGE_KEY, JSON.stringify(transferCodes));
-        
+
         if (activeTransferId) {
           await storage.setItem(ACTIVE_TRANSFER_STORAGE_KEY, activeTransferId);
         } else {
@@ -810,7 +846,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   // Transfer code management functions using Zustand store
   const storeTransferCode = useCallback(async (transferId: string, code: string, sourceDeviceId: string | null, publicKey: string) => {
     storeTransferCodeStore(transferId, code, sourceDeviceId, publicKey);
-    
+
     if (__DEV__) {
       logger('Stored transfer code', { transferId, sourceDeviceId, publicKey: publicKey.substring(0, 16) + '...' });
     }
@@ -822,7 +858,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
 
   const updateTransferState = useCallback(async (transferId: string, state: 'pending' | 'completed' | 'failed') => {
     updateTransferStateStore(transferId, state);
-    
+
     if (__DEV__) {
       logger('Updated transfer state', { transferId, state });
     }
@@ -830,7 +866,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
 
   const clearTransferCode = useCallback(async (transferId: string) => {
     clearTransferCodeStore(transferId);
-    
+
     if (__DEV__) {
       logger('Cleared transfer code', { transferId });
     }
@@ -872,7 +908,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         const storedTransfer = getTransferCode(data.transferId);
 
         if (!storedTransfer) {
-          logger('Transfer code not found for transferId', { 
+          logger('Transfer code not found for transferId', {
             transferId: data.transferId,
           });
           toast.error('Transfer verification failed: Code not found. Identity will not be deleted.');
@@ -894,7 +930,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
         // Verify deviceId matches - very lenient since publicKey is the critical check
         // If publicKey matches, we allow deletion even if deviceId doesn't match exactly
         // This handles cases where deviceId might not be available or slightly different
-        const deviceIdMatches = 
+        const deviceIdMatches =
           // Exact match
           (data.sourceDeviceId && data.sourceDeviceId === currentDeviceId) ||
           // Stored sourceDeviceId matches current deviceId
@@ -974,7 +1010,7 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
           }
 
           await deleteIdentityAndClearAccount(false, false, true);
-          
+
           // Verify identity was actually deleted
           const identityDeleted = !(await KeyManager.hasIdentity());
           if (!identityDeleted) {

package/src/ui/context/hooks/useAuthOperations.ts

@@ -146,9 +146,9 @@ export const useAuthOperations = ({
         const localDeviceId = `device_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
         const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(); // 7 days
 
-        // Create minimal user object with publicKey as id
+        // Create minimal user object with publicKey as id (canonical identity)
         fullUser = {
-          id: publicKey, // Use publicKey as id (per migration document)
+          id: publicKey, // publicKey is the canonical user identity
           publicKey,
           username: '',
           privacySettings: {},
@@ -170,7 +170,7 @@ export const useAuthOperations = ({
           deviceId: localDeviceId,
           expiresAt,
           lastActive: new Date().toISOString(),
-          userId: publicKey,
+          publicKey, // Canonical user identity
           isCurrent: true,
         };
 
@@ -204,17 +204,10 @@ export const useAuthOperations = ({
         // Get full user data
         fullUser = await oxyServices.getUserBySession(sessionResponse.sessionId);
         
-        // IMPORTANT: user.id should be MongoDB ObjectId, not publicKey
-        // The API should return the correct id (ObjectId) from the database
-        // If it doesn't, we need to fix the API, not work around it here
-        // Validate that id is ObjectId format (24 hex characters)
-        if (fullUser.id && !/^[0-9a-fA-F]{24}$/.test(fullUser.id)) {
-          console.warn('[useAuthOperations] User.id is not MongoDB ObjectId format:', {
-            id: fullUser.id.substring(0, 20),
-            publicKey: fullUser.publicKey.substring(0, 20),
-            message: 'API should return MongoDB ObjectId as user.id, not publicKey'
-          });
-          // Don't override - let the API fix this issue
+        // user.id is now publicKey (canonical identity) - this is correct
+        // Ensure publicKey field is set for consistency
+        if (!fullUser.publicKey && fullUser.id) {
+          fullUser.publicKey = fullUser.id;
         }
 
         // Fetch device sessions
@@ -222,7 +215,8 @@ export const useAuthOperations = ({
         try {
           allDeviceSessions = await fetchSessionsWithFallback(oxyServices, sessionResponse.sessionId, {
             fallbackDeviceId: sessionResponse.deviceId,
-            fallbackUserId: fullUser.id,
+            fallbackUserId: fullUser.id, // Still pass for backward compatibility
+            fallbackPublicKey: fullUser.publicKey || fullUser.id, // publicKey is canonical identity
             logger,
           });
         } catch (error) {
@@ -292,6 +286,13 @@ export const useAuthOperations = ({
       setAuthState({ isLoading: true, error: null });
 
       try {
+        // SESSION CLEANUP: Clear all sessions before creating new identity
+        // New identity means old sessions are no longer valid
+        await clearSessionState();
+        if (__DEV__ && logger) {
+          logger('Cleared all sessions before creating new identity');
+        }
+
         // Generate new key pair directly (works offline)
         const { publicKey, privateKey } = await KeyManager.generateKeyPair();
         await KeyManager.importKeyPair(privateKey);
@@ -463,6 +464,13 @@ export const useAuthOperations = ({
       setAuthState({ isLoading: true, error: null });
 
       try {
+        // SESSION CLEANUP: Clear all sessions before importing new identity
+        // Importing a different identity means old sessions are no longer valid
+        await clearSessionState();
+        if (__DEV__ && logger) {
+          logger('Cleared all sessions before importing identity');
+        }
+
         // Decrypt private key from backup data
         const Crypto = await import('expo-crypto');
         

package/src/ui/hooks/auth/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth-related hooks
+ */
+export { useUsernameValidation, USERNAME_MIN_LENGTH, USERNAME_REGEX, USERNAME_FORMAT_ERROR, USERNAME_DEBOUNCE_MS } from './useUsernameValidation';
+export type { UsernameValidationResult } from './useUsernameValidation';
+
+

package/src/ui/hooks/auth/useUsernameValidation.ts

@@ -0,0 +1,177 @@
+import { useMemo } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type { OxyServices } from '../../../core';
+import { handleHttpError, ErrorCodes } from '../../../utils/errorUtils';
+import { useDebounce } from '../../../utils/hookUtils';
+
+/**
+ * Username validation constants
+ */
+export const USERNAME_MIN_LENGTH = 4;
+export const USERNAME_REGEX = /^[a-z0-9]+$/i;
+export const USERNAME_FORMAT_ERROR = 'You can use a-z, 0-9. Minimum length is 4 characters.';
+export const USERNAME_DEBOUNCE_MS = 500;
+
+/**
+ * Username validation result interface
+ */
+export interface UsernameValidationResult {
+  isValid: boolean;
+  isAvailable: boolean | null; // null = not checked yet
+  error: string | null;
+  isChecking: boolean;
+}
+
+/**
+ * Validate username format using services validation utilities
+ */
+function validateUsernameFormat(username: string): boolean {
+  // Use stricter validation: lowercase alphanumeric only, min 4 chars
+  return username.length >= USERNAME_MIN_LENGTH && USERNAME_REGEX.test(username);
+}
+
+/**
+ * Check if an error is a network or timeout error
+ */
+function isNetworkOrTimeoutError(error: unknown): boolean {
+  const apiError = handleHttpError(error);
+  return (
+    apiError.code === ErrorCodes.NETWORK_ERROR ||
+    apiError.code === ErrorCodes.TIMEOUT ||
+    apiError.code === ErrorCodes.CONNECTION_FAILED
+  );
+}
+
+/**
+ * Extract error message from an unknown error shape
+ */
+function extractAuthErrorMessage(error: unknown, fallbackMessage = 'An error occurred'): string {
+  const apiError = handleHttpError(error);
+  return apiError.message || fallbackMessage;
+}
+
+/**
+ * Hook for username validation with debouncing and availability checking
+ * 
+ * Uses TanStack Query for efficient API calls with:
+ * - Automatic request cancellation when username changes
+ * - Built-in caching (same username checked multiple times = cached result)
+ * - Request deduplication (multiple components checking same username = single request)
+ * - Proper error handling
+ * 
+ * @param username - The username to validate
+ * @param oxyServices - OxyServices instance for API calls
+ * @returns Username validation state and result
+ */
+export function useUsernameValidation(
+  username: string,
+  oxyServices: OxyServices | null
+): UsernameValidationResult {
+  // Debounce the username input to avoid excessive API calls
+  const debouncedUsername = useDebounce(username.trim().toLowerCase(), USERNAME_DEBOUNCE_MS);
+  
+  // Validate format synchronously (no API call needed)
+  const isValid = useMemo(() => validateUsernameFormat(username), [username]);
+  
+  // Determine if we should check availability
+  const shouldCheckAvailability = useMemo(() => {
+    if (!debouncedUsername || debouncedUsername.length < USERNAME_MIN_LENGTH) {
+      return false;
+    }
+    return validateUsernameFormat(debouncedUsername);
+  }, [debouncedUsername]);
+  
+  // Use TanStack Query for the API call
+  // This provides automatic caching, request cancellation, and deduplication
+  const {
+    data: availabilityResult,
+    isLoading: isChecking,
+    error: queryError,
+    isFetching,
+  } = useQuery({
+    queryKey: ['username', 'availability', debouncedUsername],
+    queryFn: async () => {
+      if (!oxyServices) {
+        throw new Error('OxyServices not available');
+      }
+      return await oxyServices.checkUsernameAvailability(debouncedUsername);
+    },
+    enabled: shouldCheckAvailability && !!oxyServices,
+    staleTime: 5 * 60 * 1000, // Cache for 5 minutes (usernames don't change often)
+    gcTime: 30 * 60 * 1000, // Keep in cache for 30 minutes
+    retry: (failureCount, error) => {
+      // Don't retry on network/timeout errors (user might be offline)
+      if (isNetworkOrTimeoutError(error)) {
+        return false;
+      }
+      // Retry up to 2 times for other errors
+      return failureCount < 2;
+    },
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 3000),
+  });
+  
+  // Compute the result based on validation and query state
+  return useMemo(() => {
+    // If username is too short or invalid format, return early validation
+    if (!username || username.length < USERNAME_MIN_LENGTH) {
+      return {
+        isValid: false,
+        isAvailable: null,
+        error: null,
+        isChecking: false,
+      };
+    }
+    
+    if (!isValid) {
+      return {
+        isValid: false,
+        isAvailable: false,
+        error: USERNAME_FORMAT_ERROR,
+        isChecking: false,
+      };
+    }
+    
+    // If we're not checking yet (debounce period), show checking state only if user is typing
+    const isCurrentlyChecking = isChecking || isFetching;
+    
+    // Handle network/timeout errors gracefully
+    if (queryError && isNetworkOrTimeoutError(queryError)) {
+      // Allow proceeding if offline/network issue (optimistic)
+      return {
+        isValid: true,
+        isAvailable: true, // Optimistic: allow proceeding
+        error: null,
+        isChecking: false,
+      };
+    }
+    
+    // Handle other errors
+    if (queryError) {
+      return {
+        isValid: true,
+        isAvailable: false,
+        error: extractAuthErrorMessage(queryError, 'Failed to check username availability'),
+        isChecking: false,
+      };
+    }
+    
+    // If we have a result, use it
+    if (availabilityResult) {
+      return {
+        isValid: true,
+        isAvailable: availabilityResult.available,
+        error: availabilityResult.available ? null : (availabilityResult.message || 'Username is already taken'),
+        isChecking: false,
+      };
+    }
+    
+    // Still checking (or waiting for debounce)
+    return {
+      isValid: true,
+      isAvailable: null,
+      error: null,
+      isChecking: isCurrentlyChecking,
+    };
+  }, [username, isValid, availabilityResult, isChecking, isFetching, queryError]);
+}
+

package/src/ui/hooks/index.ts

@@ -1,4 +1,5 @@
 export { useFollow, useFollowerCounts } from './useFollow';
 export { useFileDownloadUrl, setOxyFileUrlInstance } from './useFileDownloadUrl';
 export { useThemeStyles } from './useThemeStyles';
-export { useThemeColors } from './useThemeColors';
+export { useThemeColors } from './useThemeColors';
+export * from './auth';

package/src/ui/hooks/mutations/index.ts

@@ -12,6 +12,8 @@ export {
   useUpdateAccountSettings,
   useUpdatePrivacySettings,
   useUploadFile,
+  useUnblockUser,
+  useUnrestrictUser,
 } from './useAccountMutations';
 
 // Service mutation hooks (sessions, devices)