@oxyhq/core 1.0.0

package/src/crypto/polyfill.ts

@@ -0,0 +1,70 @@
+/**
+ * Crypto Polyfills
+ *
+ * Ensures Buffer and crypto.getRandomValues are available
+ * across all platforms (Node.js, Browser, React Native).
+ *
+ * - Browser/Node.js: Uses native crypto
+ * - React Native: Falls back to expo-crypto if native crypto unavailable
+ */
+
+import { Buffer } from 'buffer';
+
+const getGlobalObject = (): typeof globalThis => {
+  if (typeof globalThis !== 'undefined') return globalThis;
+  if (typeof global !== 'undefined') return global;
+  if (typeof window !== 'undefined') return window as unknown as typeof globalThis;
+  if (typeof self !== 'undefined') return self as unknown as typeof globalThis;
+  return {} as typeof globalThis;
+};
+
+const globalObject = getGlobalObject();
+
+// Make Buffer available globally for libraries that depend on it
+if (!globalObject.Buffer) {
+  (globalObject as unknown as { Buffer: typeof Buffer }).Buffer = Buffer;
+}
+
+type CryptoLike = {
+  getRandomValues: <T extends ArrayBufferView>(array: T) => T;
+};
+
+// Cache for expo-crypto module (lazy loaded only in React Native)
+let expoCryptoModule: { getRandomBytes: (count: number) => Uint8Array } | null = null;
+let expoCryptoLoadAttempted = false;
+
+function getRandomBytesSync(byteCount: number): Uint8Array {
+  if (!expoCryptoLoadAttempted) {
+    expoCryptoLoadAttempted = true;
+    try {
+      expoCryptoModule = require('expo-crypto');
+    } catch {
+      // expo-crypto not available — expected in non-RN environments
+    }
+  }
+  if (expoCryptoModule) {
+    return expoCryptoModule.getRandomBytes(byteCount);
+  }
+  throw new Error(
+    'No crypto.getRandomValues implementation available. ' +
+    'In React Native, install expo-crypto.'
+  );
+}
+
+const cryptoPolyfill: CryptoLike = {
+  getRandomValues<T extends ArrayBufferView>(array: T): T {
+    const bytes = getRandomBytesSync(array.byteLength);
+    const uint8View = new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+    uint8View.set(bytes);
+    return array;
+  },
+};
+
+// Only polyfill if crypto or crypto.getRandomValues is not available
+if (typeof globalObject.crypto === 'undefined') {
+  (globalObject as unknown as { crypto: CryptoLike }).crypto = cryptoPolyfill;
+} else if (typeof globalObject.crypto.getRandomValues !== 'function') {
+  (globalObject.crypto as CryptoLike).getRandomValues = cryptoPolyfill.getRandomValues;
+}
+
+export { Buffer };

package/src/crypto/recoveryPhrase.ts

