@oxyhq/services 5.14.0 → 5.15.1

package/src/crypto/keyManager.ts

@@ -0,0 +1,214 @@
+/**
+ * Key Manager - ECDSA secp256k1 Key Generation and Storage
+ * 
+ * Handles secure generation, storage, and retrieval of cryptographic keys.
+ * Private keys are stored securely using expo-secure-store and never leave the device.
+ */
+
+import { ec as EC } from 'elliptic';
+import type { ECKeyPair } from 'elliptic';
+
+// Lazy imports for React Native specific modules
+let SecureStore: typeof import('expo-secure-store') | null = null;
+let ExpoRandom: typeof import('expo-random') | null = null;
+
+const ec = new EC('secp256k1');
+
+const STORAGE_KEYS = {
+  PRIVATE_KEY: 'oxy_identity_private_key',
+  PUBLIC_KEY: 'oxy_identity_public_key',
+} as const;
+
+/**
+ * Initialize React Native specific modules
+ * This allows the module to work in both Node.js and React Native environments
+ */
+async function initSecureStore(): Promise<typeof import('expo-secure-store')> {
+  if (!SecureStore) {
+    SecureStore = await import('expo-secure-store');
+  }
+  return SecureStore;
+}
+
+async function initExpoRandom(): Promise<typeof import('expo-random')> {
+  if (!ExpoRandom) {
+    ExpoRandom = await import('expo-random');
+  }
+  return ExpoRandom;
+}
+
+/**
+ * Generate cryptographically secure random bytes
+ */
+async function getSecureRandomBytes(length: number): Promise<Uint8Array> {
+  try {
+    const Random = await initExpoRandom();
+    return Random.getRandomBytes(length);
+  } catch {
+    // Fallback for Node.js environment
+    const crypto = await import('crypto');
+    return new Uint8Array(crypto.randomBytes(length));
+  }
+}
+
+export interface KeyPair {
+  publicKey: string;
+  privateKey: string;
+}
+
+export class KeyManager {
+  /**
+   * Generate a new ECDSA secp256k1 key pair
+   * Returns the keys in hexadecimal format
+   */
+  static generateKeyPairSync(): KeyPair {
+    const keyPair = ec.genKeyPair();
+    return {
+      privateKey: keyPair.getPrivate('hex'),
+      publicKey: keyPair.getPublic('hex'),
+    };
+  }
+
+  /**
+   * Generate a new key pair using secure random bytes
+   */
+  static async generateKeyPair(): Promise<KeyPair> {
+    const randomBytes = await getSecureRandomBytes(32);
+    const privateKeyHex = Buffer.from(randomBytes).toString('hex');
+    const keyPair = ec.keyFromPrivate(privateKeyHex);
+    
+    return {
+      privateKey: keyPair.getPrivate('hex'),
+      publicKey: keyPair.getPublic('hex'),
+    };
+  }
+
+  /**
+   * Generate and securely store a new key pair on the device
+   * Returns only the public key (private key is stored securely)
+   */
+  static async createIdentity(): Promise<string> {
+    const store = await initSecureStore();
+    const { privateKey, publicKey } = await KeyManager.generateKeyPair();
+
+    // Store private key securely
+    await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, privateKey, {
+      keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+    });
+
+    // Store public key (for quick access without deriving)
+    await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, publicKey);
+
+    return publicKey;
+  }
+
+  /**
+   * Import an existing key pair (e.g., from recovery phrase)
+   */
+  static async importKeyPair(privateKey: string): Promise<string> {
+    const store = await initSecureStore();
+    
+    // Derive public key from private key
+    const keyPair = ec.keyFromPrivate(privateKey);
+    const publicKey = keyPair.getPublic('hex');
+
+    // Store both keys
+    await store.setItemAsync(STORAGE_KEYS.PRIVATE_KEY, privateKey, {
+      keychainAccessible: store.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+    });
+    await store.setItemAsync(STORAGE_KEYS.PUBLIC_KEY, publicKey);
+
+    return publicKey;
+  }
+
+  /**
+   * Get the stored private key
+   * WARNING: Only use this for signing operations within the app
+   */
+  static async getPrivateKey(): Promise<string | null> {
+    const store = await initSecureStore();
+    return store.getItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+  }
+
+  /**
+   * Get the stored public key
+   */
+  static async getPublicKey(): Promise<string | null> {
+    const store = await initSecureStore();
+    return store.getItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+  }
+
+  /**
+   * Check if an identity (key pair) exists on this device
+   */
+  static async hasIdentity(): Promise<boolean> {
+    const privateKey = await KeyManager.getPrivateKey();
+    return privateKey !== null;
+  }
+
+  /**
+   * Delete the stored identity (both keys)
+   * Use with caution - this is irreversible without a recovery phrase
+   */
+  static async deleteIdentity(): Promise<void> {
+    const store = await initSecureStore();
+    await store.deleteItemAsync(STORAGE_KEYS.PRIVATE_KEY);
+    await store.deleteItemAsync(STORAGE_KEYS.PUBLIC_KEY);
+  }
+
+  /**
+   * Get the elliptic curve key object from the stored private key
+   * Used internally for signing operations
+   */
+  static async getKeyPairObject(): Promise<ECKeyPair | null> {
+    const privateKey = await KeyManager.getPrivateKey();
+    if (!privateKey) return null;
+    return ec.keyFromPrivate(privateKey);
+  }
+
+  /**
+   * Derive public key from a private key (without storing)
+   */
+  static derivePublicKey(privateKey: string): string {
+    const keyPair = ec.keyFromPrivate(privateKey);
+    return keyPair.getPublic('hex');
+  }
+
+  /**
+   * Validate that a string is a valid public key
+   */
+  static isValidPublicKey(publicKey: string): boolean {
+    try {
+      ec.keyFromPublic(publicKey, 'hex');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Validate that a string is a valid private key
+   */
+  static isValidPrivateKey(privateKey: string): boolean {
+    try {
+      const keyPair = ec.keyFromPrivate(privateKey);
+      // Verify it can derive a public key
+      keyPair.getPublic('hex');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get a shortened version of the public key for display
+   * Format: first 8 chars...last 8 chars
+   */
+  static shortenPublicKey(publicKey: string): string {
+    if (publicKey.length <= 20) return publicKey;
+    return `${publicKey.slice(0, 8)}...${publicKey.slice(-8)}`;
+  }
+}
+
+export default KeyManager;
+

package/src/crypto/recoveryPhrase.ts

@@ -0,0 +1,147 @@
+/**
+ * Recovery Phrase Service - BIP39 Mnemonic Generation
+ * 
+ * Handles generation and restoration of recovery phrases (mnemonic seeds)
+ * for backing up and restoring user identities.
+ */
+
+import * as bip39 from 'bip39';
+import { KeyManager } from './keyManager';
+
+export interface RecoveryPhraseResult {
+  phrase: string;
+  words: string[];
+  publicKey: string;
+}
+
+export class RecoveryPhraseService {
+  /**
+   * Generate a new identity with a recovery phrase
+   * Returns the mnemonic phrase (should only be shown once to the user)
+   */
+  static async generateIdentityWithRecovery(): Promise<RecoveryPhraseResult> {
+    // Generate 128-bit entropy for 12-word mnemonic
+    const mnemonic = bip39.generateMnemonic(128);
+    
+    // Derive private key from mnemonic
+    // Using the seed directly as the private key (simplified approach)
+    const seed = await bip39.mnemonicToSeed(mnemonic);
+    
+    // Use first 32 bytes of seed as private key
+    const privateKeyHex = seed.subarray(0, 32).toString('hex');
+    
+    // Import the derived key pair
+    const publicKey = await KeyManager.importKeyPair(privateKeyHex);
+
+    return {
+      phrase: mnemonic,
+      words: mnemonic.split(' '),
+      publicKey,
+    };
+  }
+
+  /**
+   * Generate a 24-word recovery phrase for higher security
+   */
+  static async generateIdentityWithRecovery24(): Promise<RecoveryPhraseResult> {
+    // Generate 256-bit entropy for 24-word mnemonic
+    const mnemonic = bip39.generateMnemonic(256);
+    
+    const seed = await bip39.mnemonicToSeed(mnemonic);
+    const privateKeyHex = seed.subarray(0, 32).toString('hex');
+    const publicKey = await KeyManager.importKeyPair(privateKeyHex);
+
+    return {
+      phrase: mnemonic,
+      words: mnemonic.split(' '),
+      publicKey,
+    };
+  }
+
+  /**
+   * Restore an identity from a recovery phrase
+   */
+  static async restoreFromPhrase(phrase: string): Promise<string> {
+    // Normalize and validate the phrase
+    const normalizedPhrase = phrase.trim().toLowerCase();
+    
+    if (!bip39.validateMnemonic(normalizedPhrase)) {
+      throw new Error('Invalid recovery phrase. Please check the words and try again.');
+    }
+
+    // Derive the same private key from the mnemonic
+    const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+    const privateKeyHex = seed.subarray(0, 32).toString('hex');
+    
+    // Import and store the key pair
+    const publicKey = await KeyManager.importKeyPair(privateKeyHex);
+
+    return publicKey;
+  }
+
+  /**
+   * Validate a recovery phrase without importing it
+   */
+  static validatePhrase(phrase: string): boolean {
+    const normalizedPhrase = phrase.trim().toLowerCase();
+    return bip39.validateMnemonic(normalizedPhrase);
+  }
+
+  /**
+   * Get the word list for autocomplete/validation
+   */
+  static getWordList(): string[] {
+    return bip39.wordlists.english;
+  }
+
+  /**
+   * Check if a word is valid in the BIP39 word list
+   */
+  static isValidWord(word: string): boolean {
+    return bip39.wordlists.english.includes(word.toLowerCase());
+  }
+
+  /**
+   * Get suggestions for a partial word
+   */
+  static getSuggestions(partial: string, limit: number = 5): string[] {
+    const lowerPartial = partial.toLowerCase();
+    return bip39.wordlists.english
+      .filter((word: string) => word.startsWith(lowerPartial))
+      .slice(0, limit);
+  }
+
+  /**
+   * Derive the public key from a phrase without storing
+   * Useful for verification before importing
+   */
+  static async derivePublicKeyFromPhrase(phrase: string): Promise<string> {
+    const normalizedPhrase = phrase.trim().toLowerCase();
+    
+    if (!bip39.validateMnemonic(normalizedPhrase)) {
+      throw new Error('Invalid recovery phrase');
+    }
+
+    const seed = await bip39.mnemonicToSeed(normalizedPhrase);
+    const privateKeyHex = seed.subarray(0, 32).toString('hex');
+    
+    return KeyManager.derivePublicKey(privateKeyHex);
+  }
+
+  /**
+   * Convert a phrase to its word array
+   */
+  static phraseToWords(phrase: string): string[] {
+    return phrase.trim().toLowerCase().split(/\s+/);
+  }
+
+  /**
+   * Convert a word array to a phrase string
+   */
+  static wordsToPhrase(words: string[]): string {
+    return words.map(w => w.toLowerCase().trim()).join(' ');
+  }
+}
+
+export default RecoveryPhraseService;
+

package/src/crypto/signatureService.ts

@@ -0,0 +1,280 @@
+/**
+ * Signature Service - ECDSA Digital Signatures
+ * 
+ * Handles signing and verification of messages using ECDSA secp256k1.
+ * Used for authenticating requests and proving identity ownership.
+ */
+
+import { ec as EC } from 'elliptic';
+import { KeyManager } from './keyManager';
+
+// Lazy import for expo-crypto
+let ExpoCrypto: typeof import('expo-crypto') | null = null;
+
+const ec = new EC('secp256k1');
+
+/**
+ * Check if we're in a React Native environment
+ */
+function isReactNative(): boolean {
+  return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+}
+
+/**
+ * Check if we're in a Node.js environment
+ */
+function isNodeJS(): boolean {
+  return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+}
+
+/**
+ * Initialize expo-crypto module
+ */
+async function initExpoCrypto(): Promise<typeof import('expo-crypto')> {
+  if (!ExpoCrypto) {
+    ExpoCrypto = await import('expo-crypto');
+  }
+  return ExpoCrypto;
+}
+
+/**
+ * Compute SHA-256 hash of a string
+ */
+async function sha256(message: string): Promise<string> {
+  // In React Native, always use expo-crypto
+  if (isReactNative() || !isNodeJS()) {
+    const Crypto = await initExpoCrypto();
+    return Crypto.digestStringAsync(
+      Crypto.CryptoDigestAlgorithm.SHA256,
+      message
+    );
+  }
+  
+  // In Node.js, use Node's crypto module
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const crypto = require('crypto');
+  return crypto.createHash('sha256').update(message).digest('hex');
+}
+
+export interface SignedMessage {
+  message: string;
+  signature: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+export interface AuthChallenge {
+  challenge: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+export class SignatureService {
+  /**
+   * Hash a message using SHA-256
+   */
+  static async hashMessage(message: string): Promise<string> {
+    return sha256(message);
+  }
+
+  /**
+   * Sign a message using the stored private key
+   * Returns the signature in DER format (hex encoded)
+   */
+  static async sign(message: string): Promise<string> {
+    const keyPair = await KeyManager.getKeyPairObject();
+    if (!keyPair) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const messageHash = await sha256(message);
+    const signature = keyPair.sign(messageHash);
+    return signature.toDER('hex');
+  }
+
+  /**
+   * Sign a message with an explicit private key (without storing)
+   * Useful for one-time operations or testing
+   */
+  static async signWithKey(message: string, privateKey: string): Promise<string> {
+    const keyPair = ec.keyFromPrivate(privateKey);
+    const messageHash = await sha256(message);
+    const signature = keyPair.sign(messageHash);
+    return signature.toDER('hex');
+  }
+
+  /**
+   * Verify a signature against a message and public key
+   */
+  static async verify(message: string, signature: string, publicKey: string): Promise<boolean> {
+    try {
+      const key = ec.keyFromPublic(publicKey, 'hex');
+      const messageHash = await sha256(message);
+      return key.verify(messageHash, signature);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Synchronous verification (for Node.js backend)
+   * Uses crypto module directly for hashing
+   * Note: This method should only be used in Node.js environments
+   */
+  static verifySync(message: string, signature: string, publicKey: string): boolean {
+    try {
+      if (!isNodeJS()) {
+        // In React Native, use async verify instead
+        throw new Error('verifySync should only be used in Node.js. Use verify() in React Native.');
+      }
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const crypto = require('crypto');
+      const key = ec.keyFromPublic(publicKey, 'hex');
+      const messageHash = crypto.createHash('sha256').update(message).digest('hex');
+      return key.verify(messageHash, signature);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Create a signed message object with metadata
+   */
+  static async createSignedMessage(message: string): Promise<SignedMessage> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    const messageWithTimestamp = `${message}:${timestamp}`;
+    const signature = await SignatureService.sign(messageWithTimestamp);
+
+    return {
+      message,
+      signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * Verify a signed message object
+   * Checks both signature validity and timestamp freshness
+   */
+  static async verifySignedMessage(
+    signedMessage: SignedMessage,
+    maxAgeMs: number = 5 * 60 * 1000 // 5 minutes default
+  ): Promise<boolean> {
+    const { message, signature, publicKey, timestamp } = signedMessage;
+
+    // Check timestamp freshness
+    const now = Date.now();
+    if (now - timestamp > maxAgeMs) {
+      return false;
+    }
+
+    // Verify signature
+    const messageWithTimestamp = `${message}:${timestamp}`;
+    return SignatureService.verify(messageWithTimestamp, signature, publicKey);
+  }
+
+  /**
+   * Create a signed authentication challenge response
+   * Used for challenge-response authentication
+   */
+  static async signChallenge(challenge: string): Promise<AuthChallenge> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    const message = `auth:${publicKey}:${challenge}:${timestamp}`;
+    const signature = await SignatureService.sign(message);
+
+    return {
+      challenge: signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * Verify a challenge response
+   */
+  static async verifyChallengeResponse(
+    originalChallenge: string,
+    response: AuthChallenge,
+    maxAgeMs: number = 5 * 60 * 1000
+  ): Promise<boolean> {
+    const { challenge: signature, publicKey, timestamp } = response;
+
+    // Check timestamp freshness
+    const now = Date.now();
+    if (now - timestamp > maxAgeMs) {
+      return false;
+    }
+
+    const message = `auth:${publicKey}:${originalChallenge}:${timestamp}`;
+    return SignatureService.verify(message, signature, publicKey);
+  }
+
+  /**
+   * Create a registration signature
+   * Used when registering a new identity with the server
+   */
+  static async createRegistrationSignature(
+    username: string,
+    email?: string
+  ): Promise<{ signature: string; publicKey: string; timestamp: number }> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    const message = `register:${publicKey}:${username}:${email || ''}:${timestamp}`;
+    const signature = await SignatureService.sign(message);
+
+    return {
+      signature,
+      publicKey,
+      timestamp,
+    };
+  }
+
+  /**
+   * Sign arbitrary data for API requests
+   * Creates a canonical string representation and signs it
+   */
+  static async signRequestData(data: Record<string, unknown>): Promise<{
+    signature: string;
+    publicKey: string;
+    timestamp: number;
+  }> {
+    const publicKey = await KeyManager.getPublicKey();
+    if (!publicKey) {
+      throw new Error('No identity found. Please create or import an identity first.');
+    }
+
+    const timestamp = Date.now();
+    
+    // Create canonical string representation
+    const sortedKeys = Object.keys(data).sort();
+    const canonicalParts = sortedKeys.map(key => `${key}:${JSON.stringify(data[key])}`);
+    const canonicalString = canonicalParts.join('|');
+    
+    const message = `request:${publicKey}:${timestamp}:${canonicalString}`;
+    const signature = await SignatureService.sign(message);
+
+    return {
+      signature,
+      publicKey,
+      timestamp,
+    };
+  }
+}
+
+export default SignatureService;
+

package/src/i18n/locales/en-US.json

@@ -897,6 +897,10 @@
     "community": {
       "title": "Community",
       "subtitle": "Join our community"
+    },
+    "developersPortal": {
+      "title": "Developers Portal",
+      "subtitle": "API documentation and developer resources"
     }
   },
   "legal": {

package/src/index.ts

@@ -10,6 +10,19 @@
 export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } from './core';
 export { OXY_CLOUD_URL, oxyClient } from './core';
 
+// Crypto/Identity exports
+export { 
+  KeyManager, 
+  SignatureService, 
+  RecoveryPhraseService 
+} from './crypto';
+export type { 
+  KeyPair, 
+  SignedMessage, 
+  AuthChallenge, 
+  RecoveryPhraseResult 
+} from './crypto';
+
 // React context
 export { 
   OxyContextProvider, // Backward compatibility

package/src/models/interfaces.ts

@@ -23,6 +23,7 @@ export interface OxyConfig {
 
 export interface User {
   id: string;
+  publicKey: string;
   username: string;
   email?: string;
   // Avatar file id (asset id)

package/src/types/bip39.d.ts

@@ -0,0 +1,29 @@
+declare module 'bip39' {
+  export interface Wordlist {
+    [index: number]: string;
+    length: number;
+    getWord(index: number): string;
+    getWordIndex(word: string): number;
+  }
+
+  export const wordlists: {
+    english: string[];
+    chinese_simplified: string[];
+    chinese_traditional: string[];
+    french: string[];
+    italian: string[];
+    japanese: string[];
+    korean: string[];
+    spanish: string[];
+  };
+
+  export function generateMnemonic(strength?: number, rng?: (size: number) => Buffer, wordlist?: string[]): string;
+  export function mnemonicToSeed(mnemonic: string, passphrase?: string): Promise<Buffer>;
+  export function mnemonicToSeedSync(mnemonic: string, passphrase?: string): Buffer;
+  export function mnemonicToEntropy(mnemonic: string, wordlist?: string[]): string;
+  export function entropyToMnemonic(entropy: string, wordlist?: string[]): string;
+  export function validateMnemonic(mnemonic: string, wordlist?: string[]): boolean;
+  export function mnemonicToSeedHex(mnemonic: string, passphrase?: string): Promise<string>;
+  export function mnemonicToSeedHexSync(mnemonic: string, passphrase?: string): string;
+}
+