smart-home-engine 1.53.4 → 2.0.1

package/src/matter/bindings.js

@@ -0,0 +1,291 @@
+'use strict';
+
+/**
+ * Matter bindings — the pure half (roadmap M13): what to write into a target's Access Control
+ * list and a source's Binding list so that the source may drive the target directly, and the
+ * guard that keeps she's own Administer entry in every ACL it writes. No I/O here; the controller
+ * reads and writes the attributes and calls these functions in between.
+ *
+ * Two independent clusters make a binding (Matter core spec 9.10 and 9.6):
+ *   - the target's Access Control list (endpoint 0, cluster 0x001F) must grant the source node
+ *     the Operate privilege on the bound cluster/endpoint — else the target refuses the command;
+ *   - the source's Binding list (its endpoint, cluster 0x001E) names the targets it sends to.
+ * Both are fabric-scoped lists: a write replaces this fabric's entries wholesale, so every write
+ * goes through the guard below.
+ */
+
+const PRIVILEGE = { view: 1, proxyView: 2, operate: 3, manage: 4, administer: 5 };
+const AUTH_MODE = { pase: 1, case: 2, group: 3 };
+
+const BINDING_CLUSTER_ID = 0x001e;
+const ACCESS_CONTROL_CLUSTER_ID = 0x001f;
+const SWITCH_CLUSTER_ID = 0x003b;
+
+/** The clusters a binding may carry, with the plain words the UI uses. */
+const BINDABLE_CLUSTERS = {
+    onOff: { id: 0x0006, label: 'on/off' },
+    levelControl: { id: 0x0008, label: 'dimming' },
+    colorControl: { id: 0x0300, label: 'colour' },
+    windowCovering: { id: 0x0102, label: 'blinds' },
+    thermostat: { id: 0x0201, label: 'thermostat' },
+    fanControl: { id: 0x0202, label: 'fan' },
+    doorLock: { id: 0x0101, label: 'lock' },
+};
+
+/** Device types whose endpoints are built to be binding sources (Matter device library). */
+const SOURCE_DEVICE_TYPES = {
+    0x0103: 'On/Off Light Switch',
+    0x0104: 'Dimmer Switch',
+    0x0105: 'Color Dimmer Switch',
+    0x0203: 'Window Covering Controller',
+    0x000b: 'Door Lock Controller',
+    0x0018: 'Pump Controller',
+    0x0017: 'Control Bridge',
+};
+const GENERIC_SWITCH_DEVICE_TYPE = 0x000f;
+
+/** Defaults the specification guarantees when a device does not report its limits. */
+const DEFAULT_LIMITS = { subjectsPerAccessControlEntry: 4, targetsPerAccessControlEntry: 3, accessControlEntriesPerFabric: 4 };
+
+function clusterIdOf(cluster) {
+    if (typeof cluster === 'number') return cluster;
+    const known = BINDABLE_CLUSTERS[cluster];
+    if (known) return known.id;
+    const n = Number(cluster);
+    if (Number.isFinite(n)) return n;
+    throw new Error(`Unknown cluster "${cluster}"`);
+}
+
+function clusterNameOf(id) {
+    for (const [name, def] of Object.entries(BINDABLE_CLUSTERS)) if (def.id === id) return name;
+    return null;
+}
+
+function sameId(a, b) {
+    if (a === undefined || a === null || b === undefined || b === null) return false;
+    return String(a) === String(b);
+}
+
+/** she's own Administer entry on a device: CASE, privilege 5, subjects containing she's node ID. */
+function findAdminEntry(acl, sheNodeId) {
+    return (acl ?? []).find((e) => e && e.privilege === PRIVILEGE.administer && e.authMode === AUTH_MODE.case && (e.subjects ?? []).some((s) => sameId(s, sheNodeId))) ?? null;
+}
+
+/**
+ * The guard: an ACL list is written only when it still carries she's own Administer entry —
+ * without it the device would refuse every further interaction from she, and only a factory
+ * reset brings it back.
+ */
+function assertSafeAcl(acl, sheNodeId) {
+    if (!Array.isArray(acl)) throw new Error('ACL is not a list');
+    if (!findAdminEntry(acl, sheNodeId)) {
+        throw new Error(`refusing to write an ACL without she's own Administer entry (node ${sheNodeId}) — she would lock itself out of the device`);
+    }
+}
+
+/**
+ * Entries she manages for bindings and groups: Operate, the auth mode (CASE for a source node,
+ * Group for a group ID), exactly one subject, explicit targets.
+ */
+function isOperateEntryFor(entry, subject, authMode = AUTH_MODE.case) {
+    return (
+        !!entry &&
+        entry.privilege === PRIVILEGE.operate &&
+        entry.authMode === authMode &&
+        Array.isArray(entry.subjects) &&
+        entry.subjects.length === 1 &&
+        sameId(entry.subjects[0], subject) &&
+        Array.isArray(entry.targets)
+    );
+}
+
+function targetMatches(t, endpoint, clusterId) {
+    return !!t && sameId(t.cluster, clusterId) && sameId(t.endpoint, endpoint);
+}
+
+function effectiveLimits(limits) {
+    const out = { ...DEFAULT_LIMITS };
+    for (const k of Object.keys(DEFAULT_LIMITS)) {
+        const v = Number(limits?.[k]);
+        if (Number.isFinite(v) && v > 0) out[k] = v;
+    }
+    return out;
+}
+
+/**
+ * Grant the source node Operate on the target endpoint's clusters. Returns the new ACL list (the
+ * input is not modified). Extends she's own Operate entry for that source when one exists and has
+ * room, else adds an entry; refuses when the device's limits would be exceeded.
+ *
+ * @param {object[]} acl           the target's ACL entries of she's fabric, as read
+ * @param {{ subject: bigint|number|string, endpoint: number, clusters: (number|string)[], sheNodeId: bigint|number|string, limits?: object, fabricIndex?: number }} opts
+ * @returns {object[]}
+ */
+function grantOperate(acl, { subject, endpoint, clusters, sheNodeId, limits, fabricIndex, authMode = AUTH_MODE.case }) {
+    assertSafeAcl(acl, sheNodeId);
+    const lim = effectiveLimits(limits);
+    const out = acl.map((e) => ({ ...e, subjects: e.subjects ? [...e.subjects] : e.subjects, targets: e.targets ? e.targets.map((t) => ({ ...t })) : e.targets }));
+    const wanted = clusters.map(clusterIdOf).filter((id, i, arr) => arr.indexOf(id) === i);
+    const missing = wanted.filter((id) => !out.some((e) => isOperateEntryFor(e, subject, authMode) && e.targets.some((t) => targetMatches(t, endpoint, id))));
+    if (missing.length === 0) return out;
+    const fi = fabricIndex ?? findAdminEntry(acl, sheNodeId).fabricIndex;
+    for (const id of missing) {
+        const target = { cluster: id, endpoint: Number(endpoint), deviceType: null };
+        const room = out.find((e) => isOperateEntryFor(e, subject, authMode) && e.targets.length < lim.targetsPerAccessControlEntry);
+        if (room) {
+            room.targets.push(target);
+            continue;
+        }
+        if (out.length >= lim.accessControlEntriesPerFabric) {
+            throw new Error(`the device allows only ${lim.accessControlEntriesPerFabric} access control entries per fabric and all are in use`);
+        }
+        const entry = { privilege: PRIVILEGE.operate, authMode, subjects: [typeof subject === 'bigint' ? subject : BigInt(subject)], targets: [target] };
+        if (fi !== undefined) entry.fabricIndex = fi;
+        out.push(entry);
+    }
+    return out;
+}
+
+/**
+ * Take the Operate grant for the given endpoint/clusters away from the source node — only from
+ * entries she manages (Operate, CASE, that one subject). An entry left without targets is dropped.
+ * Returns the new ACL list.
+ */
+function revokeOperate(acl, { subject, endpoint, clusters, sheNodeId, authMode = AUTH_MODE.case }) {
+    assertSafeAcl(acl, sheNodeId);
+    const ids = clusters.map(clusterIdOf);
+    const out = [];
+    for (const e of acl) {
+        if (!isOperateEntryFor(e, subject, authMode)) {
+            out.push(e);
+            continue;
+        }
+        const targets = e.targets.filter((t) => !ids.some((id) => targetMatches(t, endpoint, id)));
+        if (targets.length > 0) out.push({ ...e, targets });
+    }
+    return out;
+}
+
+/** Which clusters of target endpoint the source node is granted Operate on (by she's entries). */
+function grantedClusters(acl, { subject, endpoint, authMode = AUTH_MODE.case }) {
+    const ids = new Set();
+    for (const e of acl ?? []) {
+        if (!isOperateEntryFor(e, subject, authMode)) continue;
+        for (const t of e.targets) if (sameId(t.endpoint, endpoint) && t.cluster !== null && t.cluster !== undefined) ids.add(Number(t.cluster));
+    }
+    return [...ids];
+}
+
+function bindingEntryMatches(b, { node, group, endpoint, cluster }) {
+    if (!b || !sameId(b.cluster, cluster)) return false;
+    if (group !== undefined && group !== null) return sameId(b.group, group) && (b.node === undefined || b.node === null);
+    return sameId(b.node, node) && sameId(b.endpoint, endpoint);
+}
+
+/**
+ * Append unicast binding entries `{ node, endpoint, cluster }` for the clusters not bound yet.
+ * Returns the new list (and which clusters were added).
+ */
+function addBindingEntries(bindings, { node, group, endpoint, clusters, fabricIndex }) {
+    const out = (bindings ?? []).map((b) => ({ ...b }));
+    const added = [];
+    const isGroup = group !== undefined && group !== null;
+    for (const c of clusters) {
+        const cluster = clusterIdOf(c);
+        if (out.some((b) => bindingEntryMatches(b, { node, group, endpoint, cluster }))) continue;
+        const entry = isGroup ? { group: Number(group), cluster } : { node: typeof node === 'bigint' ? node : BigInt(node), endpoint: Number(endpoint), cluster };
+        if (fabricIndex !== undefined) entry.fabricIndex = fabricIndex;
+        out.push(entry);
+        added.push(cluster);
+    }
+    return { bindings: out, added };
+}
+
+/** Remove the unicast binding entries for the clusters; returns the new list and which clusters were removed. */
+function removeBindingEntries(bindings, { node, group, endpoint, clusters }) {
+    const ids = clusters.map(clusterIdOf);
+    const removed = [];
+    const out = (bindings ?? []).filter((b) => {
+        const hit = ids.find((cluster) => bindingEntryMatches(b, { node, group, endpoint, cluster }));
+        if (hit === undefined) return true;
+        removed.push(hit);
+        return false;
+    });
+    return { bindings: out, removed };
+}
+
+/** The clusters of `{ node, endpoint }` that other entries of the list still bind — their ACL grant must stay. */
+function clustersStillBound(bindings, { node, group, endpoint }) {
+    const ids = new Set();
+    const isGroup = group !== undefined && group !== null;
+    for (const b of bindings ?? []) {
+        if (b.cluster === undefined || b.cluster === null) continue;
+        const hit = isGroup ? sameId(b.group, group) : sameId(b.node, node) && sameId(b.endpoint, endpoint);
+        if (hit) ids.add(Number(b.cluster));
+    }
+    return [...ids];
+}
+
+/** Does the source still bind anything to the group (its key set must stay)? */
+function groupStillBound(bindings, group) {
+    return (bindings ?? []).some((b) => sameId(b.group, group));
+}
+
+/**
+ * Classify the endpoints of the commissioned nodes into binding sources and targets.
+ *
+ * @param {{ nodeId: string, name: string|null, online: boolean, endpoints: { endpointId: number, name: string|null, deviceTypes: number[], serverList: number[], clientList: number[] }[] }[]} nodes
+ * @returns {{ sources: object[], targets: object[], notBindable: object[] }}
+ */
+function classifyEndpoints(nodes) {
+    const sources = [];
+    const targets = [];
+    const notBindable = [];
+    for (const node of nodes) {
+        for (const ep of node.endpoints) {
+            if (ep.endpointId === 0) continue;
+            const servers = (ep.serverList ?? []).map(Number);
+            const clients = (ep.clientList ?? []).map(Number);
+            const base = { nodeId: node.nodeId, nodeName: node.name, online: node.online, endpointId: ep.endpointId, name: ep.name, deviceTypes: ep.deviceTypes ?? [] };
+            const serverClusters = Object.entries(BINDABLE_CLUSTERS)
+                .filter(([, def]) => servers.includes(def.id))
+                .map(([name, def]) => ({ name, id: def.id, label: def.label }));
+            if (serverClusters.length) targets.push({ ...base, clusters: serverClusters });
+            const clientClusters = Object.entries(BINDABLE_CLUSTERS)
+                .filter(([, def]) => clients.includes(def.id))
+                .map(([name, def]) => ({ name, id: def.id, label: def.label }));
+            if (servers.includes(BINDING_CLUSTER_ID) && clientClusters.length) {
+                sources.push({ ...base, clusters: clientClusters, deviceTypeName: (ep.deviceTypes ?? []).map((t) => SOURCE_DEVICE_TYPES[t]).find(Boolean) ?? null });
+            } else if (servers.includes(SWITCH_CLUSTER_ID) || (ep.deviceTypes ?? []).includes(GENERIC_SWITCH_DEVICE_TYPE)) {
+                notBindable.push({ ...base, reason: 'sends button events only (Generic Switch) — bind it with a script, see she.matter.sub' });
+            } else if (servers.includes(BINDING_CLUSTER_ID) && !clientClusters.length && !serverClusters.length) {
+                notBindable.push({ ...base, reason: 'has a Binding cluster but no client cluster she can bind (On/Off, Level Control, …)' });
+            }
+        }
+    }
+    return { sources, targets, notBindable };
+}
+
+module.exports = {
+    PRIVILEGE,
+    AUTH_MODE,
+    BINDING_CLUSTER_ID,
+    ACCESS_CONTROL_CLUSTER_ID,
+    SWITCH_CLUSTER_ID,
+    BINDABLE_CLUSTERS,
+    SOURCE_DEVICE_TYPES,
+    DEFAULT_LIMITS,
+    clusterIdOf,
+    clusterNameOf,
+    sameId,
+    findAdminEntry,
+    assertSafeAcl,
+    grantOperate,
+    revokeOperate,
+    grantedClusters,
+    addBindingEntries,
+    removeBindingEntries,
+    clustersStillBound,
+    groupStillBound,
+    classifyEndpoints,
+};

