@oxyhq/services 5.16.44 → 5.17.0

package/lib/module/core/identity-session/INTEGRATION_GUIDE.md

@@ -1,287 +0,0 @@
-# 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

@@ -1,395 +0,0 @@
-"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