@@ -0,0 +1,166 @@
+/**
+ * Recovery Phrase Service - BIP39 Mnemonic Generation
+ * 
+ * Handles generation and restoration of recovery phrases (mnemonic seeds)
+ * for backing up and restoring user identities.
+ * 
+ * Note: This module requires the polyfill to be loaded first (done via crypto/index.ts)
+ */
+
+import * as bip39 from 'bip39';
+import { KeyManager } from './keyManager';
+
+/**
+ * Convert Uint8Array or array-like to hexadecimal string
+ * Works in both Node.js and React Native without depending on Buffer
+ */
+function toHex(data: Uint8Array | ArrayLike<number>): string {
+  // Convert to array of numbers if needed
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+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 seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+    const privateKeyHex = toHex(seedSlice);
+    
+    // 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 seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+    const privateKeyHex = toHex(seedSlice);
+    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 seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+    const privateKeyHex = toHex(seedSlice);
+    
+    // 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 seedSlice = seed.subarray ? seed.subarray(0, 32) : seed.slice(0, 32);
+    const privateKeyHex = toHex(seedSlice);
+    
+    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,323 @@
+/**
+ * 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
+  // Use Function constructor to prevent Metro bundler from statically analyzing this require
+  // This ensures the require is only evaluated in Node.js runtime, not during Metro bundling
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval
+    const getCrypto = new Function('return require("crypto")');
+    const crypto = getCrypto();
+    return crypto.createHash('sha256').update(message).digest('hex');
+  } catch (error) {
+    // Fallback to expo-crypto if Node crypto fails
+    const Crypto = await initExpoCrypto();
+    return Crypto.digestStringAsync(
+      Crypto.CryptoDigestAlgorithm.SHA256,
+      message
+    );
+  }
+}
+
+export interface SignedMessage {
+  message: string;
+  signature: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+export interface AuthChallenge {
+  challenge: string;
+  publicKey: string;
+  timestamp: number;
+}
+
+export class SignatureService {
+  /**
+   * Generate a random challenge string (for offline use)
+   * Uses expo-crypto in React Native, crypto.randomBytes in Node.js
+   */
+  static async generateChallenge(): Promise<string> {
+    if (isReactNative() || !isNodeJS()) {
+      // Use expo-crypto for React Native (expo-random is deprecated)
+      const Crypto = await initExpoCrypto();
+      const randomBytes = await Crypto.getRandomBytesAsync(32);
+      return Array.from(randomBytes)
+        .map((b: number) => b.toString(16).padStart(2, '0'))
+        .join('');
+    }
+    
+    // Node.js fallback
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-implied-eval
+      const getCrypto = new Function('return require("crypto")');
+      const crypto = getCrypto();
+      return crypto.randomBytes(32).toString('hex');
+    } catch (error) {
+      // Fallback to expo-crypto if Node crypto fails
+      const Crypto = await initExpoCrypto();
+      const randomBytes = await Crypto.getRandomBytesAsync(32);
+      return Array.from(randomBytes)
+        .map((b: number) => b.toString(16).padStart(2, '0'))
+        .join('');
+    }
+  }
+
+  /**
+   * 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.');
+      }
+      // Use Function constructor to prevent Metro bundler from statically analyzing this require
+      // eslint-disable-next-line @typescript-eslint/no-implied-eval
+      const getCrypto = new Function('return require("crypto")');
+      const crypto = getCrypto();
+      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
+   * Format matches server expectation: oxy:register:{publicKey}:{timestamp}
+   */
+  static async createRegistrationSignature(): 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 = `oxy:register:${publicKey}:${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/index.ts

@@ -0,0 +1,75 @@
+// Use JSON locale files (RN Metro supports static requires reliably)
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const enUS = require('./locales/en-US.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const esES = require('./locales/es-ES.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const caES = require('./locales/ca-ES.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const frFR = require('./locales/fr-FR.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const deDE = require('./locales/de-DE.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const itIT = require('./locales/it-IT.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const ptPT = require('./locales/pt-PT.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const jaJP = require('./locales/ja-JP.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const koKR = require('./locales/ko-KR.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const zhCN = require('./locales/zh-CN.json') as Record<string, any>;
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const arSA = require('./locales/ar-SA.json') as Record<string, any>;
+
+export type LocaleDict = Record<string, any>;
+
+const DICTS: Record<string, LocaleDict> = {
+  'en': enUS as LocaleDict,
+  'en-US': enUS as LocaleDict,
+  'es': esES as LocaleDict,
+  'es-ES': esES as LocaleDict,
+  'ca': caES as LocaleDict,
+  'ca-ES': caES as LocaleDict,
+  'fr': frFR as LocaleDict,
+  'fr-FR': frFR as LocaleDict,
+  'de': deDE as LocaleDict,
+  'de-DE': deDE as LocaleDict,
+  'it': itIT as LocaleDict,
+  'it-IT': itIT as LocaleDict,
+  'pt': ptPT as LocaleDict,
+  'pt-PT': ptPT as LocaleDict,
+  'ja': jaJP as LocaleDict,
+  'ja-JP': jaJP as LocaleDict,
+  'ko': koKR as LocaleDict,
+  'ko-KR': koKR as LocaleDict,
+  'zh': zhCN as LocaleDict,
+  'zh-CN': zhCN as LocaleDict,
+  'ar': arSA as LocaleDict,
+  'ar-SA': arSA as LocaleDict,
+};
+
+const FALLBACK = 'en-US';
+
+function getNested(obj: any, path: string): any {
+  return path.split('.').reduce((acc, key) => (acc && acc[key] != null ? acc[key] : undefined), obj);
+}
+
+export function translate(locale: string | undefined, key: string, vars?: Record<string, string | number>): string {
+  const lang = locale && DICTS[locale] ? locale : FALLBACK;
+  const dict = DICTS[lang] || DICTS[FALLBACK];
+  let val = getNested(dict, key);
+  if (typeof val !== 'string') return key; // fallback to key if missing
+  if (vars) {
+    Object.keys(vars).forEach(k => {
+      const token = `{{${k}}}`;
+      val = val.replaceAll(token, String(vars[k]));
+    });
+  }
+  return val;
+}
+
+export function hasKey(locale: string | undefined, key: string): boolean {
+  const lang = locale && DICTS[locale] ? locale : FALLBACK;
+  return getNested(DICTS[lang], key) != null || getNested(DICTS[FALLBACK], key) != null;
+}