POWR/docs/technical/auth/centralized_auth_system.md

# Centralized Authentication System

**Last Updated:** 2025-04-02  
**Status:** Proposed  
**Authors:** POWR Team

## Problem Statement

POWR's current authentication implementation experiences performance issues, particularly on Android with Amber integration:

1. **UI Thread Blocking**: The current implementation uses synchronous `startActivityForResult` calls that block the main UI thread while waiting for Amber to respond, causing the app to freeze during signing operations.

2. **Login Performance**: Initial login with Amber is slow due to the synchronous nature of the calls.

3. **Event Signing Freezes**: Each event signing operation (kind 1, 1301, 33401, 33402, etc.) blocks the UI thread, making the app unresponsive when signing events.

4. **Lack of State Management**: The current authentication system uses boolean flags rather than proper state management, causing cascading issues when authentication state changes.

5. **React Hook Inconsistencies**: Components that conditionally use hooks based on authentication state can encounter ordering issues during state transitions.

## Architecture Solution

We propose a comprehensive refactoring of the authentication system with three core components:

### 1. State Machine Pattern

Replace the current boolean-based authentication state with a formal state machine:

```typescript
type AuthState = 
  | { status: 'unauthenticated' }
  | { status: 'authenticating', method: 'private_key' | 'amber' | 'ephemeral' }
  | { status: 'authenticated', user: NDKUser, method: 'private_key' | 'amber' | 'ephemeral' }
  | { status: 'signing', operationCount: number, operations: SigningOperation[] }
  | { status: 'error', error: Error };
```

This approach provides:
- Clear, defined transitions between authentication states
- Prevention of invalid state transitions
- Consistent state management across components
- Better error handling and recovery

### 2. Background Processing & Queue Management

Implement a non-blocking operation model for Amber communications:

1. **Thread Pool in Native Layer**: Create a dedicated thread pool for Amber operations in the Kotlin layer
2. **Operation Queue in JS Layer**: Implement a queue system to manage signing operations
3. **Asynchronous Bridge**: Convert the current synchronous API to a fully asynchronous model

This approach eliminates UI freezing by moving all Amber operations off the main thread.

### 3. Centralized Authentication Service

Create a new service layer to centralize authentication logic:

```
lib/
├── auth/                              # New centralized auth directory
│   ├── AuthProvider.tsx               # React Context Provider 
│   ├── AuthService.ts                 # Core authentication service
│   ├── SigningQueue.ts                # Background queue for signing operations
│   ├── AuthStateManager.ts            # Authentication state machine
│   └── types.ts                       # Type definitions
```

This provides:
- Single source of truth for authentication state
- Clean separation of concerns
- Consistent interface for components
- Improved testability

## Implementation Details

### Native Layer Changes (Kotlin)

Modify `AmberSignerModule.kt` to use a background thread pool:

```kotlin
private val executorService = Executors.newFixedThreadPool(2)
private val mainHandler = Handler(Looper.getMainLooper())
private val pendingPromises = ConcurrentHashMap<String, Promise>()

@ReactMethod
fun signEvent(eventJson: String, currentUserPubkey: String, eventId: String?, promise: Promise) {
    // Execute in background thread pool
    executorService.execute {
        try {
            // Create intent - similar to current code
            val intent = createSignEventIntent(eventJson, currentUserPubkey, eventId)
            
            // Store promise with a unique ID for correlation
            val requestId = UUID.randomUUID().toString()
            pendingPromises[requestId] = promise
            intent.putExtra("requestId", requestId)
            
            // Launch activity from main thread
            mainHandler.post {
                try {
                    currentActivity?.startActivityForResult(intent, REQUEST_CODE_SIGN)
                } catch (e: Exception) {
                    pendingPromises.remove(requestId)?.reject("E_LAUNCH_ERROR", e.message)
                }
            }
        } catch (e: Exception) {
            promise.reject("E_PREPARATION_ERROR", e.message)
        }
    }
}
```

### JavaScript Layer: SigningQueue Implementation

Based on insights from the NDK-mobile repo's signer implementations, we'll create an enhanced SigningQueue:

