dsc-itv2-client 1.0.7

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * DSC ITV2 Protocol Client Library
+ * Main exports for the library
+ */
+
+// Main client class
+export { ITV2Client } from './ITV2Client.js';
+
+// Parsers and utilities for advanced usage
+export { parseZoneStatus, formatZoneStatus, parsePartitionStatus, formatPartitionStatus, parseCommandResponse, parseCommandError } from './response-parsers.js';
+
+// Constants
+export { CMD, CMD_NAMES } from './itv2-session.js';
+export { Commands, CommandNames, getCommandName, DEFAULT_HOST, DEFAULT_PORT, DEFAULT_UDP_PORT, DEFAULT_TCP_PORT } from './constants.js';
+
+// Utility functions
+export { toHex, fromHex, hexDump, timestamp, log, crc16, byteUnstuff, byteStuff, parseCommand, makeCommand } from './utils.js';

package/src/itv2-crypto.js

@@ -0,0 +1,310 @@
+/**
+ * ITV2 Encryption Module
+ * Based on DSC-TLink reverse engineering
+ *
+ * Type 1 Encryption:
+ * - Uses Integration ID from [422] (NOT Access Code from [423]!)
+ * - Key derivation: first 8 hex chars of Integration ID, repeated 4 times → 16 bytes
+ * - Example: Integration ID "250228754876" → key "25022875" × 4 = "25022875250228752502287525022875"
+ * - Panel sends 48-byte initializer: [16 check bytes][32 ciphertext]
+ * - AES-ECB decrypt ciphertext, verify check bytes match even indexes, extract key from odd indexes
+ *
+ * Type 2 Encryption:
+ * - Uses 32-digit Integration Access Code from [700]
+ * - Direct AES-ECB encryption of 16-byte initializer
+ * - Same transform for encode local and decode remote
+ *
+ * Key Exchange:
+ * - Each side generates 32 random bytes
+ * - Even indexes become check bytes (sent in plaintext for verification)
+ * - Odd indexes become the AES session key
+ * - Ciphertext = AES-ECB-Encrypt(random32, derivedKey)
+ * - Initializer = [checkBytes 16][ciphertext 32] = 48 bytes
+ *
+ * Session Keys:
+ * - Your SEND key = derived from OTHER side's initializer (odd indexes of their decrypted random bytes)
+ * - Your RECEIVE key = odd indexes of YOUR random bytes (you already know this when you generate)
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+
+/**
+ * Transform Type 1 key string to 16-byte AES key
+ *
+ * Based on SDK analysis: The Access Code from [423] is used (8 digits)
+ * The key is derived by treating the 8 ASCII characters as bytes and repeating twice
+ * Example: "28754876" → ASCII bytes [0x32,0x33,0x34,0x32,0x35,0x33,0x35,0x32] repeated 2x = 16 bytes
+ *
+ * @param {string} keyString - 8-digit access code
+ * @param {string} method - 'ascii' (default) or 'hex'
+ */
+export function transformType1KeyString(keyString, method = 'ascii') {
+  if (keyString.length < 8) {
+    throw new Error(`Access Code must be at least 8 digits, got ${keyString.length}`);
+  }
+  const first8 = keyString.substring(0, 8);
+
+  if (method === 'ascii') {
+    // ASCII method: each digit becomes its ASCII byte value, repeated twice for 16 bytes
+    // "28754876" → [0x32, 0x33, 0x34, 0x32, 0x35, 0x33, 0x35, 0x32] × 2
+    const key = Buffer.alloc(16);
+    for (let i = 0; i < 8; i++) {
+      key[i] = first8.charCodeAt(i);
+      key[i + 8] = first8.charCodeAt(i);
+    }
+    return key;
+  } else {
+    // Hex method: treat as hex string, repeat 4 times → 16 bytes
+    // "28754876" → 0x23 0x42 0x53 0x52 × 4
+    const hexString = first8 + first8 + first8 + first8;
+    return Buffer.from(hexString, 'hex');
+  }
+}
+
+/**
+ * AES-ECB encrypt with zero padding
+ */
+export function aesEcbEncrypt(key, data) {
+  // Pad to 16-byte boundary
+  const padded = Buffer.alloc(Math.ceil(data.length / 16) * 16);
+  data.copy(padded);
+
+  const cipher = createCipheriv('aes-128-ecb', key, null);
+  cipher.setAutoPadding(false);
+  return Buffer.concat([cipher.update(padded), cipher.final()]);
+}
+
+/**
+ * AES-ECB decrypt with zero padding
+ */
+export function aesEcbDecrypt(key, data) {
+  const decipher = createDecipheriv('aes-128-ecb', key, null);
+  decipher.setAutoPadding(false);
+  return Buffer.concat([decipher.update(data), decipher.final()]);
+}
+
+/**
+ * Get bytes at even indexes (0, 2, 4, ...)
+ */
+function evenIndexes(bytes) {
+  const result = [];
+  for (let i = 0; i < bytes.length; i += 2) {
+    result.push(bytes[i]);
+  }
+  return Buffer.from(result);
+}
+
+/**
+ * Get bytes at odd indexes (1, 3, 5, ...)
+ */
+function oddIndexes(bytes) {
+  const result = [];
+  for (let i = 1; i < bytes.length; i += 2) {
+    result.push(bytes[i]);
+  }
+  return Buffer.from(result);
+}
+
+/**
+ * Parse Type 1 initializer from panel's REQUEST_ACCESS payload
+ *
+ * The panel sends a 48-byte initializer:
+ * - Bytes 0-15: Check bytes (even indexes of plaintext)
+ * - Bytes 16-47: AES-ECB encrypted data (32 bytes)
+ *
+ * After decryption, the 32-byte plaintext contains:
+ * - Even indexes → should match check bytes
+ * - Odd indexes → the AES key for decrypting panel messages
+ *
+ * Key derivation attempts multiple methods:
+ * - Access Code from [423] (8 digits) with ASCII and hex encoding
+ * - Integration ID from [422] (12 digits) with ASCII and hex encoding
+ *
+ * @param {string} accessCode - 8-digit access code from [423]
+ * @param {Buffer} remoteInitializer - 48-byte payload from REQUEST_ACCESS
+ * @param {string} integrationId - Optional 12-digit integration ID from [422]
+ * @returns {Buffer} 16-byte AES key for decrypting messages from panel
+ */
+export function parseType1Initializer(accessCode, remoteInitializer, integrationId = null, verbose = false) {
+  if (remoteInitializer.length !== 48) {
+    throw new Error(`Type 1 initializer must be 48 bytes, got ${remoteInitializer.length}`);
+  }
+
+  const checkBytes = remoteInitializer.slice(0, 16);
+  const cipherText = remoteInitializer.slice(16, 48);
+
+  const first8 = accessCode.substring(0, 8);
+
+  // Verbose logging helper
+  const log = verbose ? console.log : () => {};
+
+  // Key derivation methods to try (various interpretations)
+  const keyMethods = [
+    // Method 1: ASCII bytes of 8-digit code, repeated twice = 16 bytes
+    { name: 'ascii-repeat-2x', key: transformType1KeyString(accessCode, 'ascii') },
+    // Method 2: Hex interpretation of code, repeated 4 times = 16 bytes
+    { name: 'hex-repeat-4x', key: transformType1KeyString(accessCode, 'hex') },
+    // Method 3: Just the first 8 chars as ASCII (padded with zeros)
+    { name: 'ascii-8-padded', key: Buffer.from(first8.padEnd(16, '\0'), 'ascii') },
+    // Method 4: ASCII of code truncated/padded to 16 bytes
+    { name: 'ascii-16-trunc', key: Buffer.from(accessCode.padEnd(16, '0').substring(0, 16), 'ascii') },
+    // Method 5: BCD encoding - each digit becomes a nibble, repeated to 16 bytes
+    { name: 'bcd-repeat', key: Buffer.from(first8.split('').map((d,i) => i%2===0 ? (parseInt(d)<<4) : parseInt(first8[i-1])*16+parseInt(d)).filter((_,i)=>i%2===1).concat([0,0,0,0,0,0,0,0,0,0,0,0]).slice(0,16)) },
+  ];
+
+  // Also try with Integration ID if provided (the SDK might use Integration ID for key derivation)
+  if (integrationId && integrationId.length >= 8) {
+    const intId8 = integrationId.substring(0, 8);
+    keyMethods.push(
+      // Integration ID as ASCII bytes repeated twice
+      { name: 'intid-ascii-2x', key: (() => { const k = Buffer.alloc(16); for(let i=0;i<8;i++){k[i]=intId8.charCodeAt(i);k[i+8]=intId8.charCodeAt(i);} return k; })() },
+      // Integration ID as hex repeated 4 times
+      { name: 'intid-hex-4x', key: Buffer.from(intId8+intId8+intId8+intId8, 'hex') },
+      // Integration ID first 16 chars as ASCII
+      { name: 'intid-ascii-16', key: Buffer.from(integrationId.padEnd(16, '0').substring(0, 16), 'ascii') },
+    );
+  }
+
+  log(`[Type1] Access code: ${accessCode}`);
+  log(`[Type1] Check bytes: ${checkBytes.toString('hex')}`);
+  log(`[Type1] Ciphertext:  ${cipherText.toString('hex')}`);
+
+  for (const method of keyMethods) {
+    try {
+      if (method.key.length !== 16) {
+        log(`[Type1] Skipping ${method.name}: invalid key length ${method.key.length}`);
+        continue;
+      }
+
+      log(`[Type1] Trying ${method.name}: key=${method.key.toString('hex')}`);
+
+      // Decrypt the ciphertext
+      const plainText = aesEcbDecrypt(method.key, cipherText);
+      log(`[Type1]   Decrypted: ${plainText.toString('hex')}`);
+
+      // Extract even and odd indexes
+      const calcEven = evenIndexes(plainText);
+      const calcOdd = oddIndexes(plainText);
+      log(`[Type1]   Even idx:  ${calcEven.toString('hex')}`);
+      log(`[Type1]   Odd idx:   ${calcOdd.toString('hex')}`);
+
+      // Check if even indexes match check bytes → odd indexes are the key
+      if (checkBytes.equals(calcEven)) {
+        log(`[Type1] ✓ SUCCESS with ${method.name} (check=even, key=odd)`);
+        return calcOdd;
+      }
+
+      // Check if odd indexes match check bytes → even indexes are the key
+      if (checkBytes.equals(calcOdd)) {
+        log(`[Type1] ✓ SUCCESS with ${method.name} (check=odd, key=even)`);
+        return calcEven;
+      }
+
+      log(`[Type1]   No match for ${method.name}`);
+    } catch (err) {
+      log(`[Type1] Error with ${method.name}: ${err.message}`);
+    }
+  }
+
+  // If no method worked, try the primary method and return without verification
+  // This allows debugging to continue even if check bytes don't match
+  log(`[Type1] WARNING: No method matched check bytes, using ascii-repeat-2x without verification`);
+  const key = transformType1KeyString(accessCode, 'ascii');
+  const plainText = aesEcbDecrypt(key, cipherText);
+
+  log(`[Type1] Decrypted (no verify): ${plainText.toString('hex')}`);
+  const derivedKey = oddIndexes(plainText);
+  log(`[Type1] Derived key (odd indexes): ${derivedKey.toString('hex')}`);
+
+  return derivedKey;
+}
+
+/**
+ * Generate Type 1 initializer and local AES key
+ *
+ * Creates a 48-byte initializer for key exchange:
+ * - Generate 32 random bytes
+ * - Even indexes become check bytes (16 bytes, sent in plaintext)
+ * - Odd indexes become our receive key (16 bytes)
+ * - Encrypt the 32 random bytes with derived key
+ * - Send [16 check bytes][32 ciphertext]
+ *
+ * @param {string} accessCode - 8-digit access code from [423]
+ * @param {string} method - Key derivation method: 'ascii' (default) or 'hex'
+ * @returns {{ initializer: Buffer, localKey: Buffer }}
+ *   - initializer: 48-byte data to send in our REQUEST_ACCESS
+ *   - localKey: 16-byte AES key (this becomes our RECEIVE key)
+ */
+export function generateType1Initializer(accessCode, integrationId, method = 'ascii', verbose = false) {
+  const log = verbose ? console.log : () => {};
+  // Generate 32 random bytes
+  const randomData = randomBytes(32);
+
+  // Check bytes = even indexes of random data (sent in plaintext for verification)
+  const checkBytes = evenIndexes(randomData);
+
+  // Our local key = odd indexes of random data (this is our RECEIVE key)
+  const localKey = oddIndexes(randomData);
+
+  // Derive encryption key
+  let key;
+  let keySource = accessCode;
+  if (method === 'intid-hex-4x') {
+    keySource = integrationId;
+    const intId8 = integrationId.substring(0, 8);
+    key = Buffer.from(intId8 + intId8 + intId8 + intId8, 'hex');
+  } else {
+    key = transformType1KeyString(accessCode, method);
+  }
+
+  log(`[Type1Gen] Key source: ${keySource}`);
+  log(`[Type1Gen] Key method: ${method}`);
+  log(`[Type1Gen] Derived key: ${key.toString('hex')}`);
+  log(`[Type1Gen] Random data: ${randomData.toString('hex')}`);
+  log(`[Type1Gen] Check bytes: ${checkBytes.toString('hex')}`);
+  log(`[Type1Gen] Local key:   ${localKey.toString('hex')}`);
+
+  // Encrypt the random data
+  const cipherText = aesEcbEncrypt(key, randomData);
+  log(`[Type1Gen] Ciphertext:  ${cipherText.toString('hex')}`);
+
+  // Self-verification: decrypt and verify check bytes match
+  const decrypted = aesEcbDecrypt(key, cipherText);
+  const verifyEven = evenIndexes(decrypted);
+  const verifyOdd = oddIndexes(decrypted);
+  log(`[Type1Gen] Self-verify decrypted: ${decrypted.toString('hex')}`);
+  log(`[Type1Gen] Self-verify even idx:  ${verifyEven.toString('hex')}`);
+  log(`[Type1Gen] Self-verify matches:   ${checkBytes.equals(verifyEven) ? 'YES ✓' : 'NO ✗'}`);
+
+  // Build 48-byte initializer: [16 check bytes][32 ciphertext]
+  const initializer = Buffer.concat([checkBytes, cipherText]);
+
+  return { initializer, localKey };
+}
+
+/**
+ * Type 2 initializer transform (symmetric)
+ * Same transform for encoding local and decoding remote initializers
+ *
+ * @param {string} integrationAccessCode - 32-digit access code from [700]
+ * @param {Buffer} initializer - 16-byte initializer
+ * @returns {Buffer} 16-byte transformed result
+ */
+export function type2InitializerTransform(integrationAccessCode, initializer) {
+  if (integrationAccessCode.length !== 32) {
+    throw new Error(`Type 2 access code must be 32 digits, got ${integrationAccessCode.length}`);
+  }
+  if (initializer.length !== 16) {
+    throw new Error(`Type 2 initializer must be 16 bytes, got ${initializer.length}`);
+  }
+
+  const key = Buffer.from(integrationAccessCode, 'hex');
+  return aesEcbEncrypt(key, initializer);
+}
+
+/**
+ * Generate random 16-byte key
+ */
+export function getRandomKey() {
+  return randomBytes(16);
+}