react-native-ble-mesh 1.0.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,384 @@
+# Architecture Documentation
+
+## System Overview
+
+The BLE Mesh Network library is organized into layered modules with clear separation of concerns:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Application Layer                        │
+│                    (MeshService API)                         │
+├─────────────────────────────────────────────────────────────┤
+│                      Service Layer                           │
+│   ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
+│   │  Session    │ │  Handshake  │ │      Channel        │   │
+│   │  Manager    │ │  Manager    │ │      Manager        │   │
+│   └─────────────┘ └─────────────┘ └─────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                       Mesh Layer                             │
+│   ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
+│   │   Router    │ │    Peer     │ │     Fragment        │   │
+│   │  (Dedup)    │ │   Manager   │ │     Assembler       │   │
+│   └─────────────┘ └─────────────┘ └─────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                     Protocol Layer                           │
+│   ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
+│   │  Serializer │ │ Deserializer│ │     Validator       │   │
+│   └─────────────┘ └─────────────┘ └─────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                      Crypto Layer                            │
+│   ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
+│   │    Noise    │ │    AEAD     │ │      X25519         │   │
+│   │  Protocol   │ │ (ChaCha20)  │ │   Key Exchange      │   │
+│   └─────────────┘ └─────────────┘ └─────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                     Transport Layer                          │
+│   ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐   │
+│   │    BLE      │ │    Mock     │ │      Adapters       │   │
+│   │  Transport  │ │  Transport  │ │   (RN/Node/Web)     │   │
+│   └─────────────┘ └─────────────┘ └─────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Module Dependency Graph
+
+```
+                        index.js
+                           │
+                           ▼
+                     MeshService
+                     /    │    \
+                    /     │     \
+                   ▼      ▼      ▼
+            Session  Handshake  Channel
+            Manager   Manager   Manager
+                \       │       /
+                 \      │      /
+                  ▼     ▼     ▼
+               ┌─────────────────┐
+               │   Mesh Layer    │
+               │  ┌───────────┐  │
+               │  │  Router   │  │
+               │  │  ┌─────┐  │  │
+               │  │  │Dedup│  │  │
+               │  │  └─────┘  │  │
+               │  └───────────┘  │
+               │  ┌───────────┐  │
+               │  │   Peer    │  │
+               │  │  Manager  │  │
+               │  └───────────┘  │
+               │  ┌───────────┐  │
+               │  │ Fragment  │  │
+               │  └───────────┘  │
+               └─────────────────┘
+                        │
+                        ▼
+               ┌─────────────────┐
+               │ Protocol Layer  │
+               │  ┌───────────┐  │
+               │  │  Message  │  │
+               │  │  Header   │  │
+               │  └───────────┘  │
+               │  ┌───────────┐  │
+               │  │Serializer │  │
+               │  └───────────┘  │
+               └─────────────────┘
+                        │
+                        ▼
+               ┌─────────────────┐
+               │  Crypto Layer   │
+               │  ┌───────────┐  │
+               │  │   Noise   │  │
+               │  │ Handshake │  │
+               │  └───────────┘  │
+               │  ┌───────────┐  │
+               │  │   AEAD    │  │
+               │  └───────────┘  │
+               │  ┌───────────┐  │
+               │  │  X25519   │  │
+               │  └───────────┘  │
+               │  ┌───────────┐  │
+               │  │  SHA-256  │  │
+               │  └───────────┘  │
+               └─────────────────┘
+```
+
+## Data Flow
+
+### Outgoing Message Flow
+
+```
+Application
+    │
+    │ sendPrivateMessage(peerId, content)
+    ▼
+MeshService
+    │
+    │ Create Message object
+    ▼
+SessionManager
+    │
+    │ Get NoiseSession for peer
+    │ Encrypt payload
+    ▼
+MessageRouter
+    │
+    │ Check routing table
+    │ Get next hop
+    ▼
+Serializer
+    │
+    │ Serialize to binary
+    │ Add CRC32 checksum
+    ▼
+Transport
+    │
+    │ Send over BLE
+    ▼
+Remote Peer
+```
+
+### Incoming Message Flow
+
+```
+Transport
+    │
+    │ Receive bytes
+    ▼
+Deserializer
+    │
+    │ Parse header
+    │ Verify checksum
+    ▼
+MessageRouter
+    │
+    │ Check if duplicate (Bloom + LRU)
+    │ Check TTL and hop count
+    │
+    ├──► If for us: process locally
+    │
+    ▼
+SessionManager
+    │
+    │ Get NoiseSession
+    │ Decrypt payload
+    ▼
+MeshService
+    │
+    │ Emit 'message:received'
+    ▼
+Application
+```
+
+### Handshake Flow
+
+```
+┌──────────┐                              ┌──────────┐
+│  Alice   │                              │   Bob    │
+│(Initiator)                              │(Responder)
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  initializeInitiator(aliceStatic)       │  initializeResponder(bobStatic)
+     │                                         │
+     │              Message 1                  │
+     │  ────────────────────────────────────►  │
+     │  e (ephemeral public key, 32 bytes)     │
+     │                                         │
+     │              Message 2                  │
+     │  ◄────────────────────────────────────  │
+     │  e, ee, s, es (96 bytes)                │
+     │  - Bob's ephemeral public key           │
+     │  - Encrypted Bob's static public key    │
+     │                                         │
+     │              Message 3                  │
+     │  ────────────────────────────────────►  │
+     │  s, se (48 bytes)                       │
+     │  - Encrypted Alice's static public key  │
+     │                                         │
+     │         ◄ Session Established ►         │
+     │                                         │
+     │  getSession() → NoiseSession            │  getSession() → NoiseSession
+     │  (sendKey, receiveKey)                  │  (sendKey, receiveKey)
+     │                                         │
+     │            Encrypted Data               │
+     │  ◄─────────────────────────────────────►│
+     │                                         │
+```
+
+## State Machine
+
+### MeshService States
+
+```
+                         initialize()
+        ┌───────────┐ ──────────────► ┌──────────────┐
+        │UNINITIALIZED│               │ INITIALIZING │
+        └───────────┘                 └──────┬───────┘
+                                             │
+                                             │ success
+                                             ▼
+                              ┌─────────────────────────┐
+                              │         READY           │
+                              └───────────┬─────────────┘
+                                          │
+                                          │ start(transport)
+                                          ▼
+              stop()        ┌─────────────────────────┐
+         ◄────────────────  │         ACTIVE          │
+                            └───────────┬─────────────┘
+                                        │
+                    ┌───────────────────┼───────────────────┐
+                    │                   │                   │
+                    │ error             │ suspend           │ destroy
+                    ▼                   ▼                   ▼
+            ┌───────────┐       ┌───────────┐       ┌───────────┐
+            │   ERROR   │       │ SUSPENDED │       │ DESTROYED │
+            └───────────┘       └───────────┘       └───────────┘
+                    │                   │
+                    └───────────────────┘
+                            │
+                            │ recover/resume
+                            ▼
+                    ┌───────────┐
+                    │  ACTIVE   │
+                    └───────────┘
+```
+
+### Peer States
+
+```
+        ┌──────────────┐
+        │  DISCOVERED  │ ◄── Transport discovery
+        └──────┬───────┘
+               │
+               │ connect()
+               ▼
+        ┌──────────────┐
+        │  CONNECTING  │
+        └──────┬───────┘
+               │
+               │ connection established
+               ▼
+        ┌──────────────┐
+        │  CONNECTED   │
+        └──────┬───────┘
+               │
+               │ handshake complete
+               ▼
+        ┌──────────────┐
+        │   SECURED    │ ◄── Ready for encrypted messages
+        └──────┬───────┘
+               │
+               │ disconnect / timeout
+               ▼
+        ┌──────────────┐
+        │ DISCONNECTED │
+        └──────────────┘
+```
+
+## Key Components
+
+### Crypto Layer
+
+| Component | Purpose |
+|-----------|---------|
+| `sha256.js` | SHA-256 hash function (FIPS 180-4) |
+| `hmac.js` | HMAC-SHA256 message authentication |
+| `hkdf.js` | HKDF key derivation (RFC 5869) |
+| `x25519.js` | Elliptic curve Diffie-Hellman |
+| `chacha20.js` | ChaCha20 stream cipher |
+| `poly1305.js` | Poly1305 MAC |
+| `aead.js` | ChaCha20-Poly1305 AEAD |
+| `noise/state.js` | Noise symmetric state |
+| `noise/handshake.js` | Noise XX handshake |
+| `noise/session.js` | Post-handshake encryption |
+
+### Protocol Layer
+
+| Component | Purpose |
+|-----------|---------|
+| `header.js` | 48-byte message header |
+| `message.js` | Message container class |
+| `serializer.js` | Binary serialization |
+| `deserializer.js` | Binary deserialization |
+| `validator.js` | Message validation |
+| `crc32.js` | CRC32 checksum |
+
+### Mesh Layer
+
+| Component | Purpose |
+|-----------|---------|
+| `BloomFilter.js` | Fast probabilistic duplicate detection |
+| `MessageCache.js` | LRU cache for recent messages |
+| `DedupManager.js` | Combined deduplication |
+| `Fragmenter.js` | Message fragmentation |
+| `Assembler.js` | Fragment reassembly |
+| `Peer.js` | Peer data structure |
+| `PeerManager.js` | Peer lifecycle management |
+| `RouteTable.js` | Routing information |
+| `MessageRouter.js` | Message routing logic |
+
+### Service Layer
+
+| Component | Purpose |
+|-----------|---------|
+| `MeshService.js` | Main orchestrator, public API |
+| `SessionManager.js` | Noise session lifecycle |
+| `HandshakeManager.js` | Handshake orchestration |
+| `ChannelManager.js` | Channel subscriptions |
+
+## Design Decisions
+
+### Why Pure JavaScript Crypto?
+
+1. **Portability**: Works in Node.js, React Native, and browsers
+2. **No Native Dependencies**: Easier installation and deployment
+3. **Auditability**: Code can be reviewed without native expertise
+4. **Trade-off**: Slower than native, but sufficient for messaging workloads
+
+### Why Noise Protocol XX?
+
+1. **Mutual Authentication**: Both parties prove identity
+2. **Forward Secrecy**: Ephemeral keys protect past sessions
+3. **Identity Hiding**: Static keys encrypted during handshake
+4. **Simplicity**: Well-defined pattern with clear security properties
+5. **No PKI Required**: Works peer-to-peer without certificate authorities
+
+### Why Bloom Filter + LRU?
+
+1. **Fast**: O(1) probabilistic check with Bloom filter
+2. **Accurate**: LRU cache eliminates false positives
+3. **Memory Efficient**: Bloom filter uses minimal memory
+4. **Bounded**: LRU prevents unbounded growth
+
+### Why 48-byte Header?
+
+1. **Fixed Size**: Simplifies parsing and allocation
+2. **Complete**: Contains all necessary routing metadata
+3. **Extensible**: Reserved bytes for future use
+4. **Checksummed**: CRC32 catches corruption
+
+## Performance Considerations
+
+### Message Throughput
+
+- Header serialization: ~50μs
+- AEAD encryption (256 bytes): ~100μs
+- Bloom filter check: ~1μs
+- Total per message: ~200μs
+- Theoretical throughput: ~5000 messages/second
+
+### Memory Usage
+
+- Bloom filter (2KB): 2,048 bytes
+- LRU cache (1000 entries): ~100KB
+- Peer manager (100 peers): ~50KB
+- Session keys (10 sessions): ~2KB
+- Total baseline: ~200KB
+
+### Battery Considerations
+
+- BLE scanning: Major power consumer
+- Configurable scan intervals (POWER_MODE)
+- Heartbeat interval tuning
+- Aggressive peer timeout for cleanup