```typescript
// lib/auth/SigningQueue.ts
export class SigningQueue {
  private queue: SigningOperation[] = [];
  private processing = false;
  private maxConcurrent = 1; // Limit concurrent operations
  private activeCount = 0;

  async enqueue(event: NostrEvent): Promise<string> {
    return new Promise((resolve, reject) => {
      // Add to queue and process
      this.queue.push({ event, resolve, reject });
      this.processQueue();
    });
  }

  private async processQueue() {
    if (this.processing || this.activeCount >= this.maxConcurrent || this.queue.length === 0) {
      return;
    }

    this.processing = true;
    
    try {
      const operation = this.queue.shift()!;
      this.activeCount++;
      
      try {
        // Update state to show signing in progress
        AuthStateManager.setSigningInProgress(true, operation);
        
        // Perform the actual signing operation
        const signature = await ExternalSignerUtils.signEvent(
          operation.event, 
          operation.event.pubkey
        );
        
        operation.resolve(signature);
      } catch (error) {
        operation.reject(error);
      } finally {
        this.activeCount--;
        AuthStateManager.setSigningInProgress(false, operation);
      }
    } finally {
      this.processing = false;
      // Continue processing if items remain
      if (this.queue.length > 0) {
        this.processQueue();
      }
    }
  }
}
```

### Enhanced NDKAmberSigner

Inspired by the NDK-mobile `NDKNip55Signer` implementation:

```typescript
// lib/signers/EnhancedNDKAmberSigner.ts
export default class EnhancedNDKAmberSigner implements NDKSigner {
  private static signingQueue = new SigningQueue();
  private _pubkey: string;
  private _user?: NDKUser;
  
  constructor(pubkey: string, packageName: string) {
    this._pubkey = pubkey;
    this.packageName = packageName;
  }
  
  /**
   * Blocks until the signer is ready and returns the associated NDKUser.
   */
  async blockUntilReady(): Promise<NDKUser> {
    if (this._user) return this._user;
    
    this._user = new NDKUser({ pubkey: this._pubkey });
    return this._user;
  }
  
  /**
   * Getter for the user property.
   */
  async user(): Promise<NDKUser> {
    return this.blockUntilReady();
  }
  
  /**
   * Signs the given Nostr event using the queue-based system
   */
  async sign(event: NostrEvent): Promise<string> {
    console.log('AMBER SIGNER SIGNING', event);
    // Use the queue instead of direct signing
    return EnhancedNDKAmberSigner.signingQueue.enqueue(event);
  }
  
  getPublicKey(): string {
    return this._pubkey;
  }
}
```

### Zustand-Based Auth Store

Drawing from the NDK-mobile store implementation:

```typescript
// lib/auth/AuthStore.ts
export const useAuthStore = create<AuthState & AuthActions>((set, get) => ({
  status: 'unauthenticated',
  user: null,
  method: null,
  signingOperations: [],
  error: null,
  
  setAuthenticating: (method) => {
    set({ 
      status: 'authenticating',
      method 
    });
  },
  
  setAuthenticated: (user, method) => {
    set({
      status: 'authenticated',
      user,
      method,
      error: null
    });
  },
  
  setSigningInProgress: (inProgress, operation) => {
    const currentState = get();
    
    if (inProgress) {
      // Add operation to signing state
      set({
        status: 'signing',
        operationCount: (currentState.status === 'signing' ? currentState.operationCount : 0) + 1,
        signingOperations: [
          ...(currentState.status === 'signing' ? currentState.signingOperations : []),
          operation
        ]
      });
    } else {
      // Remove operation from signing state
      const operations = currentState.status === 'signing' 
        ? currentState.signingOperations.filter(op => op !== operation)
        : [];
        
      if (operations.length === 0) {
        // Return to authenticated state if no more operations
        set({
          status: 'authenticated',
          user: currentState.user,
          method: currentState.method,
        });
      } else {
        // Update count but stay in signing state
        set({
          signingOperations: operations,
          operationCount: operations.length
        });
      }
    }
  },
  
  logout: () => {
    // Clear NDK signer
    if (ndk) ndk.signer = undefined;
    
    // Clear secure storage
    SecureStore.deleteItemAsync(PRIVATE_KEY_STORAGE_KEY);
    AsyncStorage.multiRemove([
      'currentUser',
      'login',
      'signer',
      'auth.last_login'
    ]);
    
    // Reset state
    set({
      status: 'unauthenticated',
      user: null,
      method: null,
      signingOperations: [],
      error: null
    });
  },
  
  setError: (error) => {
    set({
      status: 'error',
      error
    });
  }
}));
```

