@oxyhq/services 5.16.44 → 5.17.0

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

@@ -1,197 +0,0 @@
-/**
- * Identity and Session Error Codes
- * 
- * Aligned with backend error codes for consistency across the ecosystem
- */
-
-export const IdentitySessionErrorCodes = {
-  // Authentication errors
-  UNAUTHORIZED: 'UNAUTHORIZED',
-  FORBIDDEN: 'FORBIDDEN',
-  INVALID_TOKEN: 'INVALID_TOKEN',
-  MISSING_TOKEN: 'MISSING_TOKEN',
-  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
-  TOKEN_NOT_YET_VALID: 'TOKEN_NOT_YET_VALID',
-  INVALID_SIGNATURE: 'INVALID_SIGNATURE',
-  MALFORMED_TOKEN: 'MALFORMED_TOKEN',
-  INVALID_SESSION: 'INVALID_SESSION',
-  
-  // Identity errors
-  IDENTITY_NOT_FOUND: 'IDENTITY_NOT_FOUND',
-  IDENTITY_ALREADY_EXISTS: 'IDENTITY_ALREADY_EXISTS',
-  IDENTITY_NOT_AVAILABLE_ON_WEB: 'IDENTITY_NOT_AVAILABLE_ON_WEB',
-  IDENTITY_NOT_SYNCED: 'IDENTITY_NOT_SYNCED',
-  INVALID_PUBLIC_KEY: 'INVALID_PUBLIC_KEY',
-  INVALID_PRIVATE_KEY: 'INVALID_PRIVATE_KEY',
-  IDENTITY_CREATION_FAILED: 'IDENTITY_CREATION_FAILED',
-  IDENTITY_IMPORT_FAILED: 'IDENTITY_IMPORT_FAILED',
-  IDENTITY_DELETE_FAILED: 'IDENTITY_DELETE_FAILED',
-  BACKUP_DECRYPTION_FAILED: 'BACKUP_DECRYPTION_FAILED',
-  
-  // Session errors
-  SESSION_NOT_FOUND: 'SESSION_NOT_FOUND',
-  SESSION_EXPIRED: 'SESSION_EXPIRED',
-  SESSION_INVALID: 'SESSION_INVALID',
-  SESSION_CREATION_FAILED: 'SESSION_CREATION_FAILED',
-  SESSION_REFRESH_FAILED: 'SESSION_REFRESH_FAILED',
-  
-  // Device errors
-  DEVICE_NOT_FOUND: 'DEVICE_NOT_FOUND',
-  DEVICE_CREATION_FAILED: 'DEVICE_CREATION_FAILED',
-  
-  // Validation errors
-  VALIDATION_ERROR: 'VALIDATION_ERROR',
-  BAD_REQUEST: 'BAD_REQUEST',
-  MISSING_PARAMETER: 'MISSING_PARAMETER',
-  INVALID_FORMAT: 'INVALID_FORMAT',
-  
-  // Resource errors
-  NOT_FOUND: 'NOT_FOUND',
-  ALREADY_EXISTS: 'ALREADY_EXISTS',
-  CONFLICT: 'CONFLICT',
-  
-  // Server errors
-  INTERNAL_ERROR: 'INTERNAL_ERROR',
-  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
-  TIMEOUT: 'TIMEOUT',
-  
-  // Network errors
-  NETWORK_ERROR: 'NETWORK_ERROR',
-  CONNECTION_FAILED: 'CONNECTION_FAILED',
-  
-  // Storage errors
-  STORAGE_ERROR: 'STORAGE_ERROR',
-  STORAGE_NOT_AVAILABLE: 'STORAGE_NOT_AVAILABLE',
-  SECURE_STORAGE_NOT_AVAILABLE: 'SECURE_STORAGE_NOT_AVAILABLE',
-  
-  // Unknown
-  UNKNOWN_ERROR: 'UNKNOWN_ERROR',
-} as const;
-
-export type IdentitySessionErrorCode = typeof IdentitySessionErrorCodes[keyof typeof IdentitySessionErrorCodes];
-
-/**
- * IdentitySessionError - Custom error class for identity and session operations
- */
-export class IdentitySessionError extends Error {
-  public readonly code: IdentitySessionErrorCode;
-  public readonly statusCode: number;
-
-  constructor(
-    message: string,
-    code: IdentitySessionErrorCode = IdentitySessionErrorCodes.UNKNOWN_ERROR,
-    statusCode: number = 500
-  ) {
-    super(message);
-    this.name = 'IdentitySessionError';
-    this.code = code;
-    this.statusCode = statusCode;
-    Object.setPrototypeOf(this, IdentitySessionError.prototype);
-  }
-}
-
-/**
- * Create error from code
- */
-export function createIdentitySessionError(
-  code: IdentitySessionErrorCode,
-  message?: string,
-  statusCode?: number
-): IdentitySessionError {
-  const defaultMessages: Record<IdentitySessionErrorCode, string> = {
-    [IdentitySessionErrorCodes.UNAUTHORIZED]: 'Unauthorized',
-    [IdentitySessionErrorCodes.FORBIDDEN]: 'Forbidden',
-    [IdentitySessionErrorCodes.INVALID_TOKEN]: 'Invalid token',
-    [IdentitySessionErrorCodes.MISSING_TOKEN]: 'Missing token',
-    [IdentitySessionErrorCodes.TOKEN_EXPIRED]: 'Token has expired',
-    [IdentitySessionErrorCodes.TOKEN_NOT_YET_VALID]: 'Token not yet valid',
-    [IdentitySessionErrorCodes.INVALID_SIGNATURE]: 'Token signature is invalid',
-    [IdentitySessionErrorCodes.MALFORMED_TOKEN]: 'Token format is invalid',
-    [IdentitySessionErrorCodes.INVALID_SESSION]: 'Invalid session',
-    [IdentitySessionErrorCodes.IDENTITY_NOT_FOUND]: 'Identity not found',
-    [IdentitySessionErrorCodes.IDENTITY_ALREADY_EXISTS]: 'Identity already exists',
-    [IdentitySessionErrorCodes.IDENTITY_NOT_AVAILABLE_ON_WEB]: 'Identity operations are only available on native platforms',
-    [IdentitySessionErrorCodes.IDENTITY_NOT_SYNCED]: 'Identity not synced with server',
-    [IdentitySessionErrorCodes.INVALID_PUBLIC_KEY]: 'Invalid public key',
-    [IdentitySessionErrorCodes.INVALID_PRIVATE_KEY]: 'Invalid private key',
-    [IdentitySessionErrorCodes.IDENTITY_CREATION_FAILED]: 'Failed to create identity',
-    [IdentitySessionErrorCodes.IDENTITY_IMPORT_FAILED]: 'Failed to import identity',
-    [IdentitySessionErrorCodes.IDENTITY_DELETE_FAILED]: 'Failed to delete identity',
-    [IdentitySessionErrorCodes.BACKUP_DECRYPTION_FAILED]: 'Failed to decrypt backup',
-    [IdentitySessionErrorCodes.SESSION_NOT_FOUND]: 'Session not found',
-    [IdentitySessionErrorCodes.SESSION_EXPIRED]: 'Session expired',
-    [IdentitySessionErrorCodes.SESSION_INVALID]: 'Session invalid',
-    [IdentitySessionErrorCodes.SESSION_CREATION_FAILED]: 'Failed to create session',
-    [IdentitySessionErrorCodes.SESSION_REFRESH_FAILED]: 'Failed to refresh session',
-    [IdentitySessionErrorCodes.DEVICE_NOT_FOUND]: 'Device not found',
-    [IdentitySessionErrorCodes.DEVICE_CREATION_FAILED]: 'Failed to create device',
-    [IdentitySessionErrorCodes.VALIDATION_ERROR]: 'Validation error',
-    [IdentitySessionErrorCodes.BAD_REQUEST]: 'Bad request',
-    [IdentitySessionErrorCodes.MISSING_PARAMETER]: 'Missing required parameter',
-    [IdentitySessionErrorCodes.INVALID_FORMAT]: 'Invalid format',
-    [IdentitySessionErrorCodes.NOT_FOUND]: 'Resource not found',
-    [IdentitySessionErrorCodes.ALREADY_EXISTS]: 'Resource already exists',
-    [IdentitySessionErrorCodes.CONFLICT]: 'Conflict',
-    [IdentitySessionErrorCodes.INTERNAL_ERROR]: 'Internal server error',
-    [IdentitySessionErrorCodes.SERVICE_UNAVAILABLE]: 'Service unavailable',
-    [IdentitySessionErrorCodes.TIMEOUT]: 'Request timeout',
-    [IdentitySessionErrorCodes.NETWORK_ERROR]: 'Network error',
-    [IdentitySessionErrorCodes.CONNECTION_FAILED]: 'Connection failed',
-    [IdentitySessionErrorCodes.STORAGE_ERROR]: 'Storage error',
-    [IdentitySessionErrorCodes.STORAGE_NOT_AVAILABLE]: 'Storage not available',
-    [IdentitySessionErrorCodes.SECURE_STORAGE_NOT_AVAILABLE]: 'Secure storage not available',
-    [IdentitySessionErrorCodes.UNKNOWN_ERROR]: 'Unknown error',
-  };
-
-  const defaultStatusCodes: Record<IdentitySessionErrorCode, number> = {
-    [IdentitySessionErrorCodes.UNAUTHORIZED]: 401,
-    [IdentitySessionErrorCodes.FORBIDDEN]: 403,
-    [IdentitySessionErrorCodes.INVALID_TOKEN]: 401,
-    [IdentitySessionErrorCodes.MISSING_TOKEN]: 401,
-    [IdentitySessionErrorCodes.TOKEN_EXPIRED]: 401,
-    [IdentitySessionErrorCodes.TOKEN_NOT_YET_VALID]: 401,
-    [IdentitySessionErrorCodes.INVALID_SIGNATURE]: 401,
-    [IdentitySessionErrorCodes.MALFORMED_TOKEN]: 401,
-    [IdentitySessionErrorCodes.INVALID_SESSION]: 401,
-    [IdentitySessionErrorCodes.IDENTITY_NOT_FOUND]: 404,
-    [IdentitySessionErrorCodes.IDENTITY_ALREADY_EXISTS]: 409,
-    [IdentitySessionErrorCodes.IDENTITY_NOT_AVAILABLE_ON_WEB]: 400,
-    [IdentitySessionErrorCodes.IDENTITY_NOT_SYNCED]: 400,
-    [IdentitySessionErrorCodes.INVALID_PUBLIC_KEY]: 400,
-    [IdentitySessionErrorCodes.INVALID_PRIVATE_KEY]: 400,
-    [IdentitySessionErrorCodes.IDENTITY_CREATION_FAILED]: 500,
-    [IdentitySessionErrorCodes.IDENTITY_IMPORT_FAILED]: 500,
-    [IdentitySessionErrorCodes.IDENTITY_DELETE_FAILED]: 500,
-    [IdentitySessionErrorCodes.BACKUP_DECRYPTION_FAILED]: 400,
-    [IdentitySessionErrorCodes.SESSION_NOT_FOUND]: 404,
-    [IdentitySessionErrorCodes.SESSION_EXPIRED]: 401,
-    [IdentitySessionErrorCodes.SESSION_INVALID]: 401,
-    [IdentitySessionErrorCodes.SESSION_CREATION_FAILED]: 500,
-    [IdentitySessionErrorCodes.SESSION_REFRESH_FAILED]: 500,
-    [IdentitySessionErrorCodes.DEVICE_NOT_FOUND]: 404,
-    [IdentitySessionErrorCodes.DEVICE_CREATION_FAILED]: 500,
-    [IdentitySessionErrorCodes.VALIDATION_ERROR]: 400,
-    [IdentitySessionErrorCodes.BAD_REQUEST]: 400,
-    [IdentitySessionErrorCodes.MISSING_PARAMETER]: 400,
-    [IdentitySessionErrorCodes.INVALID_FORMAT]: 400,
-    [IdentitySessionErrorCodes.NOT_FOUND]: 404,
-    [IdentitySessionErrorCodes.ALREADY_EXISTS]: 409,
-    [IdentitySessionErrorCodes.CONFLICT]: 409,
-    [IdentitySessionErrorCodes.INTERNAL_ERROR]: 500,
-    [IdentitySessionErrorCodes.SERVICE_UNAVAILABLE]: 503,
-    [IdentitySessionErrorCodes.TIMEOUT]: 408,
-    [IdentitySessionErrorCodes.NETWORK_ERROR]: 503,
-    [IdentitySessionErrorCodes.CONNECTION_FAILED]: 503,
-    [IdentitySessionErrorCodes.STORAGE_ERROR]: 500,
-    [IdentitySessionErrorCodes.STORAGE_NOT_AVAILABLE]: 503,
-    [IdentitySessionErrorCodes.SECURE_STORAGE_NOT_AVAILABLE]: 503,
-    [IdentitySessionErrorCodes.UNKNOWN_ERROR]: 500,
-  };
-
-  return new IdentitySessionError(
-    message || defaultMessages[code],
-    code,
-    statusCode || defaultStatusCodes[code]
-  );
-}
-

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

