react-native-ble-mesh 1.1.1 → 2.0.0

package/src/constants/index.js

@@ -7,6 +7,7 @@
 
 const protocol = require('./protocol');
 const ble = require('./ble');
+// Crypto constants kept for protocol compatibility
 const crypto = require('./crypto');
 const errors = require('./errors');
 const events = require('./events');

package/src/crypto/AutoCrypto.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * @fileoverview Auto-detect best available crypto provider
+ * @module crypto/AutoCrypto
+ *
+ * Priority order:
+ * 1. react-native-quick-crypto (native speed)
+ * 2. expo-crypto + tweetnacl (Expo projects)
+ * 3. tweetnacl (universal fallback)
+ */
+
+const QuickCryptoProvider = require('./providers/QuickCryptoProvider');
+const ExpoCryptoProvider = require('./providers/ExpoCryptoProvider');
+const TweetNaClProvider = require('./providers/TweetNaClProvider');
+
+/**
+ * Detects and returns the best available crypto provider.
+ * @returns {import('./CryptoProvider')} Best available provider
+ * @throws {Error} If no crypto provider is available
+ */
+function detectProvider() {
+  // 1. Native speed (react-native-quick-crypto)
+  if (QuickCryptoProvider.isAvailable()) {
+    return new QuickCryptoProvider();
+  }
+
+  // 2. Expo (expo-crypto + tweetnacl)
+  if (ExpoCryptoProvider.isAvailable()) {
+    return new ExpoCryptoProvider();
+  }
+
+  // 3. Universal (tweetnacl)
+  if (TweetNaClProvider.isAvailable()) {
+    return new TweetNaClProvider();
+  }
+
+  throw new Error(
+    'No crypto provider available. Install one of:\n' +
+    '  npm install tweetnacl                    (works everywhere)\n' +
+    '  npm install react-native-quick-crypto    (native speed)\n' +
+    '  npx expo install expo-crypto && npm install tweetnacl  (Expo)'
+  );
+}
+
+/**
+ * Creates a crypto provider from a config value.
+ * @param {string|Object|null} config - 'auto', provider name, or provider instance
+ * @returns {import('./CryptoProvider')}
+ */
+function createProvider(config) {
+  if (!config || config === 'auto') {
+    return detectProvider();
+  }
+
+  if (typeof config === 'object' && typeof config.generateKeyPair === 'function') {
+    return config; // Already a provider instance
+  }
+
+  if (typeof config === 'string') {
+    switch (config) {
+      case 'tweetnacl':
+        return new TweetNaClProvider();
+      case 'quick-crypto':
+        return new QuickCryptoProvider();
+      case 'expo-crypto':
+        return new ExpoCryptoProvider();
+      default:
+        throw new Error(`Unknown crypto provider: ${config}`);
+    }
+  }
+
+  throw new Error('Invalid crypto config: expected "auto", provider name, or provider instance');
+}
+
+module.exports = {
+  detectProvider,
+  createProvider
+};

