@oxyhq/services 5.16.35 → 5.16.36

package/src/crypto/README.md

@@ -0,0 +1,142 @@
+# 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/)

package/src/crypto/__tests__/core.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Tests for the shared crypto core module
+ * These tests verify that signature verification is consistent across platforms
+ */
+
+import {
+  verifySignatureCore,
+  isValidPublicKey,
+  isValidPrivateKey,
+  isTimestampFresh,
+  buildAuthMessage,
+  buildRegistrationMessage,
+  buildRequestMessage,
+  shortenPublicKey,
+  derivePublicKey,
+  getEllipticCurve,
+  CHALLENGE_TTL_MS,
+  MAX_SIGNATURE_AGE_MS,
+} from '../core';
+
+describe('Crypto Core Module', () => {
+  // Test key pair (for testing only - never use in production)
+  const testPrivateKey = '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+  // Public key derived from the private key above
+  const testPublicKey = '04bb50e2d89a4ed70663d080659fe0ad4b9bc3e06c17a227433966cb59ceee020decddbf6e00192011648d13b1c00af770c0c1bb609d4d3a5c98a43772e0e18ef4';
+  
+  describe('Public/Private Key Validation', () => {
+    it('should validate correct public keys', () => {
+      expect(isValidPublicKey(testPublicKey)).toBe(true);
+    });
+
+    it('should reject invalid public keys', () => {
+      expect(isValidPublicKey('invalid')).toBe(false);
+      expect(isValidPublicKey('')).toBe(false);
+      expect(isValidPublicKey('1234')).toBe(false);
+    });
+
+    it('should validate correct private keys', () => {
+      expect(isValidPrivateKey(testPrivateKey)).toBe(true);
+    });
+
+    it('should reject invalid private keys', () => {
+      expect(isValidPrivateKey('invalid')).toBe(false);
+      expect(isValidPrivateKey('')).toBe(false);
+      expect(isValidPrivateKey('1234')).toBe(false);
+    });
+
+    it('should derive public key from private key', () => {
+      const derived = derivePublicKey(testPrivateKey);
+      expect(derived).toBe(testPublicKey);
+    });
+  });
+
+  describe('Utility Functions', () => {
+    it('should shorten public keys correctly', () => {
+      const shortened = shortenPublicKey(testPublicKey);
+      expect(shortened).toBe('04bb50e2...e0e18ef4');
+      expect(shortened.length).toBeLessThan(testPublicKey.length);
+    });
+
+    it('should not shorten already short keys', () => {
+      const shortKey = '1234567890';
+      expect(shortenPublicKey(shortKey)).toBe(shortKey);
+    });
+  });
+
+  describe('Timestamp Validation', () => {
+    it('should accept fresh timestamps', () => {
+      const now = Date.now();
+      expect(isTimestampFresh(now)).toBe(true);
+      expect(isTimestampFresh(now - 1000)).toBe(true); // 1 second ago
+    });
+
+    it('should reject old timestamps', () => {
+      const old = Date.now() - (MAX_SIGNATURE_AGE_MS + 1000);
+      expect(isTimestampFresh(old)).toBe(false);
+    });
+
+    it('should respect custom max age', () => {
+      const timestamp = Date.now() - 10000; // 10 seconds ago
+      expect(isTimestampFresh(timestamp, 5000)).toBe(false); // max 5 seconds
+      expect(isTimestampFresh(timestamp, 15000)).toBe(true); // max 15 seconds
+    });
+  });
+
+  describe('Message Building', () => {
+    it('should build auth messages correctly', () => {
+      const publicKey = 'abc123';
+      const challenge = 'challenge456';
+      const timestamp = 1234567890;
+      
+      const message = buildAuthMessage(publicKey, challenge, timestamp);
+      expect(message).toBe('auth:abc123:challenge456:1234567890');
+    });
+
+    it('should build registration messages correctly', () => {
+      const publicKey = 'abc123';
+      const timestamp = 1234567890;
+      
+      const message = buildRegistrationMessage(publicKey, timestamp);
+      expect(message).toBe('oxy:register:abc123:1234567890');
+    });
+
+    it('should build request messages with canonical data', () => {
+      const publicKey = 'abc123';
+      const timestamp = 1234567890;
+      const data = {
+        username: 'testuser',
+        action: 'update',
+        id: 42,
+      };
+      
+      const message = buildRequestMessage(publicKey, timestamp, data);
+      
+      // Keys should be sorted alphabetically
+      expect(message).toContain('action:"update"');
+      expect(message).toContain('id:42');
+      expect(message).toContain('username:"testuser"');
+      expect(message).toContain('request:abc123:1234567890:');
+    });
+
+    it('should produce consistent canonical strings', () => {
+      const publicKey = 'key';
+      const timestamp = 1000;
+      
+      // Same data, different order
+      const data1 = { b: 2, a: 1, c: 3 };
+      const data2 = { c: 3, a: 1, b: 2 };
+      
+      const message1 = buildRequestMessage(publicKey, timestamp, data1);
+      const message2 = buildRequestMessage(publicKey, timestamp, data2);
+      
+      expect(message1).toBe(message2);
+    });
+  });
+
+  describe('Signature Verification Core', () => {
+    it('should verify valid signatures', () => {
+      const ec = getEllipticCurve();
+      const keyPair = ec.keyFromPrivate(testPrivateKey);
+      
+      // Create a test message hash
+      const messageHash = 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+      
+      // Sign it
+      const signature = keyPair.sign(messageHash);
+      const signatureHex = signature.toDER('hex');
+      
+      // Verify it
+      const isValid = verifySignatureCore(messageHash, signatureHex, testPublicKey);
+      expect(isValid).toBe(true);
+    });
+
+    it('should reject invalid signatures', () => {
+      const messageHash = 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+      const invalidSignature = '1234567890abcdef';
+      
+      const isValid = verifySignatureCore(messageHash, invalidSignature, testPublicKey);
+      expect(isValid).toBe(false);
+    });
+
+    it('should reject signatures with wrong public key', () => {
+      const ec = getEllipticCurve();
+      const keyPair = ec.keyFromPrivate(testPrivateKey);
+      
+      const messageHash = 'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+      const signature = keyPair.sign(messageHash);
+      const signatureHex = signature.toDER('hex');
+      
+      // Use a different public key
+      const wrongPublicKey = '04' + 'a'.repeat(128);
+      
+      const isValid = verifySignatureCore(messageHash, signatureHex, wrongPublicKey);
+      expect(isValid).toBe(false);
+    });
+  });
+
+  describe('Constants', () => {
+    it('should export correct TTL constants', () => {
+      expect(CHALLENGE_TTL_MS).toBe(5 * 60 * 1000); // 5 minutes
+      expect(MAX_SIGNATURE_AGE_MS).toBe(5 * 60 * 1000); // 5 minutes
+    });
+  });
+
+  describe('Elliptic Curve', () => {
+    it('should provide secp256k1 curve', () => {
+      const ec = getEllipticCurve();
+      expect(ec).toBeDefined();
+      expect(ec.curve.type).toBe('short');
+    });
+
+    it('should generate valid key pairs', () => {
+      const ec = getEllipticCurve();
+      const keyPair = ec.genKeyPair();
+      
+      const privateKey = keyPair.getPrivate('hex');
+      const publicKey = keyPair.getPublic('hex');
+      
+      expect(isValidPrivateKey(privateKey)).toBe(true);
+      expect(isValidPublicKey(publicKey)).toBe(true);
+    });
+  });
+});

