@oxyhq/services 5.16.39 → 5.16.41

package/lib/module/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.)

package/lib/module/core/identity-session/IdentityManager.js

@@ -0,0 +1,395 @@
+"use strict";
+
+/**
+ * Identity Manager
+ * 
+ * Manages cryptographic identity (OxyID) - SOLO NATIVE
+ * Handles key generation, storage, import, export, and signing operations.
+ */
+
+import { createIdentitySessionError, IdentitySessionErrorCodes } from './errors';
+import { isValidPublicKey, isValidPrivateKey, derivePublicKey, getEllipticCurve } from '../../crypto/core';
+const ec = getEllipticCurve();
+const STORAGE_KEYS = {
+  PRIVATE_KEY: 'oxy_identity_private_key',
+  PUBLIC_KEY: 'oxy_identity_public_key',
+  BACKUP_PRIVATE_KEY: 'oxy_identity_backup_private_key',
+  BACKUP_PUBLIC_KEY: 'oxy_identity_backup_public_key',
+  BACKUP_TIMESTAMP: 'oxy_identity_backup_timestamp'
+};
+
+/**
+ * Identity Manager Class
+ */
+export class IdentityManager {
+  cachedPublicKey = null;
+  cachedHasIdentity = null;
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+
+  /**
+   * Invalidate cached identity state
+   */
+  invalidateCache() {
+    this.cachedPublicKey = null;
+    this.cachedHasIdentity = null;
+  }
+
+  /**
+   * Check if identity operations are available (only on native)
+   */
+  ensureNativePlatform() {
+    if (this.adapter.platform !== 'native') {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.IDENTITY_NOT_AVAILABLE_ON_WEB, 'Identity operations are only available on native platforms (iOS/Android)');
+    }
+    if (!this.adapter.storage.isSecureStorageAvailable()) {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.SECURE_STORAGE_NOT_AVAILABLE, 'Secure storage is not available on this platform');
+    }
+  }
+
+  /**
+   * Convert Uint8Array to hexadecimal string
+   */
+  uint8ArrayToHex(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+
+  /**
+   * Generate a new ECDSA secp256k1 key pair
+   */
+  async generateKeyPair() {
+    this.ensureNativePlatform();
+    const randomBytes = await this.adapter.crypto.getRandomBytes(32);
+    const privateKeyHex = this.uint8ArrayToHex(randomBytes);
+    const keyPair = ec.keyFromPrivate(privateKeyHex);
+    return {
+      privateKey: keyPair.getPrivate('hex'),
+      publicKey: keyPair.getPublic('hex')
+    };
+  }
+
+  /**
+   * Create a new identity (generate and store key pair)
+   */
+  async createIdentity() {
+    this.ensureNativePlatform();
+    const {
+      privateKey,
+      publicKey
+    } = await this.generateKeyPair();
+    await this.adapter.storage.secureSet(STORAGE_KEYS.PRIVATE_KEY, privateKey);
+    await this.adapter.storage.secureSet(STORAGE_KEYS.PUBLIC_KEY, publicKey);
+
+    // Update cache
+    this.cachedPublicKey = publicKey;
+    this.cachedHasIdentity = true;
+    return publicKey;
+  }
+
+  /**
+   * Import an existing key pair (e.g., from backup file)
+   */
+  async importKeyPair(privateKey) {
+    this.ensureNativePlatform();
+    if (!isValidPrivateKey(privateKey)) {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.INVALID_PRIVATE_KEY, 'Invalid private key format');
+    }
+    const keyPair = ec.keyFromPrivate(privateKey);
+    const publicKey = keyPair.getPublic('hex');
+    if (!isValidPublicKey(publicKey)) {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.INVALID_PUBLIC_KEY, 'Failed to derive valid public key from private key');
+    }
+    await this.adapter.storage.secureSet(STORAGE_KEYS.PRIVATE_KEY, privateKey);
+    await this.adapter.storage.secureSet(STORAGE_KEYS.PUBLIC_KEY, publicKey);
+
+    // Update cache
+    this.cachedPublicKey = publicKey;
+    this.cachedHasIdentity = true;
+    return publicKey;
+  }
+
+  /**
+   * Get the stored private key
+   * WARNING: Only use this for signing operations within the app
+   */
+  async getPrivateKey() {
+    this.ensureNativePlatform();
+    try {
+      return await this.adapter.storage.secureGet(STORAGE_KEYS.PRIVATE_KEY);
+    } catch (error) {
+      console.warn('[IdentityManager] Failed to access secure store:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Get the stored public key (cached for performance)
+   */
+  async getPublicKey() {
+    if (this.adapter.platform !== 'native') {
+      return null; // Identity only exists on native
+    }
+    if (this.cachedPublicKey !== null) {
+      return this.cachedPublicKey;
+    }
+    try {
+      const publicKey = await this.adapter.storage.secureGet(STORAGE_KEYS.PUBLIC_KEY);
+
+      // Cache result (null is a valid cache value meaning no identity)
+      this.cachedPublicKey = publicKey;
+      return publicKey;
+    } catch (error) {
+      // If secure store is not available, return null (no identity)
+      this.cachedPublicKey = null;
+      console.warn('[IdentityManager] Failed to access secure store:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Check if an identity (key pair) exists on this device (cached for performance)
+   */
+  async hasIdentity() {
+    if (this.adapter.platform !== 'native') {
+      return false; // Identity only exists on native
+    }
+    if (this.cachedHasIdentity !== null) {
+      return this.cachedHasIdentity;
+    }
+    try {
+      const privateKey = await this.getPrivateKey();
+      const hasIdentity = privateKey !== null;
+
+      // Cache result
+      this.cachedHasIdentity = hasIdentity;
+      return hasIdentity;
+    } catch (error) {
+      // If we can't check, assume no identity (safer default)
+      this.cachedHasIdentity = false;
+      console.warn('[IdentityManager] Failed to check identity:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Delete the stored identity (both keys)
+   */
+  async deleteIdentity(skipBackup = false, force = false, userConfirmed = false) {
+    this.ensureNativePlatform();
+
+    // CRITICAL SAFEGUARD: Require explicit user confirmation unless force is true
+    if (!force && !userConfirmed) {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.IDENTITY_DELETE_FAILED, 'Identity deletion requires explicit user confirmation');
+    }
+    if (!force) {
+      const hasIdentity = await this.hasIdentity();
+      if (!hasIdentity) {
+        return; // Nothing to delete
+      }
+    }
+
+    // ALWAYS create backup before deletion unless explicitly skipped
+    if (!skipBackup) {
+      try {
+        const backupSuccess = await this.backupIdentity();
+        if (!backupSuccess) {
+          console.warn('[IdentityManager] Failed to backup identity before deletion - proceeding anyway');
+        }
+      } catch (backupError) {
+        console.warn('[IdentityManager] Failed to backup identity before deletion:', backupError);
+      }
+    }
+    await this.adapter.storage.secureDelete(STORAGE_KEYS.PRIVATE_KEY);
+    await this.adapter.storage.secureDelete(STORAGE_KEYS.PUBLIC_KEY);
+
+    // Invalidate cache
+    this.invalidateCache();
+
+    // Also clear backup if force deletion
+    if (force) {
+      try {
+        await this.adapter.storage.secureDelete(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+        await this.adapter.storage.secureDelete(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+        await this.adapter.storage.remove(STORAGE_KEYS.BACKUP_TIMESTAMP);
+      } catch (error) {
+        // Ignore backup deletion errors
+      }
+    }
+  }
+
+  /**
+   * Backup identity to SecureStore (separate backup storage)
+   */
+  async backupIdentity() {
+    this.ensureNativePlatform();
+    try {
+      const privateKey = await this.getPrivateKey();
+      const publicKey = await this.getPublicKey();
+      if (!privateKey || !publicKey) {
+        return false; // Nothing to backup
+      }
+
+      // Store backup in SecureStore (still secure, but separate from primary storage)
+      await this.adapter.storage.secureSet(STORAGE_KEYS.BACKUP_PRIVATE_KEY, privateKey);
+      await this.adapter.storage.secureSet(STORAGE_KEYS.BACKUP_PUBLIC_KEY, publicKey);
+      await this.adapter.storage.set(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+      return true;
+    } catch (error) {
+      console.error('[IdentityManager] Failed to backup identity:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Restore identity from backup if primary storage is corrupted
+   */
+  async restoreIdentityFromBackup() {
+    this.ensureNativePlatform();
+    try {
+      // Invalidate cache before restoring to ensure fresh state
+      this.invalidateCache();
+
+      // Check if backup exists
+      const backupPrivateKey = await this.adapter.storage.secureGet(STORAGE_KEYS.BACKUP_PRIVATE_KEY);
+      const backupPublicKey = await this.adapter.storage.secureGet(STORAGE_KEYS.BACKUP_PUBLIC_KEY);
+      if (!backupPrivateKey || !backupPublicKey) {
+        return false; // No backup available
+      }
+
+      // Verify backup integrity
+      if (!isValidPrivateKey(backupPrivateKey)) {
+        return false;
+      }
+      if (!isValidPublicKey(backupPublicKey)) {
+        return false;
+      }
+
+      // Verify keys match
+      const derivedPublicKey = derivePublicKey(backupPrivateKey);
+      if (derivedPublicKey !== backupPublicKey) {
+        return false; // Backup keys don't match
+      }
+      await this.adapter.storage.secureSet(STORAGE_KEYS.PRIVATE_KEY, backupPrivateKey);
+      await this.adapter.storage.secureSet(STORAGE_KEYS.PUBLIC_KEY, backupPublicKey);
+      const restored = await this.verifyIdentityIntegrity();
+      if (restored) {
+        // Update cache
+        this.cachedPublicKey = backupPublicKey;
+        this.cachedHasIdentity = true;
+        await this.adapter.storage.set(STORAGE_KEYS.BACKUP_TIMESTAMP, Date.now().toString());
+        return true;
+      }
+      return false;
+    } catch (error) {
+      console.error('[IdentityManager] Failed to restore identity from backup:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Verify identity integrity - checks if keys are valid and accessible
+   */
+  async verifyIdentityIntegrity() {
+    this.ensureNativePlatform();
+    try {
+      const privateKey = await this.getPrivateKey();
+      const publicKey = await this.getPublicKey();
+      if (!privateKey || !publicKey) {
+        return false;
+      }
+
+      // Validate private key format
+      if (!isValidPrivateKey(privateKey)) {
+        return false;
+      }
+
+      // Validate public key format
+      if (!isValidPublicKey(publicKey)) {
+        return false;
+      }
+
+      // Verify public key can be derived from private key
+      const derivedPublicKey = derivePublicKey(privateKey);
+      if (derivedPublicKey !== publicKey) {
+        return false; // Keys don't match
+      }
+
+      // Verify we can create a key pair object (tests elliptic curve operations)
+      const keyPair = await this.getKeyPairObject();
+      if (!keyPair) {
+        return false;
+      }
+      return true;
+    } catch (error) {
+      console.error('[IdentityManager] Identity integrity check failed:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get the elliptic curve key object from the stored private key
+   * Used internally for signing operations
+   */
+  async getKeyPairObject() {
+    this.ensureNativePlatform();
+    const privateKey = await this.getPrivateKey();
+    if (!privateKey) return null;
+    return ec.keyFromPrivate(privateKey);
+  }
+
+  /**
+   * Decrypt backup data and import identity
+   */
+  async decryptAndImportBackup(backupData, password) {
+    this.ensureNativePlatform();
+    try {
+      // Convert hex strings to Uint8Array
+      const saltBytes = new Uint8Array(backupData.salt.match(/.{1,2}/g)?.map(byte => parseInt(byte, 16)) || []);
+      const ivBytes = new Uint8Array(backupData.iv.match(/.{1,2}/g)?.map(byte => parseInt(byte, 16)) || []);
+
+      // Derive key from password (same algorithm as EncryptedBackupGenerator)
+      const saltHex = Array.from(saltBytes).map(b => b.toString(16).padStart(2, '0')).join('');
+      let key = password + saltHex;
+      for (let i = 0; i < 10000; i++) {
+        key = await this.adapter.crypto.digestStringAsync('SHA256', key);
+      }
+      const keyBytes = new Uint8Array(32);
+      for (let i = 0; i < 64 && i < key.length; i += 2) {
+        keyBytes[i / 2] = parseInt(key.substring(i, i + 2), 16);
+      }
+
+      // Decrypt private key (XOR decryption - same as encryption)
+      const encryptedBytes = Buffer.from(backupData.encrypted, 'base64');
+      const decryptedBytes = new Uint8Array(encryptedBytes.length);
+      for (let i = 0; i < encryptedBytes.length; i++) {
+        decryptedBytes[i] = encryptedBytes[i] ^ keyBytes[i % keyBytes.length] ^ ivBytes[i % ivBytes.length];
+      }
+      const privateKey = new TextDecoder().decode(decryptedBytes);
+
+      // Import the key pair
+      return await this.importKeyPair(privateKey);
+    } catch (error) {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.BACKUP_DECRYPTION_FAILED, `Failed to decrypt backup: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Sign a challenge using the stored private key
+   */
+  async signChallenge(challenge) {
+    this.ensureNativePlatform();
+    const keyPair = await this.getKeyPairObject();
+    if (!keyPair) {
+      throw createIdentitySessionError(IdentitySessionErrorCodes.IDENTITY_NOT_FOUND, 'No identity found. Please create or import an identity first.');
+    }
+
+    // Hash the challenge
+    const messageHash = await this.adapter.crypto.digestStringAsync('SHA256', challenge);
+
+    // Sign the hash
+    const signature = keyPair.sign(messageHash);
+    return signature.toDER('hex');
+  }
+}
+//# sourceMappingURL=IdentityManager.js.map