hm-simulator 0.1.1 → 1.0.0

package/lib/tls.js

@@ -0,0 +1,160 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+/**
+ * Self signed certificate, generated at start.
+ *
+ * The CCU serves its XML-RPC interfaces over TLS with a certificate nobody can validate either, so
+ * a client that talks to the simulator has to be able to deal with exactly that. Node can generate
+ * key pairs but not certificates, and a test simulator should not need a dependency (or a private
+ * key checked into the repository) for it, so the certificate is DER encoded here by hand. It is a
+ * plain v3 certificate for localhost/127.0.0.1, valid for one year, and it is only ever meant for
+ * `rejectUnauthorized: false` clients.
+ */
+
+function length(size) {
+    if (size < 0x80) {
+        return Buffer.from([size]);
+    }
+    const bytes = [];
+    let rest = size;
+    while (rest > 0) {
+        bytes.unshift(rest & 0xff);
+        rest >>= 8;
+    }
+    return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+
+const tagged = (tag, content) => Buffer.concat([Buffer.from([tag]), length(content.length), content]);
+const sequence = (...parts) => tagged(0x30, Buffer.concat(parts));
+const set = (content) => tagged(0x31, content);
+const octetString = (content) => tagged(0x04, content);
+const bitString = (content) => tagged(0x03, Buffer.concat([Buffer.from([0x00]), content]));
+const utf8String = (value) => tagged(0x0c, Buffer.from(value, 'utf8'));
+const boolean = (value) => tagged(0x01, Buffer.from([value ? 0xff : 0x00]));
+const nullValue = () => Buffer.from([0x05, 0x00]);
+
+function integer(value) {
+    let bytes = [];
+    let rest = BigInt(value);
+    if (rest === 0n) {
+        bytes = [0];
+    }
+    while (rest > 0n) {
+        bytes.unshift(Number(rest & 0xffn));
+        rest >>= 8n;
+    }
+    if (bytes[0] & 0x80) {
+        bytes.unshift(0);
+    }
+    return tagged(0x02, Buffer.from(bytes));
+}
+
+function oid(dotted) {
+    const parts = dotted.split('.').map(Number);
+    const bytes = [parts[0] * 40 + parts[1]];
+    for (const part of parts.slice(2)) {
+        const chunk = [part & 0x7f];
+        let rest = part >> 7;
+        while (rest > 0) {
+            chunk.unshift((rest & 0x7f) | 0x80);
+            rest >>= 7;
+        }
+        bytes.push(...chunk);
+    }
+    return tagged(0x06, Buffer.from(bytes));
+}
+
+function utcTime(date) {
+    const pad = (value) => String(value).padStart(2, '0');
+    const text =
+        pad(date.getUTCFullYear() % 100) +
+        pad(date.getUTCMonth() + 1) +
+        pad(date.getUTCDate()) +
+        pad(date.getUTCHours()) +
+        pad(date.getUTCMinutes()) +
+        pad(date.getUTCSeconds()) +
+        'Z';
+    return tagged(0x17, Buffer.from(text, 'ascii'));
+}
+
+/** Name with a single CN attribute. */
+const name = (commonName) => sequence(set(sequence(oid('2.5.4.3'), utf8String(commonName))));
+
+const extension = (id, critical, value) =>
+    critical ? sequence(oid(id), boolean(true), octetString(value)) : sequence(oid(id), octetString(value));
+
+function subjectAltName(hostnames, ips) {
+    const parts = [
+        ...hostnames.map((host) => tagged(0x82, Buffer.from(host, 'ascii'))),
+        ...ips.map((ip) => tagged(0x87, Buffer.from(ip.split('.').map(Number)))),
+    ];
+    return sequence(...parts);
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.commonName='localhost']
+ * @param {Array<string>} [options.hostnames=['localhost']]
+ * @param {Array<string>} [options.ips=['127.0.0.1']]
+ * @param {number} [options.days=365]
+ * @returns {{key: string, cert: string}} both PEM encoded
+ */
+function selfSignedCertificate({
+    commonName = 'localhost',
+    hostnames = ['localhost'],
+    ips = ['127.0.0.1'],
+    days = 365,
+} = {}) {
+    const {privateKey, publicKey} = crypto.generateKeyPairSync('rsa', {modulusLength: 2048});
+    const spki = publicKey.export({type: 'spki', format: 'der'});
+
+    const sha256WithRsa = sequence(oid('1.2.840.113549.1.1.11'), nullValue());
+    const notBefore = new Date(Date.now() - 60 * 60 * 1000);
+    const notAfter = new Date(Date.now() + days * 24 * 60 * 60 * 1000);
+
+    const tbs = sequence(
+        tagged(0xa0, integer(2)), // version v3
+        integer(Date.now()),
+        sha256WithRsa,
+        name(commonName),
+        sequence(utcTime(notBefore), utcTime(notAfter)),
+        name(commonName),
+        spki,
+        tagged(
+            0xa3,
+            sequence(
+                extension('2.5.29.19', true, sequence(boolean(true))), // basicConstraints CA:TRUE
+                extension('2.5.29.17', false, subjectAltName(hostnames, ips)),
+            ),
+        ),
+    );
+
+    const signature = crypto.sign('sha256', tbs, privateKey);
+    const der = sequence(tbs, sha256WithRsa, bitString(signature));
+
+    const base64 = der.toString('base64').replace(/(.{64})/g, '$1\n');
+    const cert = `-----BEGIN CERTIFICATE-----\n${base64}${base64.endsWith('\n') ? '' : '\n'}-----END CERTIFICATE-----\n`;
+
+    return {key: privateKey.export({type: 'pkcs8', format: 'pem'}), cert};
+}
+
+/**
+ * Turns the `tls` option into {key, cert}: `true` generates a certificate, an object with key and
+ * cert is used as it is.
+ */
+function resolveTls(option) {
+    if (!option) {
+        return null;
+    }
+    if (option === true) {
+        return selfSignedCertificate();
+    }
+    if (option.key && option.cert) {
+        return option;
+    }
+    return selfSignedCertificate(option);
+}
+
+module.exports = {selfSignedCertificate, resolveTls};

package/lib/validate.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * Type and range checking of parameter values against a paramset description.
+ *
+ * The real interface processes are stricter than the old simulator was: a value of the wrong type
+ * or outside MIN..MAX is answered with a fault (hmipserver) or silently dropped and left in
+ * CONFIG_PENDING (crRFD, see the CONFIG_PENDING modes in lib/sim.js). Both need the same check,
+ * so it lives here.
+ */
+
+const WRITEABLE = 2;
+
+/** ENUM values arrive as the index (BidCos) or as the name (HmIP); both are stored as the index. */
+function castEnum(parameter, value, fault, name) {
+    const list = Array.isArray(parameter.VALUE_LIST) ? parameter.VALUE_LIST : [];
+    if (typeof value === 'string') {
+        const index = list.indexOf(value);
+        if (index === -1) {
+            throw fault('outOfRange', `${name}=${value}`);
+        }
+        return index;
+    }
+
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw fault('typeError', `${name} is ENUM`);
+    }
+    if (value < 0 || (list.length > 0 && value >= list.length)) {
+        throw fault('outOfRange', `${name}=${value}`);
+    }
+    return value;
+}
+
+function castNumber(parameter, value, fault, name) {
+    if (value !== null && typeof value === 'object' && typeof value.explicitDouble === 'number') {
+        value = value.explicitDouble;
+    }
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw fault('typeError', `${name} is ${parameter.TYPE}`);
+    }
+    if (parameter.TYPE === 'INTEGER' && !Number.isInteger(value)) {
+        throw fault('typeError', `${name} is INTEGER`);
+    }
+    if (typeof parameter.MIN === 'number' && value < parameter.MIN) {
+        throw fault('outOfRange', `${name}=${value} < ${parameter.MIN}`);
+    }
+    if (typeof parameter.MAX === 'number' && value > parameter.MAX) {
+        throw fault('outOfRange', `${name}=${value} > ${parameter.MAX}`);
+    }
+    return value;
+}
+
+/**
+ * @param {object} description the paramset description
+ * @param {string} name parameter name
+ * @param {*} value
+ * @param {function} fault fault factory, see lib/faults.js
+ * @param {object} [options]
+ * @param {boolean} [options.write=true] check OPERATIONS for the write bit
+ * @returns {*} the value as it is stored
+ */
+function castValue(description, name, value, fault, {write = true} = {}) {
+    const parameter = description && description[name];
+    if (!parameter) {
+        throw fault('unknownParameter', name);
+    }
+
+    if (write && typeof parameter.OPERATIONS === 'number' && !(parameter.OPERATIONS & WRITEABLE)) {
+        throw fault('readOnly', name);
+    }
+
+    switch (parameter.TYPE) {
+        case 'BOOL':
+        case 'ACTION':
+            if (typeof value === 'boolean') {
+                return value;
+            }
+            // the interface processes accept 0/1 for BOOL as well
+            if (value === 0 || value === 1) {
+                return Boolean(value);
+            }
+            throw fault('typeError', `${name} is ${parameter.TYPE}`);
+        case 'INTEGER':
+        case 'FLOAT':
+            return castNumber(parameter, value, fault, name);
+        case 'ENUM':
+            return castEnum(parameter, value, fault, name);
+        case 'STRING':
+            if (typeof value !== 'string') {
+                throw fault('typeError', `${name} is STRING`);
+            }
+            return value;
+        default:
+            return value;
+    }
+}
+
+/** The value a parameter has before anything was written, taken from its description. */
+function defaultValue(parameter) {
+    if (parameter.TYPE === 'ENUM' && Array.isArray(parameter.VALUE_LIST)) {
+        const index = parameter.VALUE_LIST.indexOf(parameter.DEFAULT);
+        return index === -1 ? 0 : index;
+    }
+    return parameter.DEFAULT;
+}
+
+/** Every parameter of a description with its default value. */
+function defaultParamset(description) {
+    const result = {};
+    for (const [name, parameter] of Object.entries(description || {})) {
+        result[name] = defaultValue(parameter);
+    }
+    return result;
+}
+
+/** Unwraps the `{explicitDouble}` wrapper both RPC encoders understand. */
+function plain(value) {
+    return value !== null && typeof value === 'object' && typeof value.explicitDouble === 'number'
+        ? value.explicitDouble
+        : value;
+}
+
+function clamp(parameter, value) {
+    let result = value;
+    if (typeof parameter.MIN === 'number' && result < parameter.MIN) {
+        result = parameter.MIN;
+    }
+    if (typeof parameter.MAX === 'number' && result > parameter.MAX) {
+        result = parameter.MAX;
+    }
+    return result;
+}
+
+/**
+ * hmipserver's MASTER write, measured on firmware 3.89.8 (Homematic Manager task 6).
+ *
+ * It stores what it is given **before** it validates, and it validates the *type* only: a string
+ * in an INTEGER and an ENUM value that is not in the VALUE_LIST are stored as they came and make
+ * the channel's configuration invalid, while a number outside MIN..MAX is simply accepted - there
+ * is no range check anywhere in hmipserver.
+ *
+ * @param {object} parameter the parameter's description
+ * @param {*} value
+ * @returns {{value: *, valid: boolean}} the value as it is stored, and whether it is acceptable
+ */
+function hmipStoredValue(parameter, value) {
+    const raw = plain(value);
+    switch (parameter.TYPE) {
+        case 'BOOL':
+        case 'ACTION':
+            if (typeof raw === 'boolean') {
+                return {value: raw, valid: true};
+            }
+            if (raw === 0 || raw === 1) {
+                return {value: Boolean(raw), valid: true};
+            }
+            return {value: raw, valid: false};
+        case 'INTEGER':
+            return {value: raw, valid: typeof raw === 'number' && Number.isInteger(raw)};
+        case 'FLOAT':
+            // an <int> is accepted where a <double> belongs and stored as the integer it is
+            return {value: raw, valid: typeof raw === 'number' && !Number.isNaN(raw)};
+        case 'ENUM': {
+            const list = Array.isArray(parameter.VALUE_LIST) ? parameter.VALUE_LIST : [];
+            if (typeof raw === 'string') {
+                const index = list.indexOf(raw);
+                return index === -1 ? {value: raw, valid: false} : {value: index, valid: true};
+            }
+            const inRange = typeof raw === 'number' && Number.isInteger(raw) && raw >= 0 && raw < list.length;
+            return {value: raw, valid: inRange};
+        }
+        case 'STRING':
+            return {value: raw, valid: typeof raw === 'string'};
+        default:
+            return {value: raw, valid: true};
+    }
+}
+
+/**
+ * rfd's MASTER write, measured on firmware 3.89.8 (Homematic Manager task 6).
+ *
+ * rfd never faults on a bad value. It silently clamps a number to MIN..MAX, coerces a string to a
+ * number, and ignores what it cannot use at all - an integer where a BOOL belongs, an ENUM name
+ * that is not in the VALUE_LIST. `undefined` means "ignored, nothing was stored".
+ *
+ * Not modelled: rfd also ignores a FLOAT that arrives as an XML-RPC `<int>`, which is why every
+ * FLOAT has to go out as an explicit double. Both decode to a JavaScript number, so the
+ * distinction is gone by the time the simulator sees the value.
+ *
+ * @param {object} parameter the parameter's description
+ * @param {*} value
+ * @returns {*} the value as it is stored, or `undefined` when rfd ignores it
+ */
+function bidcosStoredValue(parameter, value) {
+    const raw = plain(value);
+    switch (parameter.TYPE) {
+        case 'BOOL':
+        case 'ACTION':
+            return typeof raw === 'boolean' ? raw : undefined;
+        case 'INTEGER': {
+            const number = typeof raw === 'number' ? raw : Number.parseInt(String(raw), 10);
+            return clamp(parameter, Number.isNaN(number) ? 0 : Math.round(number));
+        }
+        case 'FLOAT': {
+            const number = typeof raw === 'number' ? raw : Number.parseFloat(String(raw));
+            return clamp(parameter, Number.isNaN(number) ? 0 : number);
+        }
+        case 'ENUM': {
+            const list = Array.isArray(parameter.VALUE_LIST) ? parameter.VALUE_LIST : [];
+            if (typeof raw === 'string') {
+                const index = list.indexOf(raw);
+                return index === -1 ? undefined : index;
+            }
+            if (typeof raw !== 'number' || !Number.isInteger(raw)) {
+                return undefined;
+            }
+            return list.length > 0 ? Math.min(Math.max(raw, 0), list.length - 1) : raw;
+        }
+        case 'STRING':
+            return typeof raw === 'string' ? raw : undefined;
+        default:
+            return raw;
+    }
+}
+
+module.exports = {
+    WRITEABLE,
+    castValue,
+    defaultValue,
+    defaultParamset,
+    hmipStoredValue,
+    bidcosStoredValue,
+};

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "hm-simulator",
-  "version": "0.1.1",
-  "description": "Simulates a Homematic CCU",
-  "main": "index.js",
+  "version": "1.0.0",
+  "description": "Simulates a Homematic CCU (rfd, hmipserver, VirtualDevices, CUxD, ReGa) for automated tests",
+  "main": "sim.js",
   "preferGlobal": true,
   "bin": {
     "hm-simulator": "./index.js"
   },
