@oxyhq/services 5.16.39 → 5.16.41

package/src/core/identity-session/DeviceManager.ts

@@ -0,0 +1,273 @@
+/**
+ * Device Manager
+ * 
+ * Manages device identification and device sessions (Native + Web)
+ */
+
+import type { PlatformAdapter } from '../../adapters';
+import type { Device, DeviceInfo } from './types';
+import {
+  createIdentitySessionError,
+  IdentitySessionErrorCodes,
+} from './errors';
+
+const DEVICE_STORAGE_KEY = 'oxy_device_info';
+
+interface StoredDeviceInfo {
+  deviceId: string;
+  deviceName?: string;
+  fingerprint?: string;
+  createdAt: string;
+  lastUsed: string;
+}
+
+/**
+ * Device Manager Class
+ */
+export class DeviceManager {
+  private adapter: PlatformAdapter;
+  private cachedDevice: Device | null = null;
+
+  constructor(adapter: PlatformAdapter) {
+    this.adapter = adapter;
+  }
+
+  /**
+   * Invalidate cached device
+   */
+  invalidateCache(): void {
+    this.cachedDevice = null;
+  }
+
+  /**
+   * Get device fingerprint
+   */
+  private getDeviceFingerprint(): Record<string, unknown> {
+    const fingerprint: Record<string, unknown> = {
+      userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'unknown',
+      platform: typeof navigator !== 'undefined' ? navigator.platform : 'unknown',
+      language: typeof navigator !== 'undefined' ? navigator.language : undefined,
+      timezone: typeof Intl !== 'undefined' ? Intl.DateTimeFormat().resolvedOptions().timeZone : undefined,
+    };
+
+    // Add screen info if available
+    if (typeof screen !== 'undefined') {
+      fingerprint.screen = {
+        width: screen.width,
+        height: screen.height,
+        colorDepth: screen.colorDepth,
+      };
+    }
+
+    return fingerprint;
+  }
+
+  /**
+   * Generate a unique device ID
+   */
+  private async generateDeviceId(): Promise<string> {
+    const randomBytes = await this.adapter.crypto.getRandomBytes(32);
+    return Array.from(randomBytes, byte => byte.toString(16).padStart(2, '0')).join('');
+  }
+
+  /**
+   * Get a user-friendly device name based on platform
+   */
+  private getDefaultDeviceName(): string {
+    const fingerprint = this.getDeviceFingerprint();
+    const platform = (fingerprint.platform as string || '').toLowerCase();
+    const userAgent = (fingerprint.userAgent as string || '').toLowerCase();
+
+    if (platform.includes('win')) return 'Windows Computer';
+    if (platform.includes('mac')) return 'Mac Computer';
+    if (platform.includes('linux')) return 'Linux Computer';
+    if (userAgent.includes('iphone')) return 'iPhone';
+    if (userAgent.includes('ipad')) return 'iPad';
+    if (userAgent.includes('android')) return 'Android Device';
+    if (this.adapter.platform === 'web') return 'Web Browser';
+
+    return 'Unknown Device';
+  }
+
+  /**
+   * Get stored device info or create new one
+   */
+  async getCurrentDevice(): Promise<Device | null> {
+    if (this.cachedDevice) {
+      return this.cachedDevice;
+    }
+
+    try {
+      const stored = await this.adapter.storage.get(DEVICE_STORAGE_KEY);
+
+      if (stored) {
+        const deviceInfo: StoredDeviceInfo = JSON.parse(stored);
+
+        // Update last used timestamp
+        deviceInfo.lastUsed = new Date().toISOString();
+        await this.saveDeviceInfo(deviceInfo);
+
+        const device: Device = {
+          deviceId: deviceInfo.deviceId,
+          deviceName: deviceInfo.deviceName,
+          deviceType: this.getDeviceType(),
+          platform: this.adapter.platform === 'native' ? 'ios' : 'web', // Simplified
+          fingerprint: deviceInfo.fingerprint,
+          createdAt: deviceInfo.createdAt,
+          updatedAt: deviceInfo.lastUsed,
+        };
+
+        this.cachedDevice = device;
+        return device;
+      }
+
+      // Create new device info
+      return await this.createNewDevice();
+    } catch (error) {
+      console.error('[DeviceManager] Error getting device info:', error);
+      return await this.createNewDevice();
+    }
+  }
+
+  /**
+   * Create new device info and store it
+   */
+  async createNewDevice(): Promise<Device> {
+    const deviceId = await this.generateDeviceId();
+    const fingerprint = JSON.stringify(this.getDeviceFingerprint());
+    const now = new Date().toISOString();
+
+    const device: Device = {
+      deviceId,
+      deviceName: this.getDefaultDeviceName(),
+      deviceType: this.getDeviceType(),
+      platform: this.adapter.platform === 'native' ? 'ios' : 'web', // Simplified
+      fingerprint,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    const deviceInfo: StoredDeviceInfo = {
+      deviceId,
+      deviceName: device.deviceName,
+      fingerprint,
+      createdAt: now,
+      lastUsed: now,
+    };
+
+    await this.saveDeviceInfo(deviceInfo);
+    this.cachedDevice = device;
+
+    return device;
+  }
+
+  /**
+   * Get device type
+   */
+  private getDeviceType(): string {
+    if (this.adapter.platform === 'web') {
+      return 'desktop'; // Simplified - could detect mobile web
+    }
+    // For native, would need Platform.OS detection
+    return 'mobile';
+  }
+
+  /**
+   * Save device info to storage
+   */
+  private async saveDeviceInfo(deviceInfo: StoredDeviceInfo): Promise<void> {
+    try {
+      await this.adapter.storage.set(DEVICE_STORAGE_KEY, JSON.stringify(deviceInfo));
+    } catch (error) {
+      console.error('[DeviceManager] Error saving device info:', error);
+      throw createIdentitySessionError(
+        IdentitySessionErrorCodes.DEVICE_CREATION_FAILED,
+        `Failed to save device info: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Update device name
+   */
+  async updateDeviceName(deviceName: string): Promise<Device> {
+    const device = await this.getCurrentDevice();
+    if (!device) {
+      throw createIdentitySessionError(
+        IdentitySessionErrorCodes.DEVICE_NOT_FOUND,
+        'Device not found'
+      );
+    }
+
+    device.deviceName = deviceName;
+    device.updatedAt = new Date().toISOString();
+
+    const deviceInfo: StoredDeviceInfo = {
+      deviceId: device.deviceId,
+      deviceName: device.deviceName,
+      fingerprint: device.fingerprint,
+      createdAt: device.createdAt || new Date().toISOString(),
+      lastUsed: device.updatedAt,
+    };
+
+    await this.saveDeviceInfo(deviceInfo);
+    this.cachedDevice = device;
+
+    return device;
+  }
+
+  /**
+   * Get device info for session creation
+   */
+  async getDeviceInfo(): Promise<DeviceInfo> {
+    const device = await this.getCurrentDevice();
+    if (!device) {
+      throw createIdentitySessionError(
+        IdentitySessionErrorCodes.DEVICE_NOT_FOUND,
+        'Device not found'
+      );
+    }
+
+    const fingerprint = this.getDeviceFingerprint();
+
+    return {
+      deviceName: device.deviceName,
+      deviceType: device.deviceType,
+      platform: device.platform,
+      browser: typeof navigator !== 'undefined' ? this.getBrowserName() : undefined,
+      os: typeof navigator !== 'undefined' ? navigator.platform : undefined,
+      lastActive: new Date().toISOString(),
+      userAgent: fingerprint.userAgent as string,
+      fingerprint: device.fingerprint,
+    };
+  }
+
+  /**
+   * Get browser name from user agent
+   */
+  private getBrowserName(): string | undefined {
+    if (typeof navigator === 'undefined') return undefined;
+
+    const ua = navigator.userAgent.toLowerCase();
+    if (ua.includes('chrome')) return 'Chrome';
+    if (ua.includes('firefox')) return 'Firefox';
+    if (ua.includes('safari') && !ua.includes('chrome')) return 'Safari';
+    if (ua.includes('edge')) return 'Edge';
+    if (ua.includes('opera')) return 'Opera';
+
+    return undefined;
+  }
+
+  /**
+   * Clear stored device info
+   */
+  async clearDeviceInfo(): Promise<void> {
+    try {
+      await this.adapter.storage.remove(DEVICE_STORAGE_KEY);
+      this.invalidateCache();
+    } catch (error) {
+      console.error('[DeviceManager] Error clearing device info:', error);
+    }
+  }
+}
+

package/src/core/identity-session/INTEGRATION_GUIDE.md

@@ -0,0 +1,287 @@
+# Identity Session Core - Integration Guide
+
+## Overview
+
+The Identity Session Core provides a unified API for identity and session management across all platforms (React Native, Web, Node). All identity and session operations go through this core - never access `KeyManager`, storage, or APIs directly.
+
+## Architecture
+
+```
+UI/Hooks Layer
+    ↓
+IdentitySessionCore (unified API)
+    ↓
+Managers (Identity, Session, Device, Refresh)
+    ↓
+Platform Adapters (Expo 54, Node)
+```
+
+## Key Principles
+
+1. **Frontend: Use `useOxy()` hook** - This is the only API you need for React/React Native applications
+2. **Backend: Use `createIdentitySessionCore()`** - Only for Node.js/backend applications
+3. **Never access storage, APIs, or KeyManager directly** - Always go through the core or `useOxy()`
+4. **Identity operations are NATIVE ONLY** - Web cannot create/import identities
+5. **Session operations work on NATIVE + WEB** - sessions can be used on both platforms
+6. **Models are aligned with backend** - same types, same error codes
+
+## Installation
+
+```bash
+npm install @oxyhq/services
+```
+
+## Basic Usage
+
+### Using the React Hook (Recommended)
+
+```typescript
+import { OxyProvider, useOxy } from '@oxyhq/services';
+import { Platform } from 'react-native';
+
+function App() {
+  return (
+    <OxyProvider baseURL="https://api.example.com">
+      <MyComponent />
+    </OxyProvider>
+  );
+}
+
+function MyComponent() {
+  const { createIdentity, signIn, hasIdentity, isLoading, error } = useOxy();
+
+  const handleCreateIdentity = async () => {
+    if (Platform.OS === 'web') {
+      alert('Identity creation is only available on native platforms');
+      return;
+    }
+
+    try {
+      const result = await createIdentity('myusername');
+      console.log('Identity created, synced:', result.synced);
+    } catch (err) {
+      console.error('Failed to create identity:', err);
+    }
+  };
+
+  const handleSignIn = async () => {
+    try {
+      const user = await signIn('My Device');
+      console.log('Signed in:', user);
+    } catch (err) {
+      console.error('Failed to sign in:', err);
+    }
+  };
+
+  if (error) return <Text>Error: {error}</Text>;
+  if (isLoading) return <Text>Loading...</Text>;
+
+  return (
+    <View>
+      <Button onPress={handleCreateIdentity} title="Create Identity" />
+      <Button onPress={handleSignIn} title="Sign In" />
+    </View>
+  );
+}
+```
+
+### Direct Core Usage (Backend/Node.js Only)
+
+**Note:** For frontend applications, always use `useOxy()` hook. Direct core usage is only for backend/Node.js applications.
+
+```typescript
+import { createIdentitySessionCore } from '@oxyhq/services';
+
+// Backend/Node.js only
+const core = await createIdentitySessionCore('https://api.example.com');
+const identity = await core.getCurrentIdentity();
+const session = await core.getSession();
+```
+
+## API Reference
+
+### Using `useOxy` Hook (Recommended)
+
+The `useOxy` hook provides all identity and session operations through a simple, reactive API:
+
+```typescript
+const {
+  // Identity (Native Only)
+  createIdentity,
+  importIdentity,
+  deleteIdentityAndClearAccount,
+  hasIdentity,
+  getPublicKey,
+  isIdentitySynced,
+  syncIdentity,
+  identity,
+  publicKey,
+  identitySyncState,
+
+  // Session (Native + Web)
+  signIn,
+  logout,
+  logoutAll,
+  switchSession,
+  refreshSession,
+  session,
+  sessions,
+  activeSessionId,
+  isAuthenticated,
+
+  // Device (Native + Web)
+  getDeviceSessions,
+  logoutAllDeviceSessions,
+  updateDeviceName,
+  device,
+
+  // State
+  user,
+  isLoading,
+  isTokenReady,
+  isStorageReady,
+  error,
+} = useOxy();
+```
+
+### Identity Operations (Native Only)
+
+```typescript
+// Create new identity
+const result = await createIdentity(username?);
+// result.synced indicates if identity was synced with backend
+
+// Import identity from backup
+const result = await importIdentity(backupData, password, username?);
+// result.synced indicates if identity was synced with backend
+
+// Delete identity and clear all account data
+await deleteIdentityAndClearAccount(skipBackup?, force?, userConfirmed?);
+
+// Check if identity exists
+const has = await hasIdentity();
+
+// Get public key
+const publicKey = await getPublicKey();
+
+// Check if identity is synced
+const synced = await isIdentitySynced();
+
+// Manually sync identity
+const user = await syncIdentity(username?);
+```
+
+### Session Operations (Native + Web)
+
+```typescript
+// Sign in (create session)
+const user = await signIn(deviceName?);
+
+// Logout (invalidate current or specific session)
+await logout(sessionId?);
+
+// Logout all sessions
+await logoutAll();
+
+// Switch to different session
+await switchSession(sessionId);
+
+// Refresh current session
+const session = await refreshSession();
+```
+
+### Device Operations (Native + Web)
+
+```typescript
+// Get all device sessions
+const deviceSessions = await getDeviceSessions();
+
+// Logout all sessions for current device
+await logoutAllDeviceSessions();
+
+// Update device name
+await updateDeviceName(deviceName);
+```
+
+### Direct Core Usage (Advanced)
+
+For advanced use cases, you can access the core directly:
+
+```typescript
+import { createIdentitySessionCore } from '@oxyhq/services';
+
+const core = await createIdentitySessionCore('https://api.example.com');
+const identity = await core.getCurrentIdentity();
+const session = await core.getSession();
+
+// Subscribe to events
+const unsubscribe = core.subscribe((event) => {
+  switch (event.type) {
+    case 'identity:created':
+      console.log('Identity created:', event.identity);
+      break;
+    case 'session:created':
+      console.log('Session created:', event.session);
+      break;
+    case 'session:invalidated':
+      console.log('Session invalidated:', event.sessionId);
+      break;
+  }
+});
+
+// Cleanup
+unsubscribe();
+```
+
+## Error Handling
+
+All errors use unified error codes:
+
+```typescript
+import { 
+  IdentitySessionError, 
+  IdentitySessionErrorCodes 
+} from '@oxyhq/services';
+
+try {
+  await createIdentity();
+} catch (error) {
+  if (error instanceof IdentitySessionError) {
+    switch (error.code) {
+      case IdentitySessionErrorCodes.IDENTITY_NOT_AVAILABLE_ON_WEB:
+        // Handle web platform error
+        break;
+      case IdentitySessionErrorCodes.IDENTITY_ALREADY_EXISTS:
+        // Handle already exists error
+        break;
+      default:
+        console.error('Error:', error.message);
+    }
+  }
+}
+```
+
+## Type Exports
+
+```typescript
+import type {
+  Identity,
+  Session,
+  Device,
+  DeviceInfo,
+  BackupData,
+  IdentitySessionEvent,
+} from '@oxyhq/services';
+```
+
+## Platform Detection
+
+The core automatically detects the platform and validates operations. Identity operations will throw `IDENTITY_NOT_AVAILABLE_ON_WEB` on web platforms.
+
+## Notes
+
+- The core handles all platform-specific logic internally
+- Storage, crypto, and fetch are abstracted through platform adapters
+- All models are aligned with backend (IUser, ISession)
+- Error codes are unified across frontend and backend
+- The core is designed to be "plugged in" to any Oxy app (Mention, Homiio, Noted, etc.)