react-native-ble-mesh 1.0.1

package/src/crypto/keys/KeyManager.js

@@ -0,0 +1,271 @@
+'use strict';
+
+/**
+ * KeyManager for identity and key lifecycle management.
+ * Handles persistent identity storage and retrieval.
+ * @module crypto/keys/KeyManager
+ */
+
+const { KeyPair } = require('./KeyPair');
+
+/**
+ * Default storage key for identity
+ * @constant {string}
+ */
+const DEFAULT_IDENTITY_KEY = 'mesh_identity';
+
+/**
+ * KeyManager handles identity key management for the mesh network.
+ * Provides methods to generate, store, and retrieve identity keys.
+ *
+ * @class
+ */
+class KeyManager {
+  /**
+   * Creates a new KeyManager.
+   * @param {object} [options={}] - Configuration options
+   * @param {object} [options.storage] - Storage adapter (SecureStorage interface)
+   * @param {string} [options.identityKey] - Storage key for identity
+   */
+  constructor(options = {}) {
+    /** @type {object|null} */
+    this._storage = options.storage || null;
+
+    /** @type {string} */
+    this._identityKey = options.identityKey || DEFAULT_IDENTITY_KEY;
+
+    /** @type {KeyPair|null} */
+    this._identity = null;
+
+    /** @type {string|null} */
+    this._displayName = null;
+  }
+
+  /**
+   * Generates a new identity key pair.
+   * Does not persist automatically - call saveIdentity() to persist.
+   * @returns {KeyPair} New identity key pair
+   */
+  generateIdentity() {
+    // Destroy existing identity if present
+    if (this._identity) {
+      this._identity.destroy();
+    }
+
+    this._identity = KeyPair.generate();
+    return this._identity;
+  }
+
+  /**
+   * Gets the current identity, generating one if needed.
+   * If storage is configured, attempts to load from storage first.
+   * @returns {Promise<KeyPair>} Current or new identity
+   */
+  async getOrCreateIdentity() {
+    // Return existing identity if available
+    if (this._identity && !this._identity.isDestroyed()) {
+      return this._identity;
+    }
+
+    // Try to load from storage
+    if (this._storage) {
+      const loaded = await this.loadIdentity();
+      if (loaded) {
+        return loaded;
+      }
+    }
+
+    // Generate new identity
+    this.generateIdentity();
+
+    // Persist if storage is available
+    if (this._storage) {
+      await this.saveIdentity();
+    }
+
+    return this._identity;
+  }
+
+  /**
+   * Gets the current identity without generating.
+   * @returns {KeyPair|null} Current identity or null
+   */
+  getIdentity() {
+    if (this._identity && !this._identity.isDestroyed()) {
+      return this._identity;
+    }
+    return null;
+  }
+
+  /**
+   * Gets the public key of the current identity.
+   * @returns {Uint8Array|null} Public key or null if no identity
+   */
+  getPublicKey() {
+    const identity = this.getIdentity();
+    return identity ? identity.publicKey : null;
+  }
+
+  /**
+   * Saves the current identity to storage.
+   * @returns {Promise<boolean>} True if saved successfully
+   * @throws {Error} If no identity or storage not configured
+   */
+  async saveIdentity() {
+    if (!this._identity) {
+      throw new Error('No identity to save');
+    }
+    if (!this._storage) {
+      throw new Error('Storage not configured');
+    }
+
+    const data = {
+      keyPair: this._identity.export(),
+      displayName: this._displayName,
+      createdAt: Date.now()
+    };
+
+    await this._storage.set(this._identityKey, JSON.stringify(data));
+    return true;
+  }
+
+  /**
+   * Loads identity from storage.
+   * @returns {Promise<KeyPair|null>} Loaded identity or null
+   */
+  async loadIdentity() {
+    if (!this._storage) {
+      return null;
+    }
+
+    try {
+      const data = await this._storage.get(this._identityKey);
+      if (!data) {
+        return null;
+      }
+
+      const parsed = JSON.parse(data);
+      if (!parsed.keyPair) {
+        return null;
+      }
+
+      this._identity = KeyPair.fromExported(parsed.keyPair);
+      this._displayName = parsed.displayName || null;
+
+      return this._identity;
+    } catch (error) {
+      console.warn('Failed to load identity:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Imports an identity from exported data.
+   * @param {object} exported - Exported identity data
+   * @param {object} exported.publicKey - Public key as byte array
+   * @param {object} exported.secretKey - Secret key as byte array
+   * @returns {KeyPair} Imported identity
+   */
+  importIdentity(exported) {
+    // Destroy existing identity
+    if (this._identity) {
+      this._identity.destroy();
+    }
+
+    this._identity = KeyPair.fromExported(exported);
+    return this._identity;
+  }
+
+  /**
+   * Exports the current identity for backup.
+   * WARNING: Contains sensitive key material.
+   * @returns {object|null} Exported identity or null
+   */
+  exportIdentity() {
+    if (!this._identity || this._identity.isDestroyed()) {
+      return null;
+    }
+
+    return {
+      ...this._identity.export(),
+      displayName: this._displayName
+    };
+  }
+
+  /**
+   * Sets the display name for this identity.
+   * @param {string} name - Display name
+   */
+  setDisplayName(name) {
+    if (typeof name !== 'string') {
+      throw new Error('Display name must be a string');
+    }
+    this._displayName = name;
+  }
+
+  /**
+   * Gets the display name.
+   * @returns {string|null} Display name or null
+   */
+  getDisplayName() {
+    return this._displayName;
+  }
+
+  /**
+   * Deletes the identity from storage and memory.
+   * @returns {Promise<void>}
+   */
+  async deleteIdentity() {
+    if (this._identity) {
+      this._identity.destroy();
+      this._identity = null;
+    }
+
+    this._displayName = null;
+
+    if (this._storage) {
+      await this._storage.delete(this._identityKey);
+    }
+  }
+
+  /**
+   * Checks if an identity exists (in memory or storage).
+   * @returns {Promise<boolean>} True if identity exists
+   */
+  async hasIdentity() {
+    if (this._identity && !this._identity.isDestroyed()) {
+      return true;
+    }
+
+    if (this._storage) {
+      const data = await this._storage.get(this._identityKey);
+      return data !== null && data !== undefined;
+    }
+
+    return false;
+  }
+
+  /**
+   * Sets the storage adapter.
+   * @param {object} storage - Storage adapter implementing SecureStorage interface
+   */
+  setStorage(storage) {
+    this._storage = storage;
+  }
+
+  /**
+   * Clears all in-memory data (does not affect storage).
+   */
+  clear() {
+    if (this._identity) {
+      this._identity.destroy();
+      this._identity = null;
+    }
+    this._displayName = null;
+  }
+}
+
+module.exports = {
+  KeyManager,
+  DEFAULT_IDENTITY_KEY
+};

package/src/crypto/keys/KeyPair.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * KeyPair class for X25519 key management.
+ * Provides a secure wrapper around public/private key pairs.
+ * @module crypto/keys/KeyPair
+ */
+
+const { generateKeyPair: x25519GenerateKeyPair, scalarMultBase } = require('../x25519');
+
+/**
+ * Key size in bytes (X25519)
+ * @constant {number}
+ */
+const KEY_SIZE = 32;
+
+/**
+ * KeyPair represents an X25519 key pair for Noise Protocol handshakes.
+ * Provides secure key management with proper cleanup.
+ *
+ * @class
+ */
+class KeyPair {
+  /**
+   * Creates a KeyPair instance.
+   * Use static factory methods instead of constructor directly.
+   * @param {Uint8Array} publicKey - 32-byte public key
+   * @param {Uint8Array} secretKey - 32-byte secret key
+   * @private
+   */
+  constructor(publicKey, secretKey) {
+    if (!(publicKey instanceof Uint8Array) || publicKey.length !== KEY_SIZE) {
+      throw new Error(`Public key must be ${KEY_SIZE} bytes`);
+    }
+    if (!(secretKey instanceof Uint8Array) || secretKey.length !== KEY_SIZE) {
+      throw new Error(`Secret key must be ${KEY_SIZE} bytes`);
+    }
+
+    /** @type {Uint8Array} */
+    this._publicKey = new Uint8Array(publicKey);
+
+    /** @type {Uint8Array} */
+    this._secretKey = new Uint8Array(secretKey);
+
+    /** @type {boolean} */
+    this._destroyed = false;
+  }
+
+  /**
+   * Gets the public key.
+   * @returns {Uint8Array} Copy of the public key
+   * @throws {Error} If key pair has been destroyed
+   */
+  get publicKey() {
+    this._checkDestroyed();
+    return new Uint8Array(this._publicKey);
+  }
+
+  /**
+   * Gets the secret key.
+   * @returns {Uint8Array} Copy of the secret key
+   * @throws {Error} If key pair has been destroyed
+   */
+  get secretKey() {
+    this._checkDestroyed();
+    return new Uint8Array(this._secretKey);
+  }
+
+  /**
+   * Generates a new random X25519 key pair.
+   * @returns {KeyPair} New key pair
+   *
+   * @example
+   * const keyPair = KeyPair.generate();
+   * console.log('Public key:', keyPair.publicKey);
+   */
+  static generate() {
+    const { publicKey, secretKey } = x25519GenerateKeyPair();
+    return new KeyPair(publicKey, secretKey);
+  }
+
+  /**
+   * Creates a KeyPair from an existing secret key.
+   * Derives the public key from the secret key.
+   * @param {Uint8Array} secretKey - 32-byte secret key
+   * @returns {KeyPair} Key pair with derived public key
+   * @throws {Error} If secret key is invalid
+   *
+   * @example
+   * const restored = KeyPair.fromSecretKey(storedSecretKey);
+   */
+  static fromSecretKey(secretKey) {
+    if (!(secretKey instanceof Uint8Array) || secretKey.length !== KEY_SIZE) {
+      throw new Error(`Secret key must be ${KEY_SIZE} bytes`);
+    }
+
+    const publicKey = scalarMultBase(secretKey);
+    return new KeyPair(publicKey, secretKey);
+  }
+
+  /**
+   * Creates a KeyPair from exported key material.
+   * @param {object} exported - Exported key object
+   * @param {number[]} exported.publicKey - Public key as byte array
+   * @param {number[]} exported.secretKey - Secret key as byte array
+   * @returns {KeyPair} Restored key pair
+   * @throws {Error} If exported data is invalid
+   */
+  static fromExported(exported) {
+    if (!exported || typeof exported !== 'object') {
+      throw new Error('Invalid exported key data');
+    }
+    if (!Array.isArray(exported.publicKey) || !Array.isArray(exported.secretKey)) {
+      throw new Error('Exported data must contain publicKey and secretKey arrays');
+    }
+
+    const publicKey = new Uint8Array(exported.publicKey);
+    const secretKey = new Uint8Array(exported.secretKey);
+
+    return new KeyPair(publicKey, secretKey);
+  }
+
+  /**
+   * Exports the key pair for storage.
+   * WARNING: The exported data contains sensitive key material.
+   * @returns {object} Exportable key object
+   */
+  export() {
+    this._checkDestroyed();
+    return {
+      publicKey: Array.from(this._publicKey),
+      secretKey: Array.from(this._secretKey)
+    };
+  }
+
+  /**
+   * Exports only the public key (safe to share).
+   * @returns {object} Object containing only the public key
+   */
+  exportPublic() {
+    this._checkDestroyed();
+    return {
+      publicKey: Array.from(this._publicKey)
+    };
+  }
+
+  /**
+   * Checks if this key pair matches another by public key.
+   * @param {KeyPair} other - Another key pair to compare
+   * @returns {boolean} True if public keys match
+   */
+  matches(other) {
+    this._checkDestroyed();
+    if (!(other instanceof KeyPair)) {
+      return false;
+    }
+
+    const otherPublic = other.publicKey;
+    if (otherPublic.length !== this._publicKey.length) {
+      return false;
+    }
+
+    // Constant-time comparison
+    let diff = 0;
+    for (let i = 0; i < this._publicKey.length; i++) {
+      diff |= this._publicKey[i] ^ otherPublic[i];
+    }
+    return diff === 0;
+  }
+
+  /**
+   * Gets the public key as a hex string (useful for display/logging).
+   * @returns {string} Hex-encoded public key
+   */
+  getPublicKeyHex() {
+    this._checkDestroyed();
+    return Array.from(this._publicKey)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /**
+   * Securely destroys the key pair, zeroing sensitive material.
+   * After destruction, the key pair cannot be used.
+   */
+  destroy() {
+    if (!this._destroyed) {
+      this._secretKey.fill(0);
+      this._publicKey.fill(0);
+      this._destroyed = true;
+    }
+  }
+
+  /**
+   * Checks if the key pair has been destroyed.
+   * @returns {boolean} True if destroyed
+   */
+  isDestroyed() {
+    return this._destroyed;
+  }
+
+  /**
+   * Throws if the key pair has been destroyed.
+   * @private
+   */
+  _checkDestroyed() {
+    if (this._destroyed) {
+      throw new Error('Key pair has been destroyed');
+    }
+  }
+}
+
+module.exports = {
+  KeyPair,
+  KEY_SIZE
+};

package/src/crypto/keys/SecureStorage.js

@@ -0,0 +1,219 @@
+'use strict';
+
+/**
+ * SecureStorage - Abstract storage interface for sensitive key material.
+ * Implementations should use platform-specific secure storage mechanisms.
+ * @module crypto/keys/SecureStorage
+ */
+
+/**
+ * SecureStorage defines the interface for secure key storage.
+ * This is an abstract class - use platform-specific implementations.
+ *
+ * Platform implementations:
+ * - React Native: Use react-native-keychain or expo-secure-store
+ * - Node.js: Use encrypted file storage or keytar
+ * - Browser: Use IndexedDB with encryption
+ *
+ * @abstract
+ * @class
+ */
+class SecureStorage {
+  /**
+   * Stores a value securely.
+   * @param {string} key - Storage key
+   * @param {string} value - Value to store (should be serialized JSON)
+   * @returns {Promise<void>}
+   * @abstract
+   */
+  async set(_key, _value) {
+    throw new Error('SecureStorage.set() must be implemented');
+  }
+
+  /**
+   * Retrieves a stored value.
+   * @param {string} key - Storage key
+   * @returns {Promise<string|null>} Stored value or null if not found
+   * @abstract
+   */
+  async get(_key) {
+    throw new Error('SecureStorage.get() must be implemented');
+  }
+
+  /**
+   * Deletes a stored value.
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   * @abstract
+   */
+  async delete(_key) {
+    throw new Error('SecureStorage.delete() must be implemented');
+  }
+
+  /**
+   * Checks if a key exists in storage.
+   * @param {string} key - Storage key
+   * @returns {Promise<boolean>} True if key exists
+   */
+  async has(key) {
+    const value = await this.get(key);
+    return value !== null && value !== undefined;
+  }
+
+  /**
+   * Clears all stored values.
+   * @returns {Promise<void>}
+   * @abstract
+   */
+  async clear() {
+    throw new Error('SecureStorage.clear() must be implemented');
+  }
+}
+
+/**
+ * MemorySecureStorage - In-memory implementation for testing.
+ * WARNING: Not secure for production use - keys are not persisted
+ * and are stored in plain memory.
+ *
+ * @class
+ * @extends SecureStorage
+ */
+class MemorySecureStorage extends SecureStorage {
+  constructor() {
+    super();
+    /** @type {Map<string, string>} */
+    this._store = new Map();
+  }
+
+  /**
+   * Stores a value in memory.
+   * @param {string} key - Storage key
+   * @param {string} value - Value to store
+   * @returns {Promise<void>}
+   */
+  async set(key, value) {
+    if (typeof key !== 'string') {
+      throw new Error('Key must be a string');
+    }
+    if (typeof value !== 'string') {
+      throw new Error('Value must be a string');
+    }
+    this._store.set(key, value);
+  }
+
+  /**
+   * Retrieves a value from memory.
+   * @param {string} key - Storage key
+   * @returns {Promise<string|null>} Stored value or null
+   */
+  async get(key) {
+    if (typeof key !== 'string') {
+      throw new Error('Key must be a string');
+    }
+    return this._store.get(key) || null;
+  }
+
+  /**
+   * Deletes a value from memory.
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    if (typeof key !== 'string') {
+      throw new Error('Key must be a string');
+    }
+    this._store.delete(key);
+  }
+
+  /**
+   * Clears all stored values.
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this._store.clear();
+  }
+
+  /**
+   * Gets the number of stored items.
+   * @returns {number} Number of items
+   */
+  get size() {
+    return this._store.size;
+  }
+}
+
+/**
+ * Creates a SecureStorage adapter for React Native AsyncStorage.
+ * Note: AsyncStorage is NOT secure - consider using expo-secure-store
+ * or react-native-keychain for production.
+ *
+ * @param {object} asyncStorage - AsyncStorage instance
+ * @returns {SecureStorage} Storage adapter
+ *
+ * @example
+ * import AsyncStorage from '@react-native-async-storage/async-storage';
+ * const storage = createAsyncStorageAdapter(AsyncStorage);
+ */
+function createAsyncStorageAdapter(asyncStorage) {
+  return {
+    async set(key, value) {
+      await asyncStorage.setItem(key, value);
+    },
+    async get(key) {
+      return await asyncStorage.getItem(key);
+    },
+    async delete(key) {
+      await asyncStorage.removeItem(key);
+    },
+    async has(key) {
+      const value = await asyncStorage.getItem(key);
+      return value !== null;
+    },
+    async clear() {
+      // Only clear mesh-related keys
+      const keys = await asyncStorage.getAllKeys();
+      const meshKeys = keys.filter(k => k.startsWith('mesh_'));
+      await asyncStorage.multiRemove(meshKeys);
+    }
+  };
+}
+
+/**
+ * Creates a SecureStorage adapter for expo-secure-store.
+ * This provides actual secure storage on iOS/Android.
+ *
+ * @param {object} secureStore - SecureStore module from expo-secure-store
+ * @returns {SecureStorage} Storage adapter
+ *
+ * @example
+ * import * as SecureStore from 'expo-secure-store';
+ * const storage = createExpoSecureStoreAdapter(SecureStore);
+ */
+function createExpoSecureStoreAdapter(secureStore) {
+  return {
+    async set(key, value) {
+      await secureStore.setItemAsync(key, value);
+    },
+    async get(key) {
+      return await secureStore.getItemAsync(key);
+    },
+    async delete(key) {
+      await secureStore.deleteItemAsync(key);
+    },
+    async has(key) {
+      const value = await secureStore.getItemAsync(key);
+      return value !== null;
+    },
+    async clear() {
+      // expo-secure-store doesn't have getAllKeys, so we track known keys
+      console.warn('SecureStore clear() requires manual key tracking');
+    }
+  };
+}
+
+module.exports = {
+  SecureStorage,
+  MemorySecureStorage,
+  createAsyncStorageAdapter,
+  createExpoSecureStoreAdapter
+};