package/src/crypto/core.ts

@@ -0,0 +1,142 @@
+/**
+ * Core Cryptographic Functions - Platform Agnostic
+ * 
+ * This module contains the core signature verification logic
+ * that is shared between all platforms (React Native, Node.js, Web).
+ * Platform-specific implementations (hashing, random generation) are injected.
+ */
+
+import { ec as EC } from 'elliptic';
+import type { EC as ECType } from 'elliptic';
+
+const ec = new EC('secp256k1');
+
+// Constants for signature validation
+export const CHALLENGE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+export const MAX_SIGNATURE_AGE_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Core signature verification using elliptic curve
+ * This is platform-agnostic and works everywhere
+ */
+export function verifySignatureCore(
+  messageHash: string,
+  signature: string,
+  publicKey: string
+): boolean {
+  try {
+    const key = ec.keyFromPublic(publicKey, 'hex');
+    return key.verify(messageHash, signature);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate that a string is a valid public key
+ */
+export function isValidPublicKey(publicKey: string): boolean {
+  // Reject empty strings
+  if (!publicKey || publicKey.trim().length === 0) {
+    return false;
+  }
+  
+  try {
+    ec.keyFromPublic(publicKey, 'hex');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate that a string is a valid private key
+ */
+export function isValidPrivateKey(privateKey: string): boolean {
+  // Reject empty strings
+  if (!privateKey || privateKey.trim().length === 0) {
+    return false;
+  }
+  
+  // Private keys must be 64 hex characters (32 bytes)
+  if (!/^[0-9a-fA-F]{64}$/.test(privateKey)) {
+    return false;
+  }
+  
+  try {
+    const keyPair = ec.keyFromPrivate(privateKey);
+    // Verify it can derive a public key and the key is valid
+    keyPair.getPublic('hex');
+    // Check that the private key is not zero (which would be invalid)
+    const priv = keyPair.getPrivate();
+    if (!priv || priv.isZero()) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get a shortened display version of a public key
+ * Format: first 8 chars...last 8 chars
+ */
+export function shortenPublicKey(publicKey: string): string {
+  if (publicKey.length <= 20) return publicKey;
+  return `${publicKey.slice(0, 8)}...${publicKey.slice(-8)}`;
+}
+
+/**
+ * Derive public key from a private key (without storing)
+ */
+export function derivePublicKey(privateKey: string): string {
+  const keyPair = ec.keyFromPrivate(privateKey);
+  return keyPair.getPublic('hex');
+}
+
+/**
+ * Check timestamp freshness
+ */
+export function isTimestampFresh(timestamp: number, maxAgeMs: number = MAX_SIGNATURE_AGE_MS): boolean {
+  const now = Date.now();
+  return (now - timestamp) <= maxAgeMs;
+}
+
+/**
+ * Build authentication challenge message
+ * Format: auth:{publicKey}:{challenge}:{timestamp}
+ */
+export function buildAuthMessage(publicKey: string, challenge: string, timestamp: number): string {
+  return `auth:${publicKey}:${challenge}:${timestamp}`;
+}
+
+/**
+ * Build registration message
+ * Format: oxy:register:{publicKey}:{timestamp}
+ */
+export function buildRegistrationMessage(publicKey: string, timestamp: number): string {
+  return `oxy:register:${publicKey}:${timestamp}`;
+}
+
+/**
+ * Build request signature message
+ * Format: request:{publicKey}:{timestamp}:{canonicalString}
+ */
+export function buildRequestMessage(
+  publicKey: string,
+  timestamp: number,
+  data: Record<string, unknown>
+): string {
+  const sortedKeys = Object.keys(data).sort();
+  const canonicalParts = sortedKeys.map(key => `${key}:${JSON.stringify(data[key])}`);
+  const canonicalString = canonicalParts.join('|');
+  return `request:${publicKey}:${timestamp}:${canonicalString}`;
+}
+
+/**
+ * Get the elliptic curve instance (for key generation)
+ */
+export function getEllipticCurve(): ECType {
+  return ec;
+}

package/src/crypto/index.ts

@@ -3,15 +3,6 @@
  * 
  * Provides cryptographic identity management for the Oxy ecosystem.
  * Handles key generation, secure storage, and digital signatures.
- * 
- * ⚠️ IMPORTANT: KeyManager is primarily intended for use in the Oxy Accounts app.
- * While it's exported here for convenience, third-party applications should NOT
- * generate or store user identities. The Accounts app is the identity wallet.
- * 
- * For third-party apps:
- * - Use SignatureService for signing operations (but keys come from Accounts app)
- * - Do NOT call KeyManager.createIdentity() or KeyManager.importKeyPair()
- * - The Oxy Accounts app handles all identity generation and key storage
  */
 
 // Import polyfills first - this ensures Buffer is available for crypto libraries
@@ -25,7 +16,9 @@ export {
 } from './signatureService';
 export { type BackupData } from './types';
 
+// Export core crypto utilities (shared across platforms)
+export * from './core';
+
 // Re-export for convenience
 export { KeyManager as default } from './keyManager';
 
-

package/src/crypto/keyManager.ts

@@ -1,20 +1,38 @@
 /**
  * Key Manager - ECDSA secp256k1 Key Generation and Storage
  * 
- * Handles secure generation, storage, and retrieval of cryptographic keys.
+ * ⚠️ **FOR OXY ACCOUNTS APP ONLY**
+ * 
+ * This module handles secure generation, storage, and retrieval of cryptographic keys.
  * Private keys are stored securely using expo-secure-store and never leave the device.
+ * 
+ * **IMPORTANT**: Third-party apps should NOT use KeyManager directly.
+ * Instead, use the OxyServices authentication flows which communicate with the
+ * Oxy Accounts app via deep links/QR codes to obtain user authorization.
+ * 
+ * The Oxy Accounts app is the sole owner of the user's private key and identity.
+ * Other apps request authentication from the Accounts app, which signs challenges
+ * and returns authorization to the requesting app via the API.
+ * 
+ * @see {@link https://github.com/OxyHQ/OxyHQServices/blob/main/packages/services/src/crypto/README.md|Crypto Module Documentation}
  */
 
 import { ec as EC } from 'elliptic';
 import type { ECKeyPair } from 'elliptic';
 import { Platform } from 'react-native';
-import { shortenPublicKey as sharedShortenPublicKey } from '../shared';
+import {
+  isValidPublicKey as validatePublicKey,
+  isValidPrivateKey as validatePrivateKey,
+  derivePublicKey as derivePublicKeyFromPrivate,
+  shortenPublicKey as shortenKey,
+  getEllipticCurve,
+} from './core';
 
 // Lazy imports for React Native specific modules
 let SecureStore: typeof import('expo-secure-store') | null = null;
 let ExpoCrypto: typeof import('expo-crypto') | null = null;
 
-const ec = new EC('secp256k1');
+const ec = getEllipticCurve();
 
 const STORAGE_KEYS = {
   PRIVATE_KEY: 'oxy_identity_private_key',
@@ -505,34 +523,21 @@ export class KeyManager {
    * Derive public key from a private key (without storing)
    */
   static derivePublicKey(privateKey: string): string {
-    const keyPair = ec.keyFromPrivate(privateKey);
-    return keyPair.getPublic('hex');
+    return derivePublicKeyFromPrivate(privateKey);
   }
 
   /**
    * Validate that a string is a valid public key
    */
   static isValidPublicKey(publicKey: string): boolean {
-    try {
-      ec.keyFromPublic(publicKey, 'hex');
-      return true;
-    } catch {
-      return false;
-    }
+    return validatePublicKey(publicKey);
   }
 
   /**
    * 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;
-    }
+    return validatePrivateKey(privateKey);
   }
 
   /**
@@ -540,8 +545,7 @@ export class KeyManager {
    * Format: first 8 chars...last 8 chars
    */
   static shortenPublicKey(publicKey: string): string {
-    // Use shared utility
-    return sharedShortenPublicKey(publicKey);
+    return shortenKey(publicKey);
   }
 }