## Integration with User Avatars and Robohash

As part of our authentication enhancement, we'll integrate the Robohash service for user avatars:

### Avatar Utility Functions

```typescript
// utils/avatar.ts
import { Platform } from 'react-native';

/**
 * Constants for avatar generation
 */
export const AVATAR_PLACEHOLDER = 'https://robohash.org/placeholder?set=set4';

/**
 * Generates a Robohash URL for a given public key
 */
export function generateRobohashUrl(pubkey: string, size = 150): string {
  // Use the pubkey as the seed for Robohash
  // Set 4 is the "kittens" set, which is more visually appealing than robots
  return `https://robohash.org/${pubkey}?set=set4&size=${size}x${size}`;
}

/**
 * Determines the appropriate avatar URL based on authentication state
 */
export function getAvatarUrl(params: {
  profileImageUrl?: string;
  pubkey?: string;
  isAuthenticated: boolean;
  method?: 'private_key' | 'amber' | 'ephemeral';
}): string {
  const { profileImageUrl, pubkey, isAuthenticated, method } = params;
  
  // If we have a profile image URL and it's valid, use it
  if (profileImageUrl && profileImageUrl.startsWith('http')) {
    return profileImageUrl;
  }
  
  // If user is authenticated but doesn't have a profile image,
  // generate a Robohash based on their pubkey
  if (isAuthenticated && pubkey) {
    return generateRobohashUrl(pubkey);
  }
  
  // Use placeholder for unauthenticated or ephemeral users
  return AVATAR_PLACEHOLDER;
}

/**
 * Creates appropriate caching parameters for avatar images
 */
export function getAvatarCacheOptions() {
  return {
    // Images should be cached for 7 days
    expiresIn: 7 * 24 * 60 * 60 * 1000,
    // Use memory cache for better performance
    immutable: true,
    // Platform-specific cache behavior
    ...Platform.select({
      web: {
        cache: 'force-cache'
      },
      default: {
        // React Native specific cache options
      }
    })
  };
}
```

### Enhanced UserAvatar Component

```typescript
// components/UserAvatar.tsx
import React, { useEffect, useState } from 'react';
import { Image, View } from 'react-native';
import { Avatar } from 'components/ui/avatar';
import { useAuthStore } from 'lib/auth/AuthStore';
import { getAvatarUrl, getAvatarCacheOptions } from 'utils/avatar';

export interface UserAvatarProps {
  profileImageUrl?: string;
  pubkey?: string;
  size?: 'sm' | 'md' | 'lg' | number;
  onPress?: () => void;
}

const SIZE_MAP = {
  sm: 32,
  md: 48,
  lg: 64
};

