dsc-itv2-client 1.0.7

package/src/itv2-session.js

@@ -0,0 +1,1069 @@
+/**
+ * ITV2 Session Handler
+ * Based on DSC-TLink reverse engineering
+ *
+ * Packet Structure:
+ * [Integration ID 12 ASCII][0x7E][Frame Content][0x7F]
+ *
+ * Frame Content (with length/CRC framing):
+ * [Length 1-2B][SenderSeq][ReceiverSeq][Command 2B][AppSeq][Payload...][CRC-16 2B]
+ *
+ * Byte Stuffing:
+ * 0x7D → 0x7D 0x00
+ * 0x7E → 0x7D 0x01
+ * 0x7F → 0x7D 0x02
+ */
+
+import { crc16 } from './utils.js';
+import { randomBytes } from 'crypto';
+import {
+  parseType1Initializer,
+  generateType1Initializer,
+  aesEcbEncrypt,
+  aesEcbDecrypt,
+  transformType1KeyString,
+} from './itv2-crypto.js';
+
+// CRC-16 lookup table (CCITT)
+const CRC_TABLE = [
+  0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50A5, 0x60C6, 0x70E7,
+  0x8108, 0x9129, 0xA14A, 0xB16B, 0xC18C, 0xD1AD, 0xE1CE, 0xF1EF,
+  0x1231, 0x0210, 0x3273, 0x2252, 0x52B5, 0x4294, 0x72F7, 0x62D6,
+  0x9339, 0x8318, 0xB37B, 0xA35A, 0xD3BD, 0xC39C, 0xF3FF, 0xE3DE,
+  0x2462, 0x3443, 0x0420, 0x1401, 0x64E6, 0x74C7, 0x44A4, 0x5485,
+  0xA56A, 0xB54B, 0x8528, 0x9509, 0xE5EE, 0xF5CF, 0xC5AC, 0xD58D,
+  0x3653, 0x2672, 0x1611, 0x0630, 0x76D7, 0x66F6, 0x5695, 0x46B4,
+  0xB75B, 0xA77A, 0x9719, 0x8738, 0xF7DF, 0xE7FE, 0xD79D, 0xC7BC,
+  0x48C4, 0x58E5, 0x6886, 0x78A7, 0x0840, 0x1861, 0x2802, 0x3823,
+  0xC9CC, 0xD9ED, 0xE98E, 0xF9AF, 0x8948, 0x9969, 0xA90A, 0xB92B,
+  0x5AF5, 0x4AD4, 0x7AB7, 0x6A96, 0x1A71, 0x0A50, 0x3A33, 0x2A12,
+  0xDBFD, 0xCBDC, 0xFBBF, 0xEB9E, 0x9B79, 0x8B58, 0xBB3B, 0xAB1A,
+  0x6CA6, 0x7C87, 0x4CE4, 0x5CC5, 0x2C22, 0x3C03, 0x0C60, 0x1C41,
+  0xEDAE, 0xFD8F, 0xCDEC, 0xDDCD, 0xAD2A, 0xBD0B, 0x8D68, 0x9D49,
+  0x7E97, 0x6EB6, 0x5ED5, 0x4EF4, 0x3E13, 0x2E32, 0x1E51, 0x0E70,
+  0xFF9F, 0xEFBE, 0xDFDD, 0xCFFC, 0xBF1B, 0xAF3A, 0x9F59, 0x8F78,
+  0x9188, 0x81A9, 0xB1CA, 0xA1EB, 0xD10C, 0xC12D, 0xF14E, 0xE16F,
+  0x1080, 0x00A1, 0x30C2, 0x20E3, 0x5004, 0x4025, 0x7046, 0x6067,
+  0x83B9, 0x9398, 0xA3FB, 0xB3DA, 0xC33D, 0xD31C, 0xE37F, 0xF35E,
+  0x02B1, 0x1290, 0x22F3, 0x32D2, 0x4235, 0x5214, 0x6277, 0x7256,
+  0xB5EA, 0xA5CB, 0x95A8, 0x8589, 0xF56E, 0xE54F, 0xD52C, 0xC50D,
+  0x34E2, 0x24C3, 0x14A0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405,
+  0xA7DB, 0xB7FA, 0x8799, 0x97B8, 0xE75F, 0xF77E, 0xC71D, 0xD73C,
+  0x26D3, 0x36F2, 0x0691, 0x16B0, 0x6657, 0x7676, 0x4615, 0x5634,
+  0xD94C, 0xC96D, 0xF90E, 0xE92F, 0x99C8, 0x89E9, 0xB98A, 0xA9AB,
+  0x5844, 0x4865, 0x7806, 0x6827, 0x18C0, 0x08E1, 0x3882, 0x28A3,
+  0xCB7D, 0xDB5C, 0xEB3F, 0xFB1E, 0x8BF9, 0x9BD8, 0xABBB, 0xBB9A,
+  0x4A75, 0x5A54, 0x6A37, 0x7A16, 0x0AF1, 0x1AD0, 0x2AB3, 0x3A92,
+  0xFD2E, 0xED0F, 0xDD6C, 0xCD4D, 0xBDAA, 0xAD8B, 0x9DE8, 0x8DC9,
+  0x7C26, 0x6C07, 0x5C64, 0x4C45, 0x3CA2, 0x2C83, 0x1CE0, 0x0CC1,
+  0xEF1F, 0xFF3E, 0xCF5D, 0xDF7C, 0xAF9B, 0xBFBA, 0x8FD9, 0x9FF8,
+  0x6E17, 0x7E36, 0x4E55, 0x5E74, 0x2E93, 0x3EB2, 0x0ED1, 0x1EF0,
+];
+
+// Command codes
+export const CMD = {
+  SIMPLE_ACK: 0x0000,
+  // Zone/Lifestyle notifications (0x02xx)
+  LIFESTYLE_ZONE_STATUS: 0x0210,
+  TIME_DATE_BROADCAST: 0x0220,
+  // Access Level commands (0x04xx)
+  ACCESS_LEVEL_ENTER: 0x0400,
+  ACCESS_LEVEL_EXIT: 0x0401,
+  ACCESS_LEVEL_LEAD_INOUT: 0x0402,
+  // Error/Response codes (0x05xx)
+  COMMAND_ERROR: 0x0501,
+  COMMAND_RESPONSE: 0x0502,
+  // Session commands (0x06xx)
+  POLL: 0x0600,
+  OPEN_SESSION: 0x060A,
+  END_SESSION: 0x060B,
+  BUFFER_SIZES: 0x060C,
+  SOFTWARE_VERSION: 0x060D,
+  REQUEST_ACCESS: 0x060E,
+  SYSTEM_CAPABILITIES: 0x0613,
+  PANEL_STATUS: 0x0614,
+  // Configuration commands (0x07xx)
+  CONFIG_ENTER: 0x0704,
+  CONFIG_ACCESS_CODE_WRAPPER: 0x0703,
+  // Module Status commands
+  STATUS_REQUEST: 0x0800,
+  GLOBAL_STATUS: 0x0810,
+  ZONE_STATUS: 0x0811,
+  PARTITION_STATUS: 0x0812,
+  ZONE_BYPASS_STATUS: 0x0813,
+  SYSTEM_TROUBLE_STATUS: 0x0814,
+  ALARM_MEMORY_INFO: 0x0815,
+  BUS_STATUS: 0x0816,
+  TROUBLE_DETAIL: 0x0817,
+  DOOR_CHIME_STATUS: 0x0819,
+  // Module Control commands
+  PARTITION_ARM: 0x0900,
+  PARTITION_DISARM: 0x0901,
+  COMMAND_OUTPUT: 0x0902,
+  // Notifications (unsolicited from panel)
+  NOTIFICATION_ARMING: 0x0232,
+  NOTIFICATION_PARTITION_READY: 0x0239,
+  NOTIFICATION_PARTITION_TROUBLE: 0x023F,
+  ZONE_ALARM_STATUS: 0x0840,
+  // General notification event
+  GENERAL_NOTIFICATION: 0x0230,
+  DATA_UPDATE_NOTIFICATION: 0x0231,
+};
+
+export const CMD_NAMES = Object.fromEntries(
+  Object.entries(CMD).map(([k, v]) => [v, k])
+);
+
+/**
+ * Calculate CRC-16-CCITT using lookup table
+ */
+function calcCrc16(data) {
+  let crc = 0xFFFF;
+  for (const b of data) {
+    crc = ((crc << 8) ^ CRC_TABLE[(crc >> 8) ^ b]) & 0xFFFF;
+  }
+  return crc;
+}
+
+/**
+ * Byte stuffing for transmission
+ */
+function stuffBytes(data) {
+  const result = [];
+  for (const b of data) {
+    switch (b) {
+      case 0x7D:
+        result.push(0x7D, 0x00);
+        break;
+      case 0x7E:
+        result.push(0x7D, 0x01);
+        break;
+      case 0x7F:
+        result.push(0x7D, 0x02);
+        break;
+      default:
+        result.push(b);
+    }
+  }
+  return Buffer.from(result);
+}
+
+/**
+ * Byte unstuffing for reception
+ */
+function unstuffBytes(data) {
+  const result = [];
+  let i = 0;
+  while (i < data.length) {
+    if (data[i] === 0x7D && i + 1 < data.length) {
+      switch (data[i + 1]) {
+        case 0x00:
+          result.push(0x7D);
+          break;
+        case 0x01:
+          result.push(0x7E);
+          break;
+        case 0x02:
+          result.push(0x7F);
+          break;
+        default:
+          throw new Error(`Invalid escape sequence: 0x7D 0x${data[i + 1].toString(16)}`);
+      }
+      i += 2;
+    } else {
+      result.push(data[i]);
+      i++;
+    }
+  }
+  return Buffer.from(result);
+}
+
+/**
+ * Add length and CRC framing to message
+ */
+function addFraming(message) {
+  // Length = message + CRC (does NOT include the length byte itself)
+  const length = message.length + 2;
+  let framed;
+
+  if (length > 0x7F) {
+    // Two-byte length encoding
+    framed = Buffer.alloc(2 + message.length + 2);
+    framed[0] = (length >> 8) | 0x80;
+    framed[1] = length & 0xFF;
+    message.copy(framed, 2);
+  } else {
+    // Single-byte length encoding
+    framed = Buffer.alloc(1 + message.length + 2);
+    framed[0] = length;
+    message.copy(framed, 1);
+  }
+
+  // Calculate CRC on length + message
+  const crcData = framed.slice(0, -2);
+  const crc = calcCrc16(crcData);
+  framed.writeUInt16BE(crc, framed.length - 2);
+
+  return framed;
+}
+
+/**
+ * Remove length and CRC framing from message
+ */
+function removeFraming(data) {
+  let offset = 0;
+  let length;
+
+  // Check if two-byte length
+  if (data[0] & 0x80) {
+    length = ((data[0] & 0x7F) << 8) | data[1];
+    offset = 2;
+  } else {
+    length = data[0];
+    offset = 1;
+  }
+
+  // Extract message and CRC
+  const message = data.slice(offset, offset + length - 2);
+  const receivedCrc = data.readUInt16BE(offset + length - 2);
+
+  // Verify CRC
+  const crcData = data.slice(0, offset + length - 2);
+  const calculatedCrc = calcCrc16(crcData);
+
+  if (receivedCrc !== calculatedCrc) {
+    throw new Error(`CRC mismatch: received 0x${receivedCrc.toString(16)}, calculated 0x${calculatedCrc.toString(16)}`);
+  }
+
+  return message;
+}
+
+/**
+ * Parse ITv2 header from message
+ */
+function parseHeader(message) {
+  const header = {
+    senderSequence: message[0],
+    receiverSequence: message[1],
+    command: null,
+    appSequence: null,
+    commandData: null,
+  };
+
+  if (message.length > 2) {
+    header.command = message.readUInt16BE(2);
+  }
+  if (message.length > 4) {
+    header.appSequence = message[4];
+  }
+  if (message.length > 5) {
+    header.commandData = message.slice(5);
+  }
+
+  return header;
+}
+
+/**
+ * Build ITv2 header message
+ */
+function buildHeader(senderSeq, receiverSeq, command = null, appSeq = null, commandData = null) {
+  const parts = [Buffer.from([senderSeq, receiverSeq])];
+
+  if (command !== null) {
+    const cmdBuf = Buffer.alloc(2);
+    cmdBuf.writeUInt16BE(command);
+    parts.push(cmdBuf);
+  }
+
+  if (appSeq !== null) {
+    parts.push(Buffer.from([appSeq]));
+  }
+
+  if (commandData !== null) {
+    parts.push(commandData);
+  }
+
+  return Buffer.concat(parts);
+}
+
+/**
+ * ITV2 Session class
+ *
+ * Key terminology (from SDK analysis):
+ * - Integration ID: 12-digit identifier from panel [422], used in packet header
+ * - Access Code: 8-digit code from panel [423] for Type 1, or 32-hex from [700] for Type 2
+ *
+ * Key derivation:
+ * - Type 1: Uses Access Code (8 digits) → ASCII bytes repeated twice = 16 bytes
+ * - Type 2: Uses Access Code (32 hex digits) → 16 bytes directly
+ */
+export class ITv2Session {
+  constructor(integrationId, accessCode, log = console.log) {
+    this.integrationId = integrationId;      // 12-digit ID for packet header
+    this.accessCode = accessCode;            // 8-digit (Type 1) or 32-hex (Type 2) for encryption
+    this.integrationAccessCode = accessCode; // Alias for compatibility
+    this.log = log;
+
+    // Sequence tracking
+    this.localSequence = 0;   // Our sequence number
+    this.remoteSequence = 0;  // Panel's sequence number
+    this.appSequence = 0;
+
+    // Encryption state
+    this.sendAesKey = null;
+    this.receiveAesKey = null;
+    this.sendAesActive = false;
+    this.receiveAesActive = false;
+
+    // Session state
+    this.state = 'DISCONNECTED';
+    this.remoteOpenSession = null;
+  }
+
+  /**
+   * Enable AES encryption for sending
+   */
+  enableSendAes(key) {
+    this.sendAesKey = key;
+    this.sendAesActive = true;
+    this.log(`[Session] Send AES enabled: ${key.toString('hex')}`);
+  }
+
+  /**
+   * Enable AES decryption for receiving
+   */
+  enableReceiveAes(key) {
+    this.receiveAesKey = key;
+    this.receiveAesActive = true;
+    this.log(`[Session] Receive AES enabled: ${key.toString('hex')}`);
+  }
+
+  /**
+   * Disable all AES encryption/decryption (for session reset)
+   */
+  disableAes() {
+    this.sendAesKey = null;
+    this.sendAesActive = false;
+    this.receiveAesKey = null;
+    this.receiveAesActive = false;
+    this.encryptionType = 0;
+    this.log(`[Session] AES disabled (session reset)`);
+  }
+
+  /**
+   * Build a complete packet ready for transmission
+   *
+   * Encryption order (must match parsePacket):
+   * TX: message → framing (add length/CRC) → encrypt → byte stuff
+   * RX: byte unstuff → decrypt → remove framing (verify CRC) → message
+   */
+  buildPacket(message) {
+    // Add length/CRC framing FIRST
+    let framed = addFraming(message);
+
+    // Encrypt the FRAMED data (including length byte and CRC) if enabled
+    if (this.sendAesActive) {
+      this.log(`[Session] Pre-encrypt framed: ${framed.toString('hex')}`);
+      framed = aesEcbEncrypt(this.sendAesKey, framed);
+      this.log(`[Session] Encrypted framed: ${framed.toString('hex')}`);
+    }
+
+    // Byte stuff the payload
+    const stuffedPayload = stuffBytes(framed);
+
+    // Build full packet WITHOUT integration ID
+    // The panel sends WITH integration ID, but SDK sends WITHOUT it
+    return Buffer.concat([
+      Buffer.from([0x7E]),
+      stuffedPayload,
+      Buffer.from([0x7F]),
+    ]);
+  }
+
+  /**
+   * Parse a received packet
+   */
+  parsePacket(data) {
+    // Find frame markers
+    const startIdx = data.indexOf(0x7E);
+    const endIdx = data.lastIndexOf(0x7F);
+
+    if (startIdx === -1 || endIdx === -1 || startIdx >= endIdx) {
+      throw new Error('Invalid packet: missing frame markers');
+    }
+
+    // Extract and unstuff header
+    const stuffedHeader = data.slice(0, startIdx);
+    const header = unstuffBytes(stuffedHeader);
+
+    // Extract and unstuff payload
+    const stuffedPayload = data.slice(startIdx + 1, endIdx);
+    let framedPayload = unstuffBytes(stuffedPayload);
+
+    // For encrypted packets, the ENTIRE framed payload (including length byte) is encrypted
+    // Decrypt BEFORE removing framing if AES is active and payload is block-aligned
+    if (this.receiveAesActive && framedPayload.length >= 16 && framedPayload.length % 16 === 0) {
+      this.log(`[Session] Decrypting ${framedPayload.length} byte payload: ${framedPayload.toString('hex')}`);
+      framedPayload = aesEcbDecrypt(this.receiveAesKey, framedPayload);
+      this.log(`[Session] Decrypted: ${framedPayload.toString('hex')}`);
+    } else if (!this.receiveAesActive && framedPayload.length >= 16 && framedPayload.length % 16 === 0 && this.accessCode) {
+      // Panel may send encrypted data before handshake completes, using Access Code-derived key
+      // Try to decrypt with the pre-shared key if payload looks encrypted (16-byte aligned)
+      this.log(`[Session] Attempting pre-handshake decryption with Access Code key`);
+      this.log(`[Session] Encrypted payload: ${framedPayload.toString('hex')}`);
+
+      try {
+        const preSharedKey = transformType1KeyString(this.accessCode, 'ascii');
+        this.log(`[Session] Pre-shared key: ${preSharedKey.toString('hex')}`);
+
+        const decrypted = aesEcbDecrypt(preSharedKey, framedPayload);
+        this.log(`[Session] Decrypted: ${decrypted.toString('hex')}`);
+
+        // Validate: first byte should be a reasonable length (< 128 for single-byte length)
+        // or have high bit set for two-byte length but result in valid range
+        const firstByte = decrypted[0];
+        const isValidLength = (firstByte & 0x80) === 0
+          ? (firstByte > 0 && firstByte <= framedPayload.length)
+          : ((((firstByte & 0x7F) << 8) | decrypted[1]) <= framedPayload.length);
+
+        if (isValidLength) {
+          this.log(`[Session] Pre-handshake decryption successful (valid length byte: 0x${firstByte.toString(16)})`);
+          framedPayload = decrypted;
+        } else {
+          this.log(`[Session] Decrypted data has invalid length byte 0x${firstByte.toString(16)}, using original payload`);
+        }
+      } catch (err) {
+        this.log(`[Session] Pre-handshake decryption failed: ${err.message}`);
+      }
+    }
+
+    // Remove framing (length/CRC)
+    let message = removeFraming(framedPayload);
+
+    // Parse header
+    const parsed = parseHeader(message);
+    parsed.integrationId = header.toString('ascii');
+    parsed.raw = data;
+
+    // Update remote sequence
+    this.remoteSequence = parsed.senderSequence;
+
+    return parsed;
+  }
+
+  /**
+   * Build SimpleAck response
+   * SDK shows ACK format: [length][our_sender_seq][remote_seq_being_acked][CRC]
+   * The sender sequence is our current sequence (doesn't increment for ACK)
+   * The receiver sequence is the remote sequence being acknowledged
+   */
+  buildSimpleAck() {
+    // Use our current localSequence as sender (SDK shows this, not always 0)
+    const message = buildHeader(this.localSequence, this.remoteSequence);
+    return this.buildPacket(message);
+  }
+
+  /**
+   * Build command message
+   */
+  buildCommand(command, commandData = null) {
+    this.localSequence = (this.localSequence + 1) & 0xFF;
+    this.appSequence = (this.appSequence + 1) & 0xFF;
+
+    const message = buildHeader(
+      this.localSequence,
+      this.remoteSequence,
+      command,
+      this.appSequence,
+      commandData
+    );
+
+    return this.buildPacket(message);
+  }
+
+  /**
+   * Build COMMAND_RESPONSE with success code
+   */
+  buildCommandResponse(responseCode = 0x00) {
+    return this.buildCommand(CMD.COMMAND_RESPONSE, Buffer.from([responseCode]));
+  }
+
+  /**
+   * Build COMMAND_RESPONSE echoing the app sequence from the request
+   * This matches the SDK behavior where COMMAND_RESPONSE payload is [echoed_app_seq, response_code]
+   *
+   * @param {number} appSeq - App sequence to echo from the request
+   * @param {number} responseCode - Response code (0x00 = success)
+   */
+  buildCommandResponseWithAppSeq(appSeq, responseCode = 0x00) {
+    this.localSequence = (this.localSequence + 1) & 0xFF;
+
+    // SDK shows COMMAND_RESPONSE has NO app sequence of its own,
+    // just [echoed_first_byte, response_code] as payload
+    const message = buildHeader(
+      this.localSequence,
+      this.remoteSequence,
+      CMD.COMMAND_RESPONSE,
+      null,  // No app sequence in COMMAND_RESPONSE itself
+      Buffer.from([appSeq, responseCode])
+    );
+
+    return this.buildPacket(message);
+  }
+
+  /**
+   * Build OPEN_SESSION message (echo back panel's session info)
+   * NOTE: OPEN_SESSION does NOT have an app sequence byte - it goes directly to payload
+   */
+  buildOpenSessionResponse(openSessionData) {
+    this.localSequence = (this.localSequence + 1) & 0xFF;
+
+    // OPEN_SESSION format: [sender][receiver][cmd 2B][payload...] - NO app sequence!
+    const message = buildHeader(
+      this.localSequence,
+      this.remoteSequence,
+      CMD.OPEN_SESSION,
+      null,  // NO app sequence for OPEN_SESSION
+      openSessionData
+    );
+
+    return this.buildPacket(message);
+  }
+
+  /**
+   * Build REQUEST_ACCESS message for Type 1 encryption
+   */
+  buildRequestAccess() {
+    const { initializer, localKey } = generateType1Initializer(this.integrationAccessCode);
+    this.pendingReceiveKey = localKey;
+    // Payload format: [length byte][initializer data]
+    const payload = Buffer.concat([Buffer.from([initializer.length]), initializer]);
+    return this.buildCommand(CMD.REQUEST_ACCESS, payload);
+  }
+
+  /**
+   * Handle incoming OPEN_SESSION
+   */
+  handleOpenSession(header) {
+    const data = header.commandData;
+    if (!data || data.length < 13) {
+      this.log(`[Session] OPEN_SESSION payload too short: ${data?.length || 0} bytes`);
+      return null;
+    }
+
+    // OpenSession structure based on DSC-TLink:
+    // [DeviceType 1B][DeviceID 2B][FirmwareVer 2B][ProtocolVer 2B][TxBuf 2B][RxBuf 2B][Unknown 2B][EncType 1B]
+    // Total: 14 bytes minimum
+    const openSession = {
+      deviceType: data[0],
+      deviceId: data.slice(1, 3),
+      firmwareVersion: data.slice(3, 5),
+      protocolVersion: data.slice(5, 7),
+      txBufferSize: data.readUInt16BE(7),
+      rxBufferSize: data.readUInt16BE(9),
+      unknown: data.slice(11, 13),
+      encryptionType: data.length > 13 ? data[13] : 1,  // Default to Type 1
+    };
+
+    this.log(`[Session] OPEN_SESSION received:`);
+    this.log(`  Device Type: ${openSession.deviceType}`);
+    this.log(`  Device ID: ${openSession.deviceId.toString('hex')}`);
+    this.log(`  Firmware: ${openSession.firmwareVersion.toString('hex')}`);
+    this.log(`  Protocol: ${openSession.protocolVersion.toString('hex')}`);
+    this.log(`  TX Buffer: ${openSession.txBufferSize}`);
+    this.log(`  RX Buffer: ${openSession.rxBufferSize}`);
+    this.log(`  Encryption Type: ${openSession.encryptionType}`);
+
+    this.remoteOpenSession = openSession;
+    return openSession;
+  }
+
+  /**
+   * Handle incoming REQUEST_ACCESS
+   */
+  handleRequestAccess(header) {
+    const data = header.commandData;
+    if (!data) {
+      this.log(`[Session] REQUEST_ACCESS: no payload`);
+      return null;
+    }
+
+    // Payload format: [length byte][initializer data]
+    const length = data[0];
+    const initializer = data.slice(1, 1 + length);
+
+    this.log(`[Session] REQUEST_ACCESS: ${length} byte initializer`);
+    this.log(`  Initializer: ${initializer.toString('hex')}`);
+
+    if (length === 48) {
+      // Type 1 encryption - try both Access Code and Integration ID for key derivation
+      try {
+        const remoteKey = parseType1Initializer(this.accessCode, initializer, this.integrationId);
+        this.log(`[Session] Type 1 remote key derived: ${remoteKey.toString('hex')}`);
+        return { type: 1, key: remoteKey };
+      } catch (err) {
+        this.log(`[Session] Type 1 key derivation failed: ${err.message}`);
+        return null;
+      }
+    } else if (length === 16) {
+      // Type 2 encryption
+      try {
+        // For Type 2, the access code should be 32 hex chars (16 bytes)
+        // If we have an 8-digit code, expand it: "12345678" -> "12345678123456781234567812345678"
+        let accessCode32 = this.accessCode;
+        if (accessCode32.length === 8) {
+          accessCode32 = accessCode32 + accessCode32 + accessCode32 + accessCode32;
+        }
+
+        if (accessCode32.length !== 32) {
+          this.log(`[Session] Type 2 requires 32-digit access code, got ${accessCode32.length}`);
+          return null;
+        }
+
+        // Type 2: AES-ECB encrypt the initializer with the access code
+        // The result is the key for encrypting messages TO the panel
+        const key = Buffer.from(accessCode32, 'hex');
+        const remoteKey = aesEcbEncrypt(key, initializer);
+
+        this.log(`[Session] Type 2 remote key derived: ${remoteKey.toString('hex')}`);
+        return { type: 2, key: remoteKey };
+      } catch (err) {
+        this.log(`[Session] Type 2 key derivation failed: ${err.message}`);
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Build REQUEST_ACCESS message for Type 1 encryption (48-byte initializer)
+   * Uses the 48-byte format: [16 check bytes][32 ciphertext]
+   *
+   * IMPORTANT: Type 1 key derivation uses Integration ID (first 8 digits),
+   * interpreted as hex and repeated 4 times. NOT ASCII encoding!
+   * Example: "250228754876" → "25022875" → hex bytes 0x25,0x02,0x28,0x75 × 4
+   *
+   * NOTE: Based on SDK analysis, frames remain PLAINTEXT. The initializer payload
+   * contains internally encrypted data.
+   */
+  buildRequestAccessType1() {
+    // SDK analysis shows ASYMMETRIC key usage:
+    // - Panel encrypts with Integration ID key (Type1InitDeviceKey)
+    // - SDK encrypts with Access Code key (Type1InitServerKey)
+    // - Panel decrypts incoming with Access Code key
+    //
+    // Key derivation: CHexHelper::ToBytes converts hex string to bytes, repeated to 16 bytes
+    // For "28754876" → [0x23, 0x42, 0x53, 0x52] × 4 = 16 bytes
+    const { initializer, localKey } = generateType1Initializer(this.accessCode, this.integrationId, 'hex');
+
+    // The localKey is our RECEIVE key - panel will encrypt responses with it
+    this.pendingReceiveKey = localKey;
+    this.encryptionType = 1;
+
+    this.log(`[Session] Type 1 REQUEST_ACCESS: 48-byte initializer`);
+    this.log(`[Session] Using access code: ${this.accessCode} (hex method)`);
+    this.log(`[Session] Initializer: ${initializer.toString('hex')}`);
+    this.log(`[Session] Pending receive key: ${localKey.toString('hex')}`);
+
+    // Payload format: [length byte (0x30=48)][48-byte initializer]
+    const commandData = Buffer.concat([Buffer.from([initializer.length]), initializer]);
+
+    // Increment local sequence for this command
+    this.localSequence = (this.localSequence + 1) & 0xFF;
+
+    // SDK trace shows REQUEST_ACCESS uses appSeq = 0x02 (hardcoded)
+    // SDK packet: 38 04 02 06 0E 02 30 22 85 ...
+    // The 0x02 after command 06 0E is the appSeq
+    const appSeq = 0x02;
+    this.appSequence = appSeq; // Keep internal state synchronized
+
+    this.log(`[Session] REQUEST_ACCESS using localSeq=${this.localSequence}, appSeq=${appSeq}`);
+
+    const message = buildHeader(
+      this.localSequence,
+      this.remoteSequence,
+      CMD.REQUEST_ACCESS,
+      appSeq,
+      commandData
+    );
+
+    return this.buildPacket(message);
+  }
+
+  /**
+   * Build a packet WITHOUT AES encryption (for REQUEST_ACCESS)
+   */
+  buildPacketUnencrypted(message) {
+    // Add length/CRC framing
+    const framed = addFraming(message);
+
+    // Byte stuff
+    const stuffedHeader = stuffBytes(Buffer.from(this.integrationId, 'ascii'));
+    const stuffedPayload = stuffBytes(framed);
+
+    // Build full packet (no encryption)
+    return Buffer.concat([
+      stuffedHeader,
+      Buffer.from([0x7E]),
+      stuffedPayload,
+      Buffer.from([0x7F]),
+    ]);
+  }
+
+  /**
+   * Build REQUEST_ACCESS message for Type 2 encryption
+   * @param {string} masterCode - Optional master code to include in payload
+   */
+  buildRequestAccessType2(masterCode = null) {
+    // Generate 16 random bytes as our initializer
+    const initializer = randomBytes(16);
+
+    // Derive our receive key using same transform
+    let accessCode32 = this.integrationAccessCode;
+    if (accessCode32.length === 8) {
+      accessCode32 = accessCode32 + accessCode32 + accessCode32 + accessCode32;
+    }
+    const key = Buffer.from(accessCode32, 'hex');
+    this.pendingReceiveKey = aesEcbEncrypt(key, initializer);
+
+    // Build payload with initializer
+    let payload;
+    if (masterCode) {
+      // Include master code in BCD format after initializer
+      // "5555" -> [0x55, 0x55]
+      const codeStr = masterCode.toString();
+      const codeBytes = Buffer.alloc(3, 0xFF);
+      for (let i = 0; i < codeStr.length; i += 2) {
+        const high = parseInt(codeStr[i], 10);
+        const low = i + 1 < codeStr.length ? parseInt(codeStr[i + 1], 10) : 0x0F;
+        codeBytes[Math.floor(i / 2)] = (high << 4) | low;
+      }
+
+      // Payload format: [length byte][initializer data][code length][code bytes]
+      payload = Buffer.concat([
+        Buffer.from([initializer.length]),
+        initializer,
+        Buffer.from([codeStr.length]),
+        codeBytes
+      ]);
+      this.log(`[Session] REQUEST_ACCESS with master code: ${masterCode}`);
+    } else {
+      // Payload format: [length byte][initializer data]
+      payload = Buffer.concat([Buffer.from([initializer.length]), initializer]);
+    }
+
+    return this.buildCommand(CMD.REQUEST_ACCESS, payload);
+  }
+
+  /**
+   * Build status request command
+   * @param {number} statusType - Type of status to request:
+   *   0x10 = Global Status (0x0810)
+   *   0x11 = Zone Status (0x0811)
+   *   0x12 = Partition Status (0x0812)
+   *   0x13 = Zone Bypass Status (0x0813)
+   *   0x14 = System Trouble Status (0x0814)
+   *   0x15 = Alarm Memory Info (0x0815)
+   *   0x16 = Bus Status (0x0816)
+   *   0x17 = Trouble Detail (0x0817)
+   *   0x19 = Door Chime Status (0x0819)
+   * @param {number} partitionOrZone - Partition or zone number (0 = all)
+   */
+  buildStatusRequest(statusType, partitionOrZone = 0) {
+    // Payload: [status type byte][partition/zone number]
+    const payload = Buffer.from([statusType, partitionOrZone]);
+    return this.buildCommand(CMD.STATUS_REQUEST, payload);
+  }
+
+  /**
+   * Build global status request
+   */
+  buildGlobalStatusRequest() {
+    // Send GLOBAL_STATUS (0x0810) command directly, not wrapped in STATUS_REQUEST
+    return this.buildCommand(CMD.GLOBAL_STATUS);
+  }
+
+  /**
+   * Build zone status request
+   * @param {number} zone - Zone number (0 = all zones)
+   */
+  buildZoneStatusRequest(zone = 0) {
+    // Send ZONE_STATUS (0x0811) command directly with zone number
+    const payload = zone > 0 ? Buffer.from([zone]) : Buffer.alloc(0);
+    return this.buildCommand(CMD.ZONE_STATUS, payload);
+  }
+
+  /**
+   * Build partition status request
+   * @param {number} partition - Partition number (0 = all partitions)
+   */
+  buildPartitionStatusRequest(partition = 0) {
+    // Send PARTITION_STATUS (0x0812) command directly with partition number
+    const payload = partition > 0 ? Buffer.from([partition]) : Buffer.alloc(0);
+    return this.buildCommand(CMD.PARTITION_STATUS, payload);
+  }
+
+  /**
+   * Build zone bypass status request
+   * @param {number} zone - Zone number (0 = all zones)
+   */
+  buildZoneBypassStatusRequest(zone = 0) {
+    return this.buildStatusRequest(0x13, zone);
+  }
+
+  /**
+   * Build system trouble status request
+   */
+  buildTroubleStatusRequest() {
+    return this.buildStatusRequest(0x14, 0);
+  }
+
+  /**
+   * Build ACCESS_LEVEL_ENTER command to authenticate with access code
+   * @param {string} accessCode - The access code (e.g., "5555" for master code)
+   * @param {number} partition - Partition number (0 = all partitions)
+   * @param {number} accessLevel - Access level (0=User, 1=Installer, 2=Master)
+   * @param {string} format - 'ascii', 'bcd', or 'binary' - how to encode the code
+   */
+  buildAccessLevelEnter(accessCode, partition = 1, accessLevel = 0, format = 'bcd') {
+    const codeStr = accessCode.toString();
+    let codeBytes;
+
+    if (format === 'bcd') {
+      // BCD encoding: each digit as a nibble, pairs of digits per byte
+      // "5555" -> [0x55, 0x55, 0xFF, 0xFF] (FF = unused)
+      codeBytes = Buffer.alloc(3, 0xFF);  // 6 digits max = 3 bytes, unused = 0xFF
+      for (let i = 0; i < codeStr.length; i += 2) {
+        const high = parseInt(codeStr[i], 10);
+        const low = i + 1 < codeStr.length ? parseInt(codeStr[i + 1], 10) : 0x0F;
+        codeBytes[Math.floor(i / 2)] = (high << 4) | low;
+      }
+    } else if (format === 'ascii') {
+      // ASCII encoding: each digit as its ASCII code
+      codeBytes = Buffer.alloc(6, 0);
+      for (let i = 0; i < Math.min(codeStr.length, 6); i++) {
+        codeBytes[i] = codeStr.charCodeAt(i);
+      }
+    } else {
+      // Binary encoding: each digit as its numeric value
+      codeBytes = Buffer.alloc(6, 0xFF);
+      for (let i = 0; i < Math.min(codeStr.length, 6); i++) {
+        codeBytes[i] = parseInt(codeStr[i], 10);
+      }
+    }
+
+    // Payload format: [partition][access level][code length][code bytes...]
+    const payload = Buffer.concat([
+      Buffer.from([partition, accessLevel, codeStr.length]),
+      codeBytes
+    ]);
+
+    this.log(`[Session] ACCESS_LEVEL_ENTER: partition=${partition}, level=${accessLevel}, code=${codeStr}, format=${format}`);
+    this.log(`[Session] Payload: ${payload.toString('hex')}`);
+
+    return this.buildCommand(CMD.ACCESS_LEVEL_ENTER, payload);
+  }
+
+  /**
+   * Build ACCESS_LEVEL_EXIT command to de-authenticate
+   * @param {number} partition - Partition number
+   */
+  buildAccessLevelExit(partition = 1) {
+    const payload = Buffer.from([partition]);
+    return this.buildCommand(CMD.ACCESS_LEVEL_EXIT, payload);
+  }
+
+  /**
+   * Build POLL command for keepalive
+   */
+  buildPoll() {
+    return this.buildCommand(CMD.POLL);
+  }
+
+  /**
+   * Build END_SESSION command to gracefully close the session
+   */
+  buildEndSession() {
+    return this.buildCommand(CMD.END_SESSION);
+  }
+
+  /**
+   * Build SYSTEM_CAPABILITIES request
+   */
+  buildSystemCapabilitiesRequest() {
+    return this.buildCommand(CMD.SYSTEM_CAPABILITIES);
+  }
+
+  /**
+   * Parse partition status response
+   * @param {Buffer} data - Payload from PARTITION_STATUS response
+   */
+  parsePartitionStatus(data) {
+    if (!data || data.length < 2) {
+      return null;
+    }
+
+    const partition = data[0];
+    const statusByte = data[1];
+
+    // Status byte bit meanings (based on DSC protocol):
+    const status = {
+      partition,
+      armed: !!(statusByte & 0x01),        // Bit 0: Armed
+      stayArmed: !!(statusByte & 0x02),    // Bit 1: Stay Armed
+      awayArmed: !!(statusByte & 0x04),    // Bit 2: Away Armed
+      alarm: !!(statusByte & 0x08),        // Bit 3: Alarm
+      trouble: !!(statusByte & 0x10),      // Bit 4: Trouble
+      ready: !!(statusByte & 0x20),        // Bit 5: Ready
+      exitDelay: !!(statusByte & 0x40),    // Bit 6: Exit Delay
+      entryDelay: !!(statusByte & 0x80),   // Bit 7: Entry Delay
+      rawStatus: statusByte,
+    };
+
+    // Additional bytes may contain more info
+    if (data.length > 2) {
+      status.additionalData = data.slice(2);
+    }
+
+    return status;
+  }
+
+  /**
+   * Parse zone status response
+   * @param {Buffer} data - Payload from ZONE_STATUS response
+   */
+  parseZoneStatus(data) {
+    if (!data || data.length < 2) {
+      return null;
+    }
+
+    const zone = data[0];
+    const statusByte = data[1];
+
+    // Zone status bit meanings:
+    const status = {
+      zone,
+      open: !!(statusByte & 0x01),         // Bit 0: Zone Open
+      tamper: !!(statusByte & 0x02),       // Bit 1: Tamper
+      fault: !!(statusByte & 0x04),        // Bit 2: Fault
+      lowBattery: !!(statusByte & 0x08),   // Bit 3: Low Battery
+      supervision: !!(statusByte & 0x10),  // Bit 4: Supervision Loss
+      alarm: !!(statusByte & 0x20),        // Bit 5: In Alarm
+      bypassed: !!(statusByte & 0x40),     // Bit 6: Bypassed
+      armed: !!(statusByte & 0x80),        // Bit 7: Armed
+      rawStatus: statusByte,
+    };
+
+    // Additional bytes may contain zone type, etc.
+    if (data.length > 2) {
+      status.additionalData = data.slice(2);
+    }
+
+    return status;
+  }
+
+  /**
+   * Parse global status response
+   * @param {Buffer} data - Payload from GLOBAL_STATUS response
+   */
+  parseGlobalStatus(data) {
+    if (!data || data.length < 1) {
+      return null;
+    }
+
+    return {
+      rawData: data,
+      // Global status typically contains system-wide flags
+      // Exact format depends on panel model
+    };
+  }
+
+  // ============ Arm/Disarm Commands ============
+
+  /**
+   * Build PARTITION_ARM command
+   * @param {number} partition - Partition number (1-8)
+   * @param {number} armMode - Arming mode:
+   *   0 = Stay (perimeter only)
+   *   1 = Away (full arm)
+   *   2 = No Entry Delay
+   *   3 = Force Arm (bypass open zones)
+   * @param {string} accessCode - Master/user code (e.g., "5555")
+   */
+  buildPartitionArm(partition, armMode, accessCode) {
+    const codeStr = accessCode.toString();
+
+    // Payload format based on SDK decompiled code:
+    // [Partition VarLength][ArmMode 1B][AccessCode BCD 3B]
+    // Variable length: 1 byte for partition < 253
+
+    // BCD encoding: each pair of digits as one byte
+    // "5555" -> 0x55 0x55 0xFF (3 bytes, unused nibbles = 0xF)
+    const codeBytes = Buffer.alloc(3, 0xFF);
+    for (let i = 0; i < codeStr.length && i < 6; i += 2) {
+      const high = parseInt(codeStr[i], 10);
+      const low = i + 1 < codeStr.length ? parseInt(codeStr[i + 1], 10) : 0x0F;
+      codeBytes[Math.floor(i / 2)] = (high << 4) | low;
+    }
+
+    // Build payload: [partition 1B][mode 1B][bcd code 3B]
+    const payload = Buffer.concat([
+      Buffer.from([partition]),  // 1 byte for partition number
+      Buffer.from([armMode]),
+      codeBytes
+    ]);
+
+    this.log(`[Session] PARTITION_ARM: partition=${partition}, mode=${armMode}, code=${codeStr}`);
+    this.log(`[Session] Payload: ${payload.toString('hex')}`);
+
+    return this.buildCommand(CMD.PARTITION_ARM, payload);
+  }
+
+  /**
+   * Build PARTITION_DISARM command
+   * @param {number} partition - Partition number (1-8)
+   * @param {string} accessCode - Master/user code (e.g., "5555")
+   */
+  buildPartitionDisarm(partition, accessCode) {
+    const codeStr = accessCode.toString();
+
+    // Payload format based on SDK decompiled code:
+    // [Partition VarLength][AccessCode BCD 3B]
+    // Variable length: 1 byte for partition < 253
+
+    // BCD encoding: each pair of digits as one byte
+    // "5555" -> 0x55 0x55 0xFF (3 bytes, unused nibbles = 0xF)
+    const codeBytes = Buffer.alloc(3, 0xFF);
+    for (let i = 0; i < codeStr.length && i < 6; i += 2) {
+      const high = parseInt(codeStr[i], 10);
+      const low = i + 1 < codeStr.length ? parseInt(codeStr[i + 1], 10) : 0x0F;
+      codeBytes[Math.floor(i / 2)] = (high << 4) | low;
+    }
+
+    // Build payload: [partition 1B][bcd code 3B]
+    const payload = Buffer.concat([
+      Buffer.from([partition]),  // 1 byte for partition number
+      codeBytes
+    ]);
+
+    this.log(`[Session] PARTITION_DISARM: partition=${partition}, code=${codeStr}`);
+    this.log(`[Session] Payload: ${payload.toString('hex')}`);
+
+    return this.buildCommand(CMD.PARTITION_DISARM, payload);
+  }
+
+  /**
+   * Build command output activation (PGM trigger)
+   * @param {number} partition - Partition number
+   * @param {number} outputNumber - Command output number (1-4)
+   */
+  buildCommandOutput(partition, outputNumber) {
+    const payload = Buffer.alloc(3);
+    payload.writeUInt16BE(partition, 0);
+    payload.writeUInt8(outputNumber, 2);
+
+    this.log(`[Session] COMMAND_OUTPUT: partition=${partition}, output=${outputNumber}`);
+    return this.buildCommand(CMD.COMMAND_OUTPUT, payload);
+  }
+}