@@ -1,15 +0,0 @@
-/**
- * Identity Session Core
- * 
- * Main entry point for identity and session management
- */
-
-export { IdentitySessionCore } from './IdentitySessionCore';
-export { IdentityManager } from './IdentityManager';
-export { SessionManager } from './SessionManager';
-export { DeviceManager } from './DeviceManager';
-export { RefreshManager } from './RefreshManager';
-export { createIdentitySessionCore } from './createIdentitySessionCore';
-export * from './types';
-export * from './errors';
-

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

@@ -1,188 +0,0 @@
-/**
- * Core Identity and Session Types
- * 
- * These types are aligned with backend models (IUser, ISession) to ensure
- * consistency across the entire ecosystem.
- */
-
-/**
- * Identity - Aligned with IUser from backend
- * Represents a user's cryptographic identity
- */
-export interface Identity {
-  id: string;              // MongoDB ObjectId (24 hex chars) - PRIMARY IDENTIFIER
-  publicKey: string;       // ECDSA secp256k1 public key (130 hex chars) - LOOKUP KEY
-  username?: string;
-  email?: string;
-  avatar?: string;         // file id
-  verified?: boolean;
-  language?: string;
-  privacySettings?: {
-    isPrivateAccount?: boolean;
-    hideOnlineStatus?: boolean;
-    hideLastSeen?: boolean;
-    profileVisibility?: boolean;
-    loginAlerts?: boolean;
-    blockScreenshots?: boolean;
-    login?: boolean;
-    biometricLogin?: boolean;
-    showActivity?: boolean;
-    allowTagging?: boolean;
-    allowMentions?: boolean;
-    hideReadReceipts?: boolean;
-    allowDirectMessages?: boolean;
-    dataSharing?: boolean;
-    locationSharing?: boolean;
-    analyticsSharing?: boolean;
-    sensitiveContent?: boolean;
-    autoFilter?: boolean;
-    muteKeywords?: boolean;
-    [key: string]: unknown;
-  };
-  name?: {
-    first?: string;
-    last?: string;
-    full?: string; // virtual, not stored in DB
-    [key: string]: unknown;
-  };
-  bio?: string;
-  description?: string;
-  locations?: Array<{
-    id: string;
-    name: string;
-    label?: string;
-    type?: 'home' | 'work' | 'school' | 'other';
-    address?: {
-      street?: string;
-      streetNumber?: string;
-      streetDetails?: string;
-      postalCode?: string;
-      city?: string;
-      state?: string;
-      country?: string;
-      formattedAddress?: string;
-    };
-    coordinates?: {
-      lat: number;
-      lon: number;
-    };
-    metadata?: {
-      placeId?: string;
-      osmId?: string;
-      osmType?: string;
-      countryCode?: string;
-      timezone?: string;
-    };
-    createdAt?: string;
-    updatedAt?: string;
-  }>;
-  links?: string[];
-  linksMetadata?: Array<{
-    url: string;
-    title: string;
-    description: string;
-    image?: string;
-  }>;
-  _count?: {
-    followers?: number;
-    following?: number;
-  };
-  accountExpiresAfterInactivityDays?: number | null;
-  createdAt?: string;
-  updatedAt?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Session - Aligned with ISession from backend
- * Represents an active user session
- */
-export interface Session {
-  sessionId: string;      // UUID
-  userId: string;          // MongoDB ObjectId (never publicKey)
-  deviceId: string;
-  expiresAt: string;     // ISO date string
-  lastActive: string;     // ISO date string
-  deviceInfo: DeviceInfo;
-  isActive?: boolean;
-  accessToken?: string;
-  refreshToken?: string;
-  isCurrent?: boolean;
-}
-
-/**
- * DeviceInfo - Aligned with ISession.deviceInfo
- */
-export interface DeviceInfo {
-  deviceName?: string;
-  deviceType: string;      // mobile, desktop, tablet, etc.
-  platform: string;        // ios, android, web, etc.
-  browser?: string;
-  os?: string;
-  lastActive: string;     // ISO date string
-  ipAddress?: string;
-  userAgent?: string;
-  location?: string;
-  fingerprint?: string;
-}
-
-/**
- * Device - Represents device information
- */
-export interface Device {
-  deviceId: string;
-  deviceName?: string;
-  deviceType: string;
-  platform: string;
-  browser?: string;
-  os?: string;
-  fingerprint?: string;
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-/**
- * DeviceSession - Aligned with backend device session model
- */
-export interface DeviceSession {
-  deviceId: string;
-  deviceName?: string;
-  deviceType: string;
-  platform: string;
-  browser?: string;
-  os?: string;
-  lastActive: string;
-  fingerprint?: string;
-  createdAt?: string;
-  updatedAt?: string;
-}
-
-/**
- * BackupData - Encrypted backup data for identity
- */
-export interface BackupData {
-  encrypted: string;  // Base64-encoded encrypted private key
-  salt: string;       // Hex-encoded salt used for key derivation
-  iv: string;         // Hex-encoded initialization vector
-  publicKey: string;  // Public key associated with the encrypted private key
-}
-
-/**
- * IdentitySessionEvent - Events emitted by the core
- */
-export type IdentitySessionEvent =
-  | { type: 'identity:created'; identity: Identity }
-  | { type: 'identity:imported'; identity: Identity }
-  | { type: 'identity:deleted' }
-  | { type: 'identity:synced'; identity: Identity }
-  | { type: 'session:created'; session: Session }
-  | { type: 'session:refreshed'; session: Session }
-  | { type: 'session:invalidated'; sessionId: string }
-  | { type: 'session:all-invalidated' }
-  | { type: 'device:changed'; device: Device };
-
-/**
- * Platform type
- */
-export type Platform = 'native' | 'web' | 'node';
-

package/src/crypto/README.md

@@ -1,142 +0,0 @@
-# Oxy Crypto Module
-
-This module provides cryptographic operations for the Oxy ecosystem, supporting both React Native and Node.js environments.
-
-## Architecture
-
-The crypto module is organized into several layers:
-
-### Core Layer (`core.ts`)
-Platform-agnostic cryptographic functions that work everywhere:
-- Signature verification using elliptic curve cryptography
-- Public/private key validation
-- Message formatting (auth, registration, requests)
-- Utility functions (shortenPublicKey, derivePublicKey, etc.)
-
-### Platform-Specific Implementations
-
-#### React Native (`signatureService.ts`, `keyManager.ts`)
-- **KeyManager**: Manages ECDSA key pairs with secure storage via Expo SecureStore
-  - ⚠️ **For Oxy Accounts app only** - Not intended for third-party apps
-  - Handles key generation, import, backup, and secure retrieval
-  - Private keys never leave the device
-
-- **SignatureService**: Provides async signing and verification
-  - Uses `expo-crypto` for hashing in React Native
-  - Falls back to Node.js crypto when available
-  - Suitable for both React Native and Node.js environments
-
-#### Node.js (`node/signatureService.ts`)
-- Optimized synchronous signature operations for backend
-- Uses Node's `crypto` module directly for better performance
-- Exports same API as React Native version for consistency
-
-## Usage
-
-### In React Native / Accounts App
-
-```typescript
-import { KeyManager, SignatureService } from '@oxyhq/services/crypto';
-
-// Create identity (Accounts app only)
-const publicKey = await KeyManager.createIdentity();
-
-// Sign a challenge
-const signature = await SignatureService.sign(message);
-
-// Verify a signature
-const isValid = await SignatureService.verify(message, signature, publicKey);
-```
-
-### In Node.js Backend
-
-```typescript
-import { SignatureService } from '@oxyhq/services/node';
-
-// Generate challenge
-const challenge = SignatureService.generateChallenge();
-
-// Verify signature (synchronous)
-const isValid = SignatureService.verifyChallengeResponse(
-  publicKey,
-  challenge,
-  signature,
-  timestamp
-);
-```
-
-### In Third-Party Apps (Services SDK)
-
-Third-party apps should **not** use KeyManager directly. Instead, use the authentication flows provided by the OxyServices class:
-
-```typescript
-import { OxyServices } from '@oxyhq/services';
-
-const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
-
-// Request authentication (shows QR code / deep link)
-// User approves in Oxy Accounts app
-// Returns session when approved
-const session = await oxy.requestAuth({ appId: 'my-app' });
-```
-
-## Security Considerations
-
-### Message Formats
-All signed messages follow specific formats to prevent replay attacks:
-
-- **Authentication**: `auth:{publicKey}:{challenge}:{timestamp}`
-- **Registration**: `oxy:register:{publicKey}:{timestamp}`
-- **API Requests**: `request:{publicKey}:{timestamp}:{canonicalData}`
-
-Timestamps must be within 5 minutes to be valid.
-
-### Key Storage
-- Private keys are stored in device secure storage (iOS Keychain, Android Keystore)
-- Never transmitted or exposed outside the device
-- Only the Oxy Accounts app has access to private keys
-
-### Backup Encryption
-⚠️ **Current Implementation**: The backup encryption currently uses a custom XOR scheme with key stretching. This is functional but not optimal.
-
-📋 **Planned Improvement**: Migrate to standard AES-256-GCM encryption for better security and interoperability.
-
-## Separation of Concerns
-
-### Oxy Accounts App
-- Owns and manages the user's private key
-- Handles identity creation, backup, and recovery
-- Signs authentication challenges
-- Uses `KeyManager` and `SignatureService`
-
-### Services SDK / Third-Party Apps
-- Does NOT generate or store private keys
-- Displays QR codes and deep links for authentication
-- Polls server for authentication status
-- Uses `OxyServices` class for API communication
-
-### API Backend
-- Generates challenges
-- Verifies signatures using public keys
-- Manages sessions and user data
-- Uses `SignatureService` from `@oxyhq/services/node`
-
-## Migration from Old Signature Service
-
-The API previously had a duplicate `signature.service.ts` file. This has been replaced with a re-export from `@oxyhq/services/node` to ensure consistency and eliminate duplication.
-
-If you're maintaining code that imports from the old location, it will continue to work as the file now re-exports from the shared module.
-
-## Testing
-
-When making changes to crypto code:
-1. Test in both React Native and Node.js environments
-2. Verify signatures created in one environment can be verified in another
-3. Check that timestamps are properly validated
-4. Ensure message formats match exactly between client and server
-
-## Further Reading
-
-- [Public Key Authentication Guide](../docs/PUBLIC_KEY_AUTHENTICATION.md)
-- [ECDSA on secp256k1](https://en.bitcoin.it/wiki/Secp256k1)
-- [Expo SecureStore Documentation](https://docs.expo.dev/versions/latest/sdk/securestore/)