+  "engines": {
+    "node": ">=20.19"
+  },
   "scripts": {
-    "test": "camo-purge ; xo --space 4"
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write . && eslint --fix .",
+    "test": "node --test test/*.test.js",
+    "test:watch": "node --test --watch test/*.test.js",
+    "fixtures": "node tools/fixtures-from-paramsets.js"
   },
   "repository": {
     "type": "git",
@@ -26,30 +33,32 @@
   ],
   "author": "Sebastian Raff <hobbyquaker@gmail.com>",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "bugs": {
     "url": "https://github.com/hobbyquaker/hm-simulator/issues"
   },
   "homepage": "https://github.com/hobbyquaker/hm-simulator#readme",
+  "files": [
+    "index.js",
+    "sim.js",
+    "sim.mjs",
+    "lib/",
+    "data/",
+    "behaviors/",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
-    "async": "^3.1.0",
-    "binrpc": "^3.0.1",
-    "body-parser": "^1.18.3",
-    "express": "^4.16.4",
-    "homematic-xmlrpc": "^1.0.2",
-    "request": "^2.88.0",
-    "yalm": "^4.0.2"
+    "binrpc": "^4.2.0",
+    "homematic-xmlrpc": "^2.0.0"
   },
   "devDependencies": {
-    "camo-purge": "^1.0.1",
-    "xo": "^0.25.3"
-  },
-  "xo": {
-    "space": 4,
-    "rules": {
-      "no-cond-assign": "warn",
-      "no-case-declarations": "warn",
-      "no-constant-condition": "warn",
-      "no-unused-vars": "warn"
-    }
+    "@eslint/js": "^9.39.5",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.5.0",
+    "prettier": "^3.9.6"
   }
 }