react-native-ble-mesh 1.0.1

package/src/protocol/crc32.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * @fileoverview CRC32 checksum implementation using standard polynomial.
+ * @module protocol/crc32
+ */
+
+/**
+ * CRC32 polynomial (IEEE 802.3 standard, reversed).
+ * @constant {number}
+ */
+const CRC32_POLYNOMIAL = 0xEDB88320;
+
+/**
+ * Pre-computed CRC32 lookup table.
+ * @type {Uint32Array}
+ */
+const CRC32_TABLE = buildTable();
+
+/**
+ * Builds the CRC32 lookup table.
+ * @returns {Uint32Array} 256-entry lookup table
+ */
+function buildTable() {
+  const table = new Uint32Array(256);
+
+  for (let i = 0; i < 256; i++) {
+    let crc = i;
+    for (let j = 0; j < 8; j++) {
+      if (crc & 1) {
+        crc = (crc >>> 1) ^ CRC32_POLYNOMIAL;
+      } else {
+        crc = crc >>> 1;
+      }
+    }
+    table[i] = crc >>> 0;
+  }
+
+  return table;
+}
+
+/**
+ * Calculates CRC32 checksum of the given data.
+ * Uses the standard CRC32 polynomial (0xEDB88320) with the IEEE algorithm.
+ *
+ * @param {Uint8Array} data - Input data to compute checksum for
+ * @returns {number} 32-bit unsigned CRC32 checksum
+ * @throws {TypeError} If data is not a Uint8Array
+ *
+ * @example
+ * const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
+ * const checksum = crc32(data);
+ * console.log(checksum.toString(16)); // "f7d18982"
+ */
+function crc32(data) {
+  if (!(data instanceof Uint8Array)) {
+    throw new TypeError('Data must be a Uint8Array');
+  }
+
+  let crc = 0xFFFFFFFF;
+
+  for (let i = 0; i < data.length; i++) {
+    const byte = data[i];
+    const tableIndex = (crc ^ byte) & 0xFF;
+    crc = (crc >>> 8) ^ CRC32_TABLE[tableIndex];
+  }
+
+  // Return inverted result as unsigned 32-bit integer
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+/**
+ * Verifies that data matches an expected CRC32 checksum.
+ *
+ * @param {Uint8Array} data - Input data to verify
+ * @param {number} expectedCrc - Expected CRC32 checksum
+ * @returns {boolean} True if checksum matches
+ *
+ * @example
+ * const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+ * const isValid = verifyCrc32(data, 0xf7d18982);
+ * console.log(isValid); // true
+ */
+function verifyCrc32(data, expectedCrc) {
+  const actualCrc = crc32(data);
+  return actualCrc === (expectedCrc >>> 0);
+}
+
+module.exports = {
+  crc32,
+  verifyCrc32,
+  CRC32_POLYNOMIAL
+};

package/src/protocol/deserializer.js

@@ -0,0 +1,241 @@
+'use strict';
+
+/**
+ * @fileoverview Binary deserialization for mesh protocol messages.
+ * @module protocol/deserializer
+ */
+
+const { MessageHeader, HEADER_SIZE } = require('./header');
+const { Message } = require('./message');
+const { crc32 } = require('./crc32');
+const { MessageError } = require('../errors');
+
+/**
+ * Deserializes a message header from bytes.
+ * Validates minimum length and verifies checksum.
+ *
+ * @param {Uint8Array} data - Raw header bytes (minimum 48 bytes)
+ * @returns {MessageHeader} Parsed header
+ * @throws {MessageError} If data is invalid or checksum fails
+ *
+ * @example
+ * const header = deserializeHeader(headerBytes);
+ * console.log(header.type, header.messageId);
+ */
+function deserializeHeader(data) {
+  // Validate input type
+  if (!(data instanceof Uint8Array)) {
+    throw MessageError.invalidFormat(null, {
+      reason: 'Data must be a Uint8Array'
+    });
+  }
+
+  // Validate minimum length
+  if (data.length < HEADER_SIZE) {
+    throw MessageError.invalidFormat(null, {
+      reason: 'Data too short for header',
+      expected: HEADER_SIZE,
+      actual: data.length
+    });
+  }
+
+  const headerData = data.slice(0, HEADER_SIZE);
+  const view = new DataView(headerData.buffer, headerData.byteOffset, HEADER_SIZE);
+
+  // Extract checksum from bytes 44-47 (big-endian)
+  const storedChecksum = view.getUint32(44, false);
+
+  // Calculate checksum over bytes 0-43
+  const checksumData = headerData.slice(0, 44);
+  const calculatedChecksum = crc32(checksumData);
+
+  // Verify checksum
+  if (storedChecksum !== calculatedChecksum) {
+    throw MessageError.invalidChecksum(null, {
+      stored: storedChecksum.toString(16),
+      calculated: calculatedChecksum.toString(16)
+    });
+  }
+
+  // Parse header fields
+  const header = new MessageHeader({
+    version: headerData[0],
+    type: headerData[1],
+    flags: headerData[2],
+    hopCount: headerData[3],
+    maxHops: headerData[4],
+    // bytes 5-7 are reserved
+    messageId: headerData.slice(8, 24),
+    timestamp: readUint64BE(view, 24),
+    expiresAt: readUint64BE(view, 32),
+    payloadLength: view.getUint16(40, false),
+    fragmentIndex: headerData[42],
+    fragmentTotal: headerData[43],
+    checksum: storedChecksum
+  });
+
+  return header;
+}
+
+/**
+ * Deserializes a complete message (header + payload) from bytes.
+ * Validates header checksum and payload length.
+ *
+ * @param {Uint8Array} data - Raw message bytes
+ * @returns {Message} Parsed message
+ * @throws {MessageError} If data is invalid
+ *
+ * @example
+ * const message = deserialize(rawBytes);
+ * console.log(message.getContent());
+ */
+function deserialize(data) {
+  // Validate input type
+  if (!(data instanceof Uint8Array)) {
+    throw MessageError.invalidFormat(null, {
+      reason: 'Data must be a Uint8Array'
+    });
+  }
+
+  // Validate minimum length for header
+  if (data.length < HEADER_SIZE) {
+    throw MessageError.invalidFormat(null, {
+      reason: 'Data too short for message',
+      minSize: HEADER_SIZE,
+      actual: data.length
+    });
+  }
+
+  // Parse header first
+  const header = deserializeHeader(data);
+
+  // Validate total message length
+  const expectedLength = HEADER_SIZE + header.payloadLength;
+
+  if (data.length < expectedLength) {
+    throw MessageError.invalidFormat(header.getMessageIdHex(), {
+      reason: 'Incomplete payload',
+      expected: expectedLength,
+      actual: data.length
+    });
+  }
+
+  // Extract payload
+  const payload = data.slice(HEADER_SIZE, HEADER_SIZE + header.payloadLength);
+
+  return new Message(header, payload);
+}
+
+/**
+ * Attempts to deserialize a message, returning null on failure.
+ * Useful when processing potentially malformed data.
+ *
+ * @param {Uint8Array} data - Raw message bytes
+ * @returns {Message|null} Parsed message or null if invalid
+ */
+function tryDeserialize(data) {
+  try {
+    return deserialize(data);
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Deserializes multiple messages from a concatenated buffer.
+ * Stops at first invalid message.
+ *
+ * @param {Uint8Array} data - Buffer containing multiple messages
+ * @returns {Array<Message>} Array of parsed messages
+ */
+function deserializeBatch(data) {
+  if (!(data instanceof Uint8Array)) {
+    throw MessageError.invalidFormat(null, {
+      reason: 'Data must be a Uint8Array'
+    });
+  }
+
+  const messages = [];
+  let offset = 0;
+
+  while (offset < data.length) {
+    // Need at least header size remaining
+    if (data.length - offset < HEADER_SIZE) {
+      break;
+    }
+
+    // Peek at payload length to know full message size
+    const view = new DataView(data.buffer, data.byteOffset + offset, HEADER_SIZE);
+    const payloadLength = view.getUint16(40, false);
+    const messageLength = HEADER_SIZE + payloadLength;
+
+    // Check if we have the complete message
+    if (data.length - offset < messageLength) {
+      break;
+    }
+
+    // Extract and deserialize this message
+    const messageData = data.slice(offset, offset + messageLength);
+
+    try {
+      const message = deserialize(messageData);
+      messages.push(message);
+      offset += messageLength;
+    } catch (error) {
+      // Stop on first error
+      break;
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * Reads a 64-bit unsigned integer in big-endian format.
+ * JavaScript numbers can safely represent integers up to 2^53.
+ *
+ * @param {DataView} view - DataView to read from
+ * @param {number} offset - Byte offset
+ * @returns {number} 64-bit value
+ */
+function readUint64BE(view, offset) {
+  const high = view.getUint32(offset, false);
+  const low = view.getUint32(offset + 4, false);
+  return high * 0x100000000 + low;
+}
+
+/**
+ * Peeks at message type without full deserialization.
+ * Useful for routing decisions.
+ *
+ * @param {Uint8Array} data - Raw message bytes
+ * @returns {number|null} Message type or null if invalid
+ */
+function peekMessageType(data) {
+  if (!(data instanceof Uint8Array) || data.length < 2) {
+    return null;
+  }
+  return data[1];
+}
+
+/**
+ * Peeks at message ID without full deserialization.
+ *
+ * @param {Uint8Array} data - Raw message bytes
+ * @returns {Uint8Array|null} 16-byte message ID or null if invalid
+ */
+function peekMessageId(data) {
+  if (!(data instanceof Uint8Array) || data.length < 24) {
+    return null;
+  }
+  return data.slice(8, 24);
+}
+
+module.exports = {
+  deserialize,
+  deserializeHeader,
+  tryDeserialize,
+  deserializeBatch,
+  peekMessageType,
+  peekMessageId
+};

package/src/protocol/header.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * @fileoverview Message header structure and serialization (48 bytes).
+ * @module protocol/header
+ */
+
+const { crc32 } = require('./crc32');
+const { PROTOCOL_VERSION, MESSAGE_FLAGS, MESH_CONFIG } = require('../constants');
+const { MessageError } = require('../errors');
+
+/**
+ * Header size in bytes.
+ * @constant {number}
+ */
+const HEADER_SIZE = 48;
+
+/**
+ * Message header class representing the 48-byte header structure.
+ * @class MessageHeader
+ */
+class MessageHeader {
+  /**
+   * Creates a new MessageHeader instance.
+   * @param {Object} options - Header options
+   * @param {number} [options.version=1] - Protocol version
+   * @param {number} options.type - Message type from MESSAGE_TYPE
+   * @param {number} [options.flags=0] - Message flags
+   * @param {number} [options.hopCount=0] - Current hop count
+   * @param {number} [options.maxHops=7] - Maximum hops allowed
+   * @param {Uint8Array} options.messageId - 16-byte UUID
+   * @param {number} options.timestamp - Unix timestamp in ms
+   * @param {number} options.expiresAt - Expiration timestamp in ms
+   * @param {number} options.payloadLength - Payload size in bytes
+   * @param {number} [options.fragmentIndex=0] - Fragment index (0-based)
+   * @param {number} [options.fragmentTotal=1] - Total fragments
+   * @param {number} [options.checksum=0] - CRC32 checksum
+   */
+  constructor(options) {
+    this.version = options.version ?? PROTOCOL_VERSION;
+    this.type = options.type;
+    this.flags = options.flags ?? MESSAGE_FLAGS.NONE;
+    this.hopCount = options.hopCount ?? 0;
+    this.maxHops = options.maxHops ?? MESH_CONFIG.MAX_HOPS;
+    this.reserved = new Uint8Array(3);
+    this.messageId = options.messageId;
+    this.timestamp = options.timestamp;
+    this.expiresAt = options.expiresAt;
+    this.payloadLength = options.payloadLength;
+    this.fragmentIndex = options.fragmentIndex ?? 0;
+    this.fragmentTotal = options.fragmentTotal ?? 1;
+    this.checksum = options.checksum ?? 0;
+  }
+
+  /**
+   * Creates a new MessageHeader with generated UUID and timestamps.
+   * @param {Object} options - Header creation options
+   * @param {number} options.type - Message type
+   * @param {number} [options.flags=0] - Message flags
+   * @param {number} [options.maxHops=7] - Maximum hops
+   * @param {number} options.payloadLength - Payload size
+   * @param {number} [options.fragmentIndex=0] - Fragment index
+   * @param {number} [options.fragmentTotal=1] - Total fragments
+   * @param {number} [options.ttlMs] - Time-to-live in ms
+   * @returns {MessageHeader} New header instance
+   */
+  static create(options) {
+    const now = Date.now();
+    const ttl = options.ttlMs ?? MESH_CONFIG.MESSAGE_TTL_MS;
+
+    return new MessageHeader({
+      version: PROTOCOL_VERSION,
+      type: options.type,
+      flags: options.flags ?? MESSAGE_FLAGS.NONE,
+      hopCount: 0,
+      maxHops: options.maxHops ?? MESH_CONFIG.MAX_HOPS,
+      messageId: generateUuid(),
+      timestamp: now,
+      expiresAt: now + ttl,
+      payloadLength: options.payloadLength,
+      fragmentIndex: options.fragmentIndex ?? 0,
+      fragmentTotal: options.fragmentTotal ?? 1,
+      checksum: 0
+    });
+  }
+
+  /**
+   * Deserializes a header from bytes.
+   * @param {Uint8Array} data - 48-byte header data
+   * @returns {MessageHeader} Parsed header
+   * @throws {MessageError} If data is invalid
+   */
+  static fromBytes(data) {
+    if (!(data instanceof Uint8Array) || data.length < HEADER_SIZE) {
+      throw MessageError.invalidFormat(null, { reason: 'Header too small' });
+    }
+
+    const view = new DataView(data.buffer, data.byteOffset, HEADER_SIZE);
+
+    return new MessageHeader({
+      version: data[0],
+      type: data[1],
+      flags: data[2],
+      hopCount: data[3],
+      maxHops: data[4],
+      messageId: data.slice(8, 24),
+      timestamp: readUint64BE(view, 24),
+      expiresAt: readUint64BE(view, 32),
+      payloadLength: view.getUint16(40, false),
+      fragmentIndex: data[42],
+      fragmentTotal: data[43],
+      checksum: view.getUint32(44, false)
+    });
+  }
+
+  /**
+   * Serializes the header to bytes.
+   * @returns {Uint8Array} 48-byte header
+   */
+  toBytes() {
+    return MessageHeader.toBytes(this);
+  }
+
+  /**
+   * Serializes a header to bytes.
+   * @param {MessageHeader} header - Header to serialize
+   * @returns {Uint8Array} 48-byte header
+   */
+  static toBytes(header) {
+    const buffer = new Uint8Array(HEADER_SIZE);
+    const view = new DataView(buffer.buffer);
+
+    buffer[0] = header.version;
+    buffer[1] = header.type;
+    buffer[2] = header.flags;
+    buffer[3] = header.hopCount;
+    buffer[4] = header.maxHops;
+    // bytes 5-7 reserved (zeros)
+    buffer.set(header.messageId, 8);
+    writeUint64BE(view, 24, header.timestamp);
+    writeUint64BE(view, 32, header.expiresAt);
+    view.setUint16(40, header.payloadLength, false);
+    buffer[42] = header.fragmentIndex;
+    buffer[43] = header.fragmentTotal;
+    // Calculate checksum over header without checksum field
+    const checksumData = buffer.slice(0, 44);
+    const checksum = crc32(checksumData);
+    view.setUint32(44, checksum, false);
+    header.checksum = checksum;
+
+    return buffer;
+  }
+
+  /**
+   * Returns the message ID as a hex string.
+   * @returns {string} UUID hex string
+   */
+  getMessageIdHex() {
+    return bytesToHex(this.messageId);
+  }
+}
+
+/**
+ * Generates a random 16-byte UUID.
+ * @returns {Uint8Array} 16-byte UUID
+ */
+function generateUuid() {
+  const uuid = new Uint8Array(16);
+  if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+    globalThis.crypto.getRandomValues(uuid);
+  } else {
+    const nodeCrypto = require('crypto');
+    const randomBuffer = nodeCrypto.randomBytes(16);
+    uuid.set(randomBuffer);
+  }
+  // Set version 4 (random) and variant bits
+  uuid[6] = (uuid[6] & 0x0f) | 0x40;
+  uuid[8] = (uuid[8] & 0x3f) | 0x80;
+  return uuid;
+}
+
+/**
+ * Reads a 64-bit unsigned integer (big-endian) from DataView.
+ * @param {DataView} view - DataView to read from
+ * @param {number} offset - Byte offset
+ * @returns {number} 64-bit value (may lose precision for large values)
+ */
+function readUint64BE(view, offset) {
+  const high = view.getUint32(offset, false);
+  const low = view.getUint32(offset + 4, false);
+  return high * 0x100000000 + low;
+}
+
+/**
+ * Writes a 64-bit unsigned integer (big-endian) to DataView.
+ * @param {DataView} view - DataView to write to
+ * @param {number} offset - Byte offset
+ * @param {number} value - Value to write
+ */
+function writeUint64BE(view, offset, value) {
+  const high = Math.floor(value / 0x100000000);
+  const low = value >>> 0;
+  view.setUint32(offset, high, false);
+  view.setUint32(offset + 4, low, false);
+}
+
+/**
+ * Converts bytes to hex string.
+ * @param {Uint8Array} bytes - Bytes to convert
+ * @returns {string} Hex string
+ */
+function bytesToHex(bytes) {
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+module.exports = {
+  MessageHeader,
+  HEADER_SIZE,
+  generateUuid
+};

package/src/protocol/index.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * @fileoverview Protocol module exports for BLE Mesh Network library.
+ * Provides message serialization, deserialization, and validation.
+ * @module protocol
+ */
+
+const { crc32, verifyCrc32, CRC32_POLYNOMIAL } = require('./crc32');
+const { MessageHeader, HEADER_SIZE, generateUuid } = require('./header');
+const { Message } = require('./message');
+const { serialize, serializeHeader, serializeBatch } = require('./serializer');
+const {
+  deserialize,
+  deserializeHeader,
+  tryDeserialize,
+  deserializeBatch,
+  peekMessageType,
+  peekMessageId
+} = require('./deserializer');
+const {
+  validateMessage,
+  validateHeader,
+  validateChecksum,
+  validateRawMessage,
+  isValidMessageType,
+  isExpired,
+  hasExceededMaxHops
+} = require('./validator');
+
+module.exports = {
+  // CRC32
+  crc32,
+  verifyCrc32,
+  CRC32_POLYNOMIAL,
+
+  // Header
+  MessageHeader,
+  HEADER_SIZE,
+  generateUuid,
+
+  // Message
+  Message,
+
+  // Serialization
+  serialize,
+  serializeHeader,
+  serializeBatch,
+
+  // Deserialization
+  deserialize,
+  deserializeHeader,
+  tryDeserialize,
+  deserializeBatch,
+  peekMessageType,
+  peekMessageId,
+
+  // Validation
+  validateMessage,
+  validateHeader,
+  validateChecksum,
+  validateRawMessage,
+  isValidMessageType,
+  isExpired,
+  hasExceededMaxHops
+};