export function UserAvatar({ 
  profileImageUrl, 
  pubkey,
  size = 'md',
  onPress
}: UserAvatarProps) {
  const { status, user, method } = useAuthStore();
  const isAuthenticated = status === 'authenticated' || status === 'signing';
  
  // If no pubkey provided, use the authenticated user's pubkey
  const effectivePubkey = pubkey || (user?.pubkey);
  const numericSize = typeof size === 'number' ? size : SIZE_MAP[size];
  
  // Determine the correct avatar URL
  const avatarUrl = getAvatarUrl({
    profileImageUrl,
    pubkey: effectivePubkey,
    isAuthenticated,
    method
  });
  
  return (
    <Avatar
      size={numericSize}
      onPress={onPress}
      source={{
        uri: avatarUrl,
        ...getAvatarCacheOptions()
      }}
      fallback={
        <Image
          source={{ uri: generateRobohashUrl('placeholder', numericSize) }}
          style={{ width: numericSize, height: numericSize, borderRadius: numericSize / 2 }}
        />
      }
    />
  );
}
```

## iOS Considerations

While the primary performance issues affect Android due to the Amber integration, the centralized authentication system will also benefit iOS in several ways:

1. **Unified Authentication Experience**: The state machine approach ensures consistent authentication behavior across platforms.

2. **Future External Signer Support**: As NIP-55 compliant signers become available on iOS, the architecture is ready to support them.

3. **Enhanced State Management**: The state machine approach improves React hook ordering issues that can affect both platforms.

4. **Consistent UI Feedback**: Authentication state indicators will work consistently across both platforms.

5. **Performance Benefits**: Though iOS doesn't use Amber, the queue-based signature system still benefits performance by preventing multiple simultaneous signing operations.

6. **Cleaner Code Structure**: The centralized authentication service provides a cleaner approach for all platforms, making iOS-specific code easier to maintain.

## Private Key Security

This architecture maintains and enhances the existing security measures for private keys:

### iOS Private Key Storage

On iOS, private keys (nsec) are stored securely using `expo-secure-store`, which leverages iOS's Keychain Services. This provides:

- Data encrypted at rest using the device's security hardware
- Protection from other apps accessing the keychain data
- Automatic removal when the app is uninstalled

The current implementation in `lib/stores/ndk.ts` already uses `SecureStore.setItemAsync(PRIVATE_KEY_STORAGE_KEY, privateKeyHex)` to store private keys securely, and this implementation will be maintained in the new architecture.

### Android Private Key Storage

On Android, private keys are stored using `expo-secure-store`, which leverages Android's EncryptedSharedPreferences. This provides:

- Encryption of both keys and values
- Integration with Android Keystore
- Protection by the device's security model

For Amber users, no private key is stored in POWR at all - only the public key is stored. The private key remains exclusively in the Amber app, providing maximum security.

### Key Lifecycle

The new architecture enhances key security through clear state transitions:

1. **Key Generation**: Generated keys never leave the JavaScript context until stored
2. **Key Storage**: Keys are immediately stored in secure storage
3. **Key Retrieval**: Keys are loaded directly into the signer without unnecessary exposure
4. **Key Deletion**: On logout, keys are completely removed from secure storage

This state machine approach ensures there are no "in-between" states where keys might be exposed.

## NDK Integration Insights

From reviewing the NDK and NDK-mobile repositories, we've incorporated several best practices:

1. **Cleaner Signer Interface**: Based on NDK-mobile's `NDKNip55Signer`, our implementation has a cleaner interface with better error handling and logging.

2. **State Management**: Adopted Zustand-based state management similar to the NDK-mobile approach, but enhanced with our state machine model.

3. **Authentication Flow**: Incorporated the cleaner login/logout flow from NDK store with enhanced persistent state management.

4. **Signer Initialization**: Added `blockUntilReady` pattern to ensure signers are properly initialized before use.

These patterns from the reference repositories provide a solid foundation for our enhanced architecture while addressing the specific performance issues in our application.

## Migration Strategy

To implement this architecture while minimizing disruption:

### Phased Implementation

1. **Create Core Infrastructure**: First implement the AuthStateManager and SigningQueue without changing existing code
2. **Adapt NDK Store**: Update the NDK store to use the new authentication system
3. **Update Native Module**: Modify AmberSignerModule to use background processing
4. **Component Migration**: Gradually update components to use the new system

### Feature Flag Approach

Implement a feature flag to toggle between old and new authentication systems:

```typescript
const useNewAuthSystem = true; // Toggle for testing

// In NDKStore
if (useNewAuthSystem) {
  // Use new AuthService
} else {
  // Use existing implementation
}
```

This allows for:
- A/B testing during development
- Easy rollback if issues are discovered
- Gradual migration of components

## Benefits

This architecture provides significant improvements:

1. **Immediate Performance Benefits**: Eliminates UI freezing during authentication and signing
2. **Improved User Experience**: Provides visual feedback during signing operations
3. **Enhanced Stability**: Proper state management prevents cascading issues
4. **Better Developer Experience**: Clean separation of concerns makes the code more maintainable
5. **Future Extensibility**: This foundation makes it easier to add features like batch signing
6. **Consistent Avatars**: Users always have a visual representation, whether using robohash or custom images

## Timeline and Resources

### Estimated Timeline

1. **Planning and Design**: 1-2 days
2. **Core Infrastructure**: 3-4 days
3. **Native Module Updates**: 2-3 days
4. **Integration and Testing**: 3-5 days
5. **Component Migration**: 5-7 days (progressive)

**Total**: 2-3 weeks for full implementation

### Resources Required

- 1 React Native developer with TypeScript experience
- 1 Android developer with Kotlin experience
- Testing devices with Amber installed