package/docs/CONTRIBUTING.md

@@ -0,0 +1,244 @@
+# Contributing to BLE Mesh
+
+Thank you for your interest in contributing to BLE Mesh! This document provides guidelines and information for contributors.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn
+- Git
+
+### Setup
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/react-native-ble-mesh.git
+   cd react-native-ble-mesh
+   ```
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+4. Run tests to ensure everything works:
+   ```bash
+   npm test
+   ```
+
+## Development Guidelines
+
+### Code Style
+
+- **Maximum 200 lines per file** - Split large files into focused modules
+- Use **JSDoc comments** for all public APIs
+- Follow existing code patterns and naming conventions
+- Use strict mode (`'use strict';`) in all files
+
+### File Organization
+
+```
+src/
+├── core/         # Core mesh service
+├── crypto/       # Cryptographic primitives (flat structure)
+├── protocol/     # Wire protocol
+├── mesh/         # Mesh networking (flat structure)
+├── transport/    # Transport layer (flat structure)
+├── storage/      # Data persistence
+├── utils/        # Utility functions
+├── errors/       # Error classes
+├── hooks/        # React Native hooks
+└── plugins/      # Optional features (audio, text)
+```
+
+### Writing Code
+
+```javascript
+'use strict';
+
+/**
+ * @fileoverview Brief description of the file
+ * @module module/name
+ */
+
+const SomeDependency = require('./SomeDependency');
+
+/**
+ * Description of the class/function
+ * @class ClassName
+ * @example
+ * const instance = new ClassName(options);
+ */
+class ClassName {
+  /**
+   * Creates a new instance
+   * @param {Object} options - Configuration options
+   * @param {string} options.name - The name
+   */
+  constructor(options = {}) {
+    // Implementation
+  }
+}
+
+module.exports = ClassName;
+```
+
+### Error Handling
+
+Use custom error classes from `src/errors/`:
+
+```javascript
+const { CryptoError, ConnectionError } = require('../errors');
+
+// Throw appropriate errors
+if (!isValid) {
+  throw new CryptoError('Invalid key format', 'E_CRYPTO_002');
+}
+```
+
+### Testing
+
+- Write tests for all new functionality
+- Place tests in `__tests__/` mirroring `src/` structure
+- Aim for **>80% code coverage** (100% for crypto)
+- Use descriptive test names
+
+```javascript
+describe('ClassName', () => {
+  describe('methodName()', () => {
+    test('does something specific', () => {
+      // Arrange
+      const instance = new ClassName();
+
+      // Act
+      const result = instance.methodName();
+
+      // Assert
+      expect(result).toBe(expected);
+    });
+
+    test('throws error for invalid input', () => {
+      expect(() => instance.methodName(null)).toThrow(SomeError);
+    });
+  });
+});
+```
+
+Run tests:
+```bash
+npm test                    # Run all tests
+npm test -- --watch         # Watch mode
+npm test -- --coverage      # With coverage
+npm test -- path/to/test    # Specific test
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Run tests**: `npm test`
+2. **Run linter**: `npm run lint`
+3. **Check coverage**: `npm test -- --coverage`
+4. Update documentation if needed
+5. Add tests for new features
+
+### PR Guidelines
+
+1. Create a feature branch from `master`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes with clear, focused commits
+
+3. Write a clear PR description:
+   - What changes were made
+   - Why the changes were made
+   - How to test the changes
+
+4. Ensure CI passes (tests, linting)
+
+5. Request review from maintainers
+
+### Commit Messages
+
+Follow conventional commit format:
+
+```
+type(scope): brief description
+
+Longer description if needed.
+
+Fixes #123
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `test`: Tests
+- `refactor`: Code refactoring
+- `perf`: Performance improvement
+- `chore`: Maintenance
+
+Examples:
+```
+feat(hooks): add useMesh hook for React Native
+fix(transport): handle BLE disconnection gracefully
+docs(readme): update installation instructions
+test(crypto): add Ed25519 test vectors
+```
+
+## Architecture Guidelines
+
+### Module Dependencies
+
+```
+index.js (entry point)
+    ↓
+service/MeshService.js (orchestrator)
+    ├→ crypto/ (no external deps)
+    ├→ protocol/ (depends on crypto)
+    ├→ mesh/ (depends on protocol, crypto)
+    ├→ transport/ (depends on protocol)
+    └→ storage/ (depends on protocol)
+```
+
+**Rules:**
+- No circular dependencies
+- Lower layers don't depend on higher layers
+- Utils and errors can be used anywhere
+
+### Adding New Features
+
+1. **Discuss first**: Open an issue to discuss the feature
+2. **Design**: Consider how it fits with existing architecture
+3. **Implement**: Follow existing patterns
+4. **Test**: Write comprehensive tests
+5. **Document**: Update API docs and examples
+
+### Performance Considerations
+
+- Use `BoundedMap` for caches (prevents memory leaks)
+- Use `TimeoutManager` for timeouts (prevents memory leaks)
+- Use optimized `base64` module (not string concatenation)
+- Batch async operations when possible
+- Profile before and after changes
+
+## Security Guidelines
+
+- **Never log secrets** (keys, tokens, passwords)
+- Use **constant-time comparisons** for sensitive data
+- Follow existing crypto patterns
+- Report security issues privately to maintainers
+
+## Getting Help
+
+- **Questions**: Open a GitHub Discussion
+- **Bugs**: Open a GitHub Issue
+- **Security**: Email maintainers directly
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.