package/src/crypto/CryptoProvider.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * @fileoverview Abstract CryptoProvider interface
+ * @module crypto/CryptoProvider
+ *
+ * Pluggable crypto backend. Consumers choose their provider:
+ * - TweetNaClProvider (tweetnacl) — works everywhere
+ * - QuickCryptoProvider (react-native-quick-crypto) — native speed
+ * - ExpoCryptoProvider (expo-crypto) — for Expo projects
+ */
+
+/**
+ * Abstract crypto provider interface.
+ * All crypto operations go through this interface, allowing
+ * consumers to swap implementations without changing application code.
+ *
+ * @abstract
+ * @class CryptoProvider
+ */
+class CryptoProvider {
+  /**
+   * Provider name for identification
+   * @returns {string}
+   */
+  get name() {
+    return 'abstract';
+  }
+
+  /**
+   * Generates a new X25519 key pair
+   * @returns {{ publicKey: Uint8Array, secretKey: Uint8Array }}
+   */
+  generateKeyPair() {
+    throw new Error('CryptoProvider.generateKeyPair() must be implemented');
+  }
+
+  /**
+   * Computes X25519 shared secret
+   * @param {Uint8Array} secretKey - Our secret key (32 bytes)
+   * @param {Uint8Array} publicKey - Their public key (32 bytes)
+   * @returns {Uint8Array} Shared secret (32 bytes)
+   */
+  sharedSecret(_secretKey, _publicKey) {
+    throw new Error('CryptoProvider.sharedSecret() must be implemented');
+  }
+
+  /**
+   * AEAD encrypt (XSalsa20-Poly1305 or ChaCha20-Poly1305)
+   * @param {Uint8Array} key - Encryption key (32 bytes)
+   * @param {Uint8Array} nonce - Nonce (24 bytes for XSalsa20, 12 for ChaCha20)
+   * @param {Uint8Array} plaintext - Data to encrypt
+   * @param {Uint8Array} [ad] - Additional authenticated data (optional)
+   * @returns {Uint8Array} Ciphertext with authentication tag
+   */
+  encrypt(_key, _nonce, _plaintext, _ad) {
+    throw new Error('CryptoProvider.encrypt() must be implemented');
+  }
+
+  /**
+   * AEAD decrypt
+   * @param {Uint8Array} key - Encryption key (32 bytes)
+   * @param {Uint8Array} nonce - Nonce
+   * @param {Uint8Array} ciphertext - Ciphertext with auth tag
+   * @param {Uint8Array} [ad] - Additional authenticated data (optional)
+   * @returns {Uint8Array|null} Plaintext or null if authentication fails
+   */
+  decrypt(_key, _nonce, _ciphertext, _ad) {
+    throw new Error('CryptoProvider.decrypt() must be implemented');
+  }
+
+  /**
+   * Computes SHA-256 hash
+   * @param {Uint8Array} data - Data to hash
+   * @returns {Uint8Array} Hash (32 bytes)
+   */
+  hash(_data) {
+    throw new Error('CryptoProvider.hash() must be implemented');
+  }
+
+  /**
+   * Generates cryptographically secure random bytes
+   * @param {number} length - Number of bytes
+   * @returns {Uint8Array} Random bytes
+   */
+  randomBytes(_length) {
+    throw new Error('CryptoProvider.randomBytes() must be implemented');
+  }
+
+  /**
+   * Checks if this provider is available in the current environment
+   * @returns {boolean}
+   */
+  static isAvailable() {
+    return false;
+  }
+}
+
+module.exports = CryptoProvider;

package/src/crypto/index.js

@@ -1,72 +1,24 @@
 'use strict';
 
 /**
- * Crypto Module
- * Main exports for all cryptographic primitives and protocols.
+ * @fileoverview Crypto module — pluggable provider system
  * @module crypto
+ *
+ * Provides a CryptoProvider interface with auto-detection:
+ * - TweetNaClProvider (tweetnacl) — works everywhere
+ * - QuickCryptoProvider (react-native-quick-crypto) — native speed
+ * - ExpoCryptoProvider (expo-crypto) — for Expo projects
  */
 
-// Hash functions
-const { hash, createHash, HashContext } = require('./sha256');
-const { hmacSha256, verifyHmac } = require('./hmac');
-const { extract, expand, derive, deriveMultiple } = require('./hkdf');
-
-// Symmetric encryption
-const { chacha20, chacha20Block } = require('./chacha20');
-const { poly1305 } = require('./poly1305');
-const { encrypt, decrypt } = require('./aead');
-
-// Asymmetric encryption (key exchange)
-const { generateKeyPair, scalarMult, scalarMultBase } = require('./x25519');
-
-// Noise Protocol
-const noise = require('./noise');
-
-// Key management
-const keys = require('./keys');
+const CryptoProvider = require('./CryptoProvider');
+const { TweetNaClProvider, QuickCryptoProvider, ExpoCryptoProvider } = require('./providers');
+const { detectProvider, createProvider } = require('./AutoCrypto');
 
 module.exports = {
-  // SHA-256
-  hash,
-  createHash,
-  HashContext,
-
-  // HMAC
-  hmacSha256,
-  verifyHmac,
-
-  // HKDF
-  hkdfExtract: extract,
-  hkdfExpand: expand,
-  hkdf: derive,
-  hkdfMultiple: deriveMultiple,
-
-  // ChaCha20
-  chacha20,
-  chacha20Block,
-
-  // Poly1305
-  poly1305,
-
-  // AEAD (ChaCha20-Poly1305)
-  encrypt,
-  decrypt,
-
-  // X25519
-  generateKeyPair,
-  scalarMult,
-  scalarMultBase,
-
-  // Noise Protocol (as namespace)
-  noise,
-
-  // Key management (as namespace)
-  keys,
-
-  // Re-export commonly used classes at top level
-  NoiseHandshake: noise.NoiseHandshake,
-  NoiseSession: noise.NoiseSession,
-  SymmetricState: noise.SymmetricState,
-  KeyPair: keys.KeyPair,
-  KeyManager: keys.KeyManager
+  CryptoProvider,
+  TweetNaClProvider,
+  QuickCryptoProvider,
+  ExpoCryptoProvider,
+  detectProvider,
+  createProvider
 };