package/src/matter/bridge-templates.js

@@ -0,0 +1,261 @@
+'use strict';
+
+/**
+ * The Matter ↔ MQTT bridge's pure parts (roadmap M19): topic templates with `${placeholders}`
+ * (filled outbound, turned into subscription patterns and matched inbound — node-red-contrib-ccu's
+ * mqtt node is the model), the payload formats, the MQTT device names, the cluster deny-list and
+ * the resolution of a `set` into a Matter command or an attribute write.
+ *
+ * The defaults are mqtt-smarthome (SPEC.md 2.0): `{ val, ts, lc }`, `matter/status/#`, `matter/set/#`.
+ */
+
+const mqttWildcard = require('../lib/mqtt-wildcards');
+
+const DEFAULT_TEMPLATES = Object.freeze({
+    connected: 'matter/connected',
+    attribute: 'matter/status/${device}/${endpoint}/${cluster}/${attribute}',
+    event: 'matter/status/${device}/${endpoint}/${cluster}/${event}',
+    online: 'matter/status/${device}/online',
+    set: 'matter/set/${device}/${endpoint}/${cluster}/${attributeOrCommand}',
+    get: 'matter/get/${device}/${endpoint}/${cluster}/${attribute}',
+});
+
+const OUTBOUND = ['connected', 'attribute', 'event', 'online'];
+const INBOUND = ['set', 'get'];
+const PLACEHOLDERS = ['device', 'nodeId', 'endpoint', 'cluster', 'attribute', 'event', 'attributeOrCommand'];
+const FORMATS = ['plain', 'basic', 'extended'];
+
+/** Clusters never bridged (D-24): diagnostics, commissioning, the data model's plumbing. */
+const DENY_CLUSTERS = new Set([
+    'descriptor',
+    'binding',
+    'accessControl',
+    'groups',
+    'groupKeyManagement',
+    'generalDiagnostics',
+    'softwareDiagnostics',
+    'threadNetworkDiagnostics',
+    'wiFiNetworkDiagnostics',
+    'ethernetNetworkDiagnostics',
+    'otaSoftwareUpdateRequestor',
+    'otaSoftwareUpdateProvider',
+    'identify',
+    'fixedLabel',
+    'userLabel',
+    'basicInformation',
+    'generalCommissioning',
+    'networkCommissioning',
+    'administratorCommissioning',
+    'operationalCredentials',
+    'timeSynchronization',
+    'icdManagement',
+    'powerSourceConfiguration',
+    'localizationConfiguration',
+    'timeFormatLocalization',
+    'unitLocalization',
+    'diagnosticLogs',
+    'scenesManagement',
+    'proxyConfiguration',
+    'proxyDiscovery',
+    'proxyValid',
+]);
+
+/** Global attributes every cluster has — plumbing, not state. */
+const DENY_ATTRIBUTES = new Set(['generatedCommandList', 'acceptedCommandList', 'eventList', 'attributeList', 'featureMap', 'clusterRevision']);
+
+/** camelCase → snake_case (`levelControl` → `level_control`, `currentPositionLiftPercent100ths` → `current_position_lift_percent100ths`). */
+function snake(name) {
+    return String(name)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .toLowerCase();
+}
+
+/** snake_case → camelCase (`on_off` → `onOff`). */
+function camel(name) {
+    return String(name).replace(/_([a-z0-9])/g, (_m, c) => c.toUpperCase());
+}
+
+/** An MQTT device name from a device name: lower snake_case, nothing MQTT minds (`/`, `+`, `#`, spaces). */
+function mqttName(name) {
+    const s = String(name ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[äöüß]/g, (c) => ({ ä: 'ae', ö: 'oe', ü: 'ue', ß: 'ss' })[c])
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return s || 'device';
+}
+
+/** Make a name unique among the taken ones: `name`, `name_2`, `name_3`, … */
+function uniqueName(name, taken) {
+    const set = new Set(taken);
+    if (!set.has(name)) return name;
+    for (let i = 2; ; i++) if (!set.has(`${name}_${i}`)) return `${name}_${i}`;
+}
+
+function placeholdersOf(template) {
+    return [...String(template).matchAll(/\$\{([a-zA-Z]+)\}/g)].map((m) => m[1]);
+}
+
+/** Fill a template with values; a missing value becomes an empty segment. */
+function fill(template, vars) {
+    return String(template).replace(/\$\{([a-zA-Z]+)\}/g, (_m, k) => (vars[k] === undefined || vars[k] === null ? '' : String(vars[k])));
+}
+
+/**
+ * The subscription pattern of an inbound template: every placeholder `+`, a placeholder at the
+ * very end `#` (it may span several segments — node-red-contrib-ccu does the same).
+ */
+function toPattern(template) {
+    const t = String(template);
+    const parts = t.split('/');
+    return parts
+        .map((seg, i) => {
+            if (!/\$\{[a-zA-Z]+\}/.test(seg)) return seg;
+            return i === parts.length - 1 && /^\$\{[a-zA-Z]+\}$/.test(seg) ? '#' : '+';
+        })
+        .join('/');
+}
+
+/**
+ * Match a topic against a template: the placeholder values, or null. A segment with text around
+ * a placeholder (`${device}_x`) matches the pattern but cannot be split — it is returned whole.
+ */
+function match(template, topic) {
+    const parts = String(template).split('/');
+    const pattern = toPattern(template);
+    const captured = mqttWildcard(topic, pattern);
+    if (captured === null) return null;
+    const vars = {};
+    let c = 0;
+    parts.forEach((seg) => {
+        const ph = placeholdersOf(seg);
+        if (!ph.length) return;
+        vars[ph[0]] = captured[c++];
+    });
+    return vars;
+}
+
+/**
+ * Validate a template set: every template a non-empty string of known placeholders (an empty
+ * one disables that topic), no MQTT wildcards, and an inbound template must not match what an
+ * outbound one publishes (she would answer its own status). Returns a list of problems.
+ */
+function validate(templates) {
+    const problems = [];
+    const t = { ...DEFAULT_TEMPLATES, ...(templates ?? {}) };
+    for (const [key, value] of Object.entries(t)) {
+        if (!(key in DEFAULT_TEMPLATES)) {
+            problems.push(`unknown template "${key}"`);
+            continue;
+        }
+        if (typeof value !== 'string') {
+            problems.push(`${key}: must be a string`);
+            continue;
+        }
+        if (value === '') continue;
+        if (/[+#]/.test(value)) problems.push(`${key}: no MQTT wildcards in a template`);
+        if (/^\/|\/\/|\/$/.test(value)) problems.push(`${key}: empty topic segment`);
+        for (const ph of placeholdersOf(value)) if (!PLACEHOLDERS.includes(ph)) problems.push(`${key}: unknown placeholder \${${ph}}`);
+        if (INBOUND.includes(key) && !placeholdersOf(value).includes('device') && !placeholdersOf(value).includes('nodeId'))
+            problems.push(`${key}: needs \${device} or \${nodeId}`);
+    }
+    const flagged = new Set(problems.map((p) => p.split(':')[0]));
+    const sample = { device: 'sample_device', nodeId: '7', endpoint: '1', cluster: 'on_off', attribute: 'on_off', event: 'initial_press', attributeOrCommand: 'on_off' };
+    for (const inKey of INBOUND) {
+        if (!t[inKey] || flagged.has(inKey)) continue;
+        for (const outKey of OUTBOUND) {
+            if (!t[outKey] || flagged.has(outKey)) continue;
+            if (mqttWildcard(fill(t[outKey], sample), toPattern(t[inKey])) !== null) problems.push(`${inKey} overlaps ${outKey}: she would answer its own ${outKey} topics`);
+        }
+    }
+    if (t.set && t.get && t.set === t.get) problems.push('set and get are the same template');
+    return problems;
+}
+
+/** The outbound payload for a value in the chosen format. */
+function formatPayload(format, val, { ts, lc, matter } = {}) {
+    const v = val;
+    switch (format) {
+        case 'plain':
+            return typeof v === 'string' ? v : JSON.stringify(v);
+        case 'extended':
+            return JSON.stringify({ val: v, ts, lc, matter });
+        case 'basic':
+        default:
+            return JSON.stringify({ val: v, ts, lc });
+    }
+}
+
+/** An inbound payload: `{"val": …}` or a plain value (JSON when it parses, else the string). */
+function parseInbound(payload) {
+    const s = Buffer.isBuffer(payload) ? payload.toString('utf8') : String(payload ?? '');
+    if (s === '') return '';
+    try {
+        const parsed = JSON.parse(s);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && 'val' in parsed) return parsed.val;
+        return parsed;
+    } catch {
+        return s;
+    }
+}
+
+/** Commands behind an attribute `set` (D: on/off, level, blinds, colour temperature). */
+const MAPPED = {
+    'onOff/onOff': (val) => {
+        if (val === 'toggle') return { command: 'toggle' };
+        return { command: truthy(val) ? 'on' : 'off' };
+    },
+    'levelControl/currentLevel': (val) => ({ command: 'moveToLevel', args: { level: Number(val), transitionTime: 0 } }),
+    'windowCovering/currentPositionLiftPercent100ths': (val) => ({ command: 'goToLiftPercentage', args: { liftPercent100thsValue: Number(val) } }),
+    'windowCovering/currentPositionTiltPercent100ths': (val) => ({ command: 'goToTiltPercentage', args: { tiltPercent100thsValue: Number(val) } }),
+    'colorControl/colorTemperatureMireds': (val) => ({ command: 'moveToColorTemperature', args: { colorTemperatureMireds: Number(val), transitionTime: 0 } }),
+};
+
+function truthy(val) {
+    if (typeof val === 'string') return !['', '0', 'false', 'off', 'no'].includes(val.trim().toLowerCase());
+    return !!val;
+}
+
+/**
+ * What a `set` on `<cluster>/<attributeOrCommand>` does: a mapped command, the command of that
+ * name with the payload object as its fields, or an attribute write.
+ * @param {string} cluster   camelCase
+ * @param {string} name      camelCase attribute or command name
+ * @param {*} val            the parsed payload
+ * @param {{ commands?: object, attributes?: object }} clusterDef  the matter.js cluster definition (Complete)
+ * @returns {{ kind: 'command', command: string, args?: object } | { kind: 'write', attribute: string, value: * }}
+ */
+function resolveSet(cluster, name, val, clusterDef) {
+    const mapped = MAPPED[`${cluster}/${name}`];
+    if (mapped) return { kind: 'command', ...mapped(val) };
+    const commands = clusterDef?.commands ?? {};
+    const attributes = clusterDef?.attributes ?? {};
+    if (commands[name]) return { kind: 'command', command: name, args: val && typeof val === 'object' && !Array.isArray(val) ? val : {} };
+    if (attributes[name]) return { kind: 'write', attribute: name, value: val };
+    throw new Error(`"${name}" is neither a command nor an attribute of cluster "${cluster}"`);
+}
+
+module.exports = {
+    DEFAULT_TEMPLATES,
+    OUTBOUND,
+    INBOUND,
+    PLACEHOLDERS,
+    FORMATS,
+    DENY_CLUSTERS,
+    DENY_ATTRIBUTES,
+    snake,
+    camel,
+    mqttName,
+    uniqueName,
+    placeholdersOf,
+    fill,
+    toPattern,
+    match,
+    validate,
+    formatPayload,
+    parseInbound,
+    resolveSet,
+    truthy,
+};