package/src/crypto/providers/ExpoCryptoProvider.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * @fileoverview Expo-crypto based provider
+ * @module crypto/providers/ExpoCryptoProvider
+ *
+ * Uses expo-crypto for Expo managed workflow projects.
+ * Note: expo-crypto provides hashing and random bytes but NOT key exchange or AEAD.
+ * Falls back to tweetnacl for those operations.
+ *
+ * Install: npx expo install expo-crypto tweetnacl
+ */
+
+const CryptoProvider = require('../CryptoProvider');
+
+/**
+ * Crypto provider for Expo projects.
+ * Uses expo-crypto for hashing/random, tweetnacl for key exchange and AEAD.
+ *
+ * @class ExpoCryptoProvider
+ * @extends CryptoProvider
+ */
+class ExpoCryptoProvider extends CryptoProvider {
+  constructor(options = {}) {
+    super();
+    this._expoCrypto = options.expoCrypto || null;
+    this._nacl = options.nacl || null;
+  }
+
+  get name() {
+    return 'expo-crypto';
+  }
+
+  _getExpoCrypto() {
+    if (!this._expoCrypto) {
+      try {
+        this._expoCrypto = require('expo-crypto');
+      } catch (e) {
+        throw new Error('expo-crypto is required. Install: npx expo install expo-crypto');
+      }
+    }
+    return this._expoCrypto;
+  }
+
+  _getNacl() {
+    if (!this._nacl) {
+      try {
+        this._nacl = require('tweetnacl');
+      } catch (e) {
+        throw new Error('tweetnacl is required with ExpoCryptoProvider. Install: npm install tweetnacl');
+      }
+    }
+    return this._nacl;
+  }
+
+  /** @inheritdoc */
+  generateKeyPair() {
+    const nacl = this._getNacl();
+    const kp = nacl.box.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+  }
+
+  /** @inheritdoc */
+  sharedSecret(secretKey, publicKey) {
+    const nacl = this._getNacl();
+    return nacl.box.before(publicKey, secretKey);
+  }
+
+  /** @inheritdoc */
+  encrypt(key, nonce, plaintext, _ad) {
+    const nacl = this._getNacl();
+
+    // Ensure 24-byte nonce (pad short nonces with zeros)
+    let fullNonce = nonce;
+    if (nonce.length < 24) {
+      fullNonce = new Uint8Array(24);
+      fullNonce.set(nonce);
+    }
+
+    return nacl.secretbox(plaintext, fullNonce, key);
+  }
+
+  /** @inheritdoc */
+  decrypt(key, nonce, ciphertext, _ad) {
+    const nacl = this._getNacl();
+
+    // Ensure 24-byte nonce (pad short nonces with zeros)
+    let fullNonce = nonce;
+    if (nonce.length < 24) {
+      fullNonce = new Uint8Array(24);
+      fullNonce.set(nonce);
+    }
+
+    return nacl.secretbox.open(ciphertext, fullNonce, key) || null;
+  }
+
+  /** @inheritdoc */
+  hash(data) {
+    // expo-crypto's digestStringAsync is async — for sync compat, use tweetnacl
+    const nacl = this._getNacl();
+    return nacl.hash(data).slice(0, 32);
+  }
+
+  /** @inheritdoc */
+  randomBytes(length) {
+    const expoCrypto = this._getExpoCrypto();
+    if (expoCrypto.getRandomBytes) {
+      return new Uint8Array(expoCrypto.getRandomBytes(length));
+    }
+    // Fallback to tweetnacl
+    const nacl = this._getNacl();
+    return nacl.randomBytes(length);
+  }
+
+  static isAvailable() {
+    try {
+      require('expo-crypto');
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+}
+
+module.exports = ExpoCryptoProvider;

package/src/crypto/providers/QuickCryptoProvider.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * @fileoverview react-native-quick-crypto based provider
+ * @module crypto/providers/QuickCryptoProvider
+ *
+ * Uses native crypto via react-native-quick-crypto for maximum performance.
+ * Install: npm install react-native-quick-crypto
+ */
+
+const CryptoProvider = require('../CryptoProvider');
+
+/**
+ * Crypto provider using react-native-quick-crypto.
+ * Provides native-speed crypto on React Native (JSI binding).
+ *
+ * @class QuickCryptoProvider
+ * @extends CryptoProvider
+ */
+class QuickCryptoProvider extends CryptoProvider {
+  constructor(options = {}) {
+    super();
+    this._crypto = options.crypto || null;
+  }
+
+  get name() {
+    return 'quick-crypto';
+  }
+
+  _getCrypto() {
+    if (!this._crypto) {
+      try {
+        this._crypto = require('react-native-quick-crypto');
+      } catch (e) {
+        throw new Error(
+          'react-native-quick-crypto is required. Install: npm install react-native-quick-crypto'
+        );
+      }
+    }
+    return this._crypto;
+  }
+
+  /** @inheritdoc */
+  generateKeyPair() {
+    const crypto = this._getCrypto();
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('x25519');
+    return {
+      publicKey: new Uint8Array(publicKey.export({ type: 'spki', format: 'der' }).slice(-32)),
+      secretKey: new Uint8Array(privateKey.export({ type: 'pkcs8', format: 'der' }).slice(-32))
+    };
+  }
+
+  /** @inheritdoc */
+  sharedSecret(secretKey, publicKey) {
+    const crypto = this._getCrypto();
+    const privKey = crypto.createPrivateKey({
+      key: Buffer.concat([
+        Buffer.from('302e020100300506032b656e04220420', 'hex'),
+        Buffer.from(secretKey)
+      ]),
+      format: 'der',
+      type: 'pkcs8'
+    });
+    const pubKey = crypto.createPublicKey({
+      key: Buffer.concat([
+        Buffer.from('302a300506032b656e032100', 'hex'),
+        Buffer.from(publicKey)
+      ]),
+      format: 'der',
+      type: 'spki'
+    });
+    const shared = crypto.diffieHellman({ privateKey: privKey, publicKey: pubKey });
+    return new Uint8Array(shared);
+  }
+
+  /** @inheritdoc */
+  encrypt(key, nonce, plaintext, _ad) {
+    // Use tweetnacl for encryption to ensure cross-provider compatibility
+    // QuickCrypto's advantage is in fast native key generation (X25519), not AEAD
+    const nacl = require('tweetnacl');
+
+    // Ensure 24-byte nonce for XSalsa20-Poly1305
+    let fullNonce = nonce;
+    if (nonce.length < 24) {
+      fullNonce = new Uint8Array(24);
+      fullNonce.set(nonce);
+    }
+
+    return nacl.secretbox(plaintext, fullNonce, key);
+  }
+
+  /** @inheritdoc */
+  decrypt(key, nonce, ciphertext, _ad) {
+    const nacl = require('tweetnacl');
+
+    // Ensure 24-byte nonce for XSalsa20-Poly1305
+    let fullNonce = nonce;
+    if (nonce.length < 24) {
+      fullNonce = new Uint8Array(24);
+      fullNonce.set(nonce);
+    }
+
+    const result = nacl.secretbox.open(ciphertext, fullNonce, key);
+    if (!result) {
+      return null; // Decryption failed: authentication error
+    }
+    return result;
+  }
+
+  /** @inheritdoc */
+  hash(data) {
+    // Use SHA-512 truncated to 32 bytes for cross-provider compatibility
+    const nacl = require('tweetnacl');
+    const full = nacl.hash(data); // SHA-512
+    return full.slice(0, 32);
+  }
+
+  /** @inheritdoc */
+  randomBytes(length) {
+    const crypto = this._getCrypto();
+    return new Uint8Array(crypto.randomBytes(length));
+  }
+
+  static isAvailable() {
+    try {
+      require('react-native-quick-crypto');
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+}
+
+module.exports = QuickCryptoProvider;

package/src/crypto/providers/TweetNaClProvider.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * @fileoverview TweetNaCl-based crypto provider
+ * @module crypto/providers/TweetNaClProvider
+ *
+ * Uses the `tweetnacl` library — lightweight, audited, works everywhere.
+ * Install: npm install tweetnacl
+ */
+
+const CryptoProvider = require('../CryptoProvider');
+
+/**
+ * Crypto provider using tweetnacl.
+ * Provides X25519 key exchange, XSalsa20-Poly1305 AEAD, SHA-512 (for hashing).
+ *
+ * @class TweetNaClProvider
+ * @extends CryptoProvider
+ */
+class TweetNaClProvider extends CryptoProvider {
+  /**
+   * @param {Object} [options={}]
+   * @param {Object} [options.nacl] - Injected tweetnacl instance (for testing)
+   */
+  constructor(options = {}) {
+    super();
+    this._nacl = options.nacl || null;
+  }
+
+  get name() {
+    return 'tweetnacl';
+  }
+
+  /**
+   * Lazily loads tweetnacl
+   * @returns {Object} nacl module
+   * @private
+   */
+  _getNacl() {
+    if (!this._nacl) {
+      try {
+        this._nacl = require('tweetnacl');
+      } catch (e) {
+        throw new Error(
+          'tweetnacl is required for TweetNaClProvider. Install: npm install tweetnacl'
+        );
+      }
+    }
+    return this._nacl;
+  }
+
+  /** @inheritdoc */
+  generateKeyPair() {
+    const nacl = this._getNacl();
+    const kp = nacl.box.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+  }
+
+  /** @inheritdoc */
+  sharedSecret(secretKey, publicKey) {
+    const nacl = this._getNacl();
+    return nacl.box.before(publicKey, secretKey);
+  }
+
+  /** @inheritdoc */
+  encrypt(key, nonce, plaintext, _ad) {
+    const nacl = this._getNacl();
+    // tweetnacl uses XSalsa20-Poly1305 with 24-byte nonce
+    // nacl.secretbox includes authentication
+
+    // Ensure 24-byte nonce (pad short nonces with zeros)
+    let fullNonce = nonce;
+    if (nonce.length < 24) {
+      fullNonce = new Uint8Array(24);
+      fullNonce.set(nonce);
+    }
+
+    return nacl.secretbox(plaintext, fullNonce, key);
+  }
+
+  /** @inheritdoc */
+  decrypt(key, nonce, ciphertext, _ad) {
+    const nacl = this._getNacl();
+
+    // Ensure 24-byte nonce (pad short nonces with zeros)
+    let fullNonce = nonce;
+    if (nonce.length < 24) {
+      fullNonce = new Uint8Array(24);
+      fullNonce.set(nonce);
+    }
+
+    const result = nacl.secretbox.open(ciphertext, fullNonce, key);
+    return result || null; // returns null on auth failure
+  }
+
+  /** @inheritdoc */
+  hash(data) {
+    const nacl = this._getNacl();
+    // tweetnacl provides SHA-512; we return first 32 bytes for SHA-256 compatibility
+    const full = nacl.hash(data);
+    return full.slice(0, 32);
+  }
+
+  /** @inheritdoc */
+  randomBytes(length) {
+    const nacl = this._getNacl();
+    return nacl.randomBytes(length);
+  }
+
+  /**
+   * Checks if tweetnacl is available
+   * @returns {boolean}
+   */
+  static isAvailable() {
+    try {
+      require('tweetnacl');
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+}
+
+module.exports = TweetNaClProvider;

package/src/crypto/providers/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const TweetNaClProvider = require('./TweetNaClProvider');
+const QuickCryptoProvider = require('./QuickCryptoProvider');
+const ExpoCryptoProvider = require('./ExpoCryptoProvider');
+
+module.exports = {
+  TweetNaClProvider,
+  QuickCryptoProvider,
+  ExpoCryptoProvider
+};

package/src/errors/MeshError.js

@@ -20,7 +20,8 @@ class MeshError extends Error {
    * @param {Object|null} [details=null] - Additional error context
    */
   constructor(message, code = 'E900', details = null) {
-    super(message);
+    const className = new.target ? new.target.name : 'MeshError';
+    super(`${className}: ${message}`);
 
     /**
      * Error name