node-red-contrib-room-tools 1.8.2 → 1.8.3

package/managed-bridge-admin.js

@@ -0,0 +1,90 @@
+const crypto = require('node:crypto')
+const fs = require('node:fs')
+const path = require('node:path')
+
+function flowDigest (flows) {
+  return crypto.createHash('sha256').update(JSON.stringify(flows)).digest('hex')
+}
+
+function localDirectory (userDir, remoteAddress) {
+  const address = String(remoteAddress || '')
+  if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(address)) {
+    throw new Error('Managed bridge editor is restricted to a local request')
+  }
+  return fs.realpathSync(userDir)
+}
+
+function regularFile (file) {
+  return fs.existsSync(file) && fs.lstatSync(file).isFile()
+}
+
+function flowLocation (directory) {
+  if (directory.includes(`${path.sep}local-validation${path.sep}`)) {
+    const flowFile = path.join(directory, 'flows.json')
+    if (!regularFile(flowFile)) throw new Error('Local-validation Flow file is missing')
+    return { flowFile, credentialFile: path.join(directory, 'flows_cred.json'),
+      backupRoot: path.join(directory, 'managed-bridge-backups') }
+  }
+
+  const configFile = path.join(directory, '.config.projects.json')
+  if (!regularFile(configFile)) {
+    throw new Error('Managed bridge editor requires a local-validation directory or an active Node-RED project')
+  }
+  const config = JSON.parse(fs.readFileSync(configFile, 'utf8'))
+  const name = config.activeProject
+  if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) ||
+    !Object.hasOwn(config.projects || {}, name)) {
+    throw new Error('Active Node-RED project is missing or invalid')
+  }
+  const projectsRoot = fs.realpathSync(path.join(directory, 'projects'))
+  if (path.dirname(projectsRoot) !== directory) throw new Error('Projects directory escapes the user directory')
+  const projectPath = path.join(projectsRoot, name)
+  if (!fs.lstatSync(projectPath).isDirectory()) throw new Error('Active project must be a directory')
+  const projectDir = fs.realpathSync(projectPath)
+  if (path.dirname(projectDir) !== projectsRoot) throw new Error('Active project escapes the projects directory')
+  const packageFile = path.join(projectDir, 'package.json')
+  if (!regularFile(packageFile)) throw new Error('Active project package.json is missing')
+  const settings = JSON.parse(fs.readFileSync(packageFile, 'utf8'))['node-red']?.settings
+  const validName = name => typeof name === 'string' &&
+    /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/.test(name) && path.basename(name) === name
+  if (!validName(settings?.flowFile) || !validName(settings?.credentialsFile) ||
+    settings.flowFile === settings.credentialsFile) {
+    throw new Error('Active project must declare safe flowFile and credentialsFile names')
+  }
+  const flowFile = path.join(projectDir, settings.flowFile)
+  const credentialFile = path.join(projectDir, settings.credentialsFile)
+  if (!regularFile(flowFile)) throw new Error('Active project Flow file is missing or unsafe')
+  if (fs.existsSync(credentialFile) && !regularFile(credentialFile)) {
+    throw new Error('Active project credentials file must be a regular file')
+  }
+  return { flowFile, credentialFile,
+    backupRoot: path.join(directory, 'managed-bridge-backups', name) }
+}
+
+function privateDirectory (directory) {
+  if (fs.existsSync(directory)) {
+    if (!fs.lstatSync(directory).isDirectory()) throw new Error('Bridge backup path must be a directory')
+  } else {
+    fs.mkdirSync(directory, { mode: 0o700 })
+  }
+}
+
+function backupFlow (location, rev, flows) {
+  const parent = path.dirname(location.backupRoot)
+  if (parent !== path.dirname(location.flowFile)) privateDirectory(parent)
+  privateDirectory(location.backupRoot)
+  const backupDir = path.join(location.backupRoot,
+    new Date().toISOString().replace(/[:.]/g, '-') + '-' + crypto.randomBytes(3).toString('hex'))
+  fs.mkdirSync(backupDir, { mode: 0o700 })
+  fs.writeFileSync(path.join(backupDir, 'api-flows.json'), JSON.stringify({ rev, flows }, null, 2),
+    { flag: 'wx', mode: 0o600 })
+  for (const file of [location.flowFile, location.credentialFile]) {
+    if (!regularFile(file)) continue
+    const target = path.join(backupDir, path.basename(file))
+    fs.copyFileSync(file, target)
+    fs.chmodSync(target, 0o600)
+  }
+  return backupDir
+}
+
+module.exports = { backupFlow, flowDigest, localDirectory, flowLocation }

package/managed-bridge-revision.js

@@ -0,0 +1,32 @@
+const crypto = require('node:crypto')
+const { configuredRoutes } = require('./control-bound-protocol')
+
+function canonical (value) {
+  if (Array.isArray(value)) return value.map(canonical)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+  }
+  return value
+}
+
+function managedBridgeRevision (panel) {
+  const routes = [...configuredRoutes(panel)].map(([id, { control, binding }]) => ({
+    id,
+    type: control.type,
+    mode: control.mode,
+    device: binding?.device || '',
+    readPath: binding?.readPath || '',
+    writePath: binding?.writePath || '',
+    readMeta: binding?.readMeta || null,
+    writeMeta: binding?.writeMeta || null
+  })).sort((a, b) => a.id.localeCompare(b.id))
+  const payload = canonical({
+    panelId: panel.id,
+    room: panel.boundRoom,
+    nativeBridge: panel.nativeBridge === true,
+    routes
+  })
+  return `v1:${crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex')}`
+}
+
+module.exports = { managedBridgeRevision }

package/managed-native-bridge.js

@@ -0,0 +1,124 @@
+const crypto = require('node:crypto')
+const { configuredRoutes } = require('./control-bound-protocol')
+const { compileNativeBindingPlan } = require('./native-binding-plan')
+const { managedBridgeRevision } = require('./managed-bridge-revision')
+
+const MARKER = 'control-panel-managed-v1'
+
+function digest (value) {
+  return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+function panelTargets (panel) {
+  const targets = new Map()
+  for (const [id, { control, binding }] of configuredRoutes(panel)) {
+    if (!binding?.device) throw new Error(`Missing device binding: ${id}`)
+    for (const direction of ['read', 'write']) {
+      if ((direction === 'read' && control.mode === 'write') ||
+        (direction === 'write' && control.mode === 'read')) continue
+      const path = binding[`${direction}Path`]
+      const meta = binding[`${direction}Meta`]
+      if (!path || !meta || typeof meta !== 'object' || Array.isArray(meta)) {
+        throw new Error(`Missing ${direction} target metadata: ${id}`)
+      }
+      const target = {
+        device: binding.device, path, kind: meta.kind, type: meta.type,
+        access: meta.access, onebased: meta.onebased,
+        ...(meta.booleanEncoding ? { booleanEncoding: meta.booleanEncoding } : {})
+      }
+      const key = JSON.stringify([target.device, target.path])
+      const previous = targets.get(key)
+      if (previous && digest(previous) !== digest(target)) {
+        throw new Error(`Conflicting target metadata: ${target.device} ${target.path}`)
+      }
+      targets.set(key, target)
+    }
+  }
+  return [...targets.values()]
+}
+
+function generatedBridge (panel) {
+  const scopeId = `cp${digest(panel.id).slice(0, 12)}`
+  const { nodes, manifest } = compileNativeBindingPlan({ panel, targets: panelTargets(panel), scopeId })
+  const subflow = nodes[0]
+  subflow.info = `${MARKER}:${panel.id}:${digest(nodes.slice(1))}`
+  const instanceId = `${scopeId}-instance`
+  const instance = {
+    id: instanceId,
+    type: `subflow:${manifest.subflowId}`,
+    z: panel.z,
+    name: `Managed bridge for ${panel.id}`,
+    x: Number(panel.x || 200) + 240,
+    y: Number(panel.y || 200),
+    wires: manifest.nativeReads ? [[panel.id]] : []
+  }
+  return { nodes, instance, manifest, scopeId }
+}
+
+function removeBridgeNodes (flows, subflowId, instanceId) {
+  const removeIds = new Set([subflowId, instanceId])
+  for (const node of flows) {
+    if (node.z === subflowId || node.type === `subflow:${subflowId}`) {
+      removeIds.add(node.id)
+    }
+  }
+
+  // Remove references from any remaining node before the generated bridge is
+  // replaced. The panel itself is assigned its new wire immediately after.
+  for (const node of flows) {
+    if (removeIds.has(node.id) || !Array.isArray(node.wires)) continue
+    node.wires = node.wires.map(port => Array.isArray(port)
+      ? port.filter(id => !removeIds.has(id))
+      : port)
+  }
+
+  for (let index = flows.length - 1; index >= 0; index--) {
+    if (removeIds.has(flows[index].id)) flows.splice(index, 1)
+  }
+}
+
+function provisionManagedBridges (currentFlows, options = {}) {
+  if (!Array.isArray(currentFlows)) throw new Error('Expected a Node-RED Flow array')
+  const flows = structuredClone(currentFlows)
+  const scopedPanelId = options.panelId || null
+  const owners = flows.filter(node => node.type === 'ui-control-panel' && node.nativeBridge === true &&
+    (!scopedPanelId || node.id === scopedPanelId))
+  const updated = []
+  for (const panel of owners) {
+    if (!panel.id || !panel.z) throw new Error('Managed panel needs an ID and Flow tab')
+    const bridge = generatedBridge(panel)
+    const revision = managedBridgeRevision(panel)
+    const { nodes, instance, manifest, scopeId } = bridge
+    const subflowId = manifest.subflowId
+
+    // The bridge is derived state. Always remove the complete previous
+    // generation for this panel, including moved or older-version nodes.
+    removeBridgeNodes(flows, subflowId, instance.id)
+    panel.wires = [[instance.id]]
+    panel.bridgeRevisionApplied = revision
+    flows.push(...nodes, instance)
+    updated.push({ panelId: panel.id, room: panel.boundRoom, controls: manifest.controls,
+      reads: manifest.nativeReads, writes: manifest.nativeWrites, scopeId })
+  }
+  for (const subflow of [...flows]) {
+    if (subflow.type !== 'subflow' || typeof subflow.info !== 'string' ||
+      !subflow.info.startsWith(`${MARKER}:`)) continue
+    const match = subflow.info.match(/^control-panel-managed-v1:([^:]+):([a-f0-9]{64})$/)
+    if (!match) continue
+    const ownerId = match[1]
+    if (scopedPanelId && ownerId !== scopedPanelId) continue
+    if (owners.some(panel => panel.id === ownerId)) continue
+    const scopeId = `cp${digest(ownerId).slice(0, 12)}`
+    const instanceId = `${scopeId}-instance`
+    const oldPanel = flows.find(node => node.id === ownerId)
+    if (oldPanel) {
+      oldPanel.wires = [[]]
+      oldPanel.bridgeRevisionApplied = ''
+    }
+    removeBridgeNodes(flows, subflow.id, instanceId)
+    updated.push({ panelId: ownerId, removed: true })
+  }
+  return { flows, updated, managedPanels: owners.length }
+}
+
+module.exports = { panelTargets, generatedBridge, provisionManagedBridges }

package/native-binding-plan.js

@@ -0,0 +1,177 @@
+const { configuredRoutes } = require('./control-bound-protocol')
+
+const supportedTypes = {
+  boolean: { eventType: 'Boolean', eventOptions: { boolParamFilter: 'Any' } },
+  integer: { eventType: 'Integer', eventOptions: { normalized: false } },
+  float: { eventType: 'Float', eventOptions: { normalized: false } },
+  string: { eventType: 'String', eventOptions: {} },
+  dstring: { eventType: 'DString (comma separated string)', eventOptions: {} },
+  enum: { eventType: 'Enumeration', eventOptions: {} }
+}
+
+function compileNativeBindingPlan ({ panel, targets, scopeId }) {
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,48}$/.test(scopeId || '')) {
+    throw new Error('A unique, stable scopeId is required')
+  }
+  if (!Array.isArray(targets)) throw new Error('Target descriptors are required')
+  const routes = configuredRoutes(panel)
+  if (!routes.size) throw new Error('No visual bindings to compile')
+
+  const targetIndex = new Map()
+  for (const target of targets) {
+    const key = JSON.stringify([target.device, target.path])
+    if (targetIndex.has(key)) throw new Error(`Duplicate target descriptor: ${key}`)
+    targetIndex.set(key, target)
+  }
+
+  const subflowId = `${scopeId}-bridge`
+  const nodes = []
+  const readTargets = new Map()
+  const writeTargets = new Map()
+  const commandRules = []
+  const commandWires = []
+
+  function metadata (device, path, type, access) {
+    const target = targetIndex.get(JSON.stringify([device, path]))
+    if (!target) throw new Error(`Missing target descriptor: ${device} ${path}`)
+    if (target.kind !== 'param') throw new Error(`Only parameter targets are supported: ${path}`)
+    if (!Object.hasOwn(supportedTypes, target.type)) {
+      throw new Error(`Unsupported native parameter type: ${path} (${target.type})`)
+    }
+    if (['mute', 'power'].includes(type) && target.type !== 'boolean' &&
+      !(target.type === 'integer' && target.booleanEncoding === 'integer01')) {
+      throw new Error(`Boolean control bound to ${target.type}: ${path}`)
+    }
+    if (['level', 'dimmer', 'position'].includes(type) && !['integer', 'float'].includes(target.type)) {
+      throw new Error(`Numeric control bound to ${target.type}: ${path}`)
+    }
+    if (type === 'text' && !['string', 'dstring'].includes(target.type)) {
+      throw new Error(`Text control bound to ${target.type}: ${path}`)
+    }
+    if (['source', 'preset'].includes(type) && !['enum', 'integer', 'string'].includes(target.type)) {
+      throw new Error(`Choice control bound to ${target.type}: ${path}`)
+    }
+    if (!['mute', 'power', 'level', 'dimmer', 'position', 'text', 'source', 'preset'].includes(type)) {
+      throw new Error(`Control type requires a separate command adapter: ${type}`)
+    }
+    if (!['ro', 'wo', 'rw'].includes(target.access) || !target.access.includes(access)) {
+      throw new Error(`Target is not ${access === 'r' ? 'readable' : 'writable'}: ${path}`)
+    }
+    if (typeof target.onebased !== 'boolean') {
+      throw new Error(`Target numbering mode is required: ${path}`)
+    }
+    return target
+  }
+
+  for (const [id, { control, binding }] of routes) {
+    if (!binding?.device) throw new Error(`Missing device binding: ${id}`)
+    if (control.mode !== 'read') {
+      if (!binding.writePath) throw new Error(`Missing write path: ${id}`)
+      const target = metadata(binding.device, binding.writePath, control.type, 'w')
+      const key = JSON.stringify([target.device, target.path])
+      if (!writeTargets.has(key)) {
+        const nodeId = `${scopeId}-write-${writeTargets.size + 1}`
+        writeTargets.set(key, nodeId)
+        nodes.push({
+          id: nodeId, type: 'Command', z: subflowId,
+          name: `Write ${target.device} ${target.path}`,
+          x: 1860, y: 10 + writeTargets.size * 110,
+          mojo: { version: '1.0', device: [target.device], command: target.path,
+            onebased: target.onebased, cmdvalue: 'Message payload' },
+          wires: [[]]
+        })
+      }
+      commandRules.push({ t: 'eq', v: id, vt: 'str' })
+      commandWires.push([writeTargets.get(key)])
+    }
+
+    if (control.mode !== 'write') {
+      if (!binding.readPath) throw new Error(`Missing read path: ${id}`)
+      const target = metadata(binding.device, binding.readPath, control.type, 'r')
+      const key = JSON.stringify([target.device, target.path])
+      if (readTargets.has(key)) continue
+      const index = readTargets.size + 1
+      const statusId = `${scopeId}-read-${index}`
+      const eventId = `${scopeId}-watch-${index}`
+      const tagId = `${scopeId}-tag-${index}`
+      readTargets.set(key, { statusId, eventId, tagId })
+      const event = supportedTypes[target.type]
+      nodes.push({
+        id: statusId, type: 'Status', z: subflowId,
+        name: `Read ${target.device} ${target.path}`,
+        x: 440, y: 360 + index * 170,
+        mojo: { version: '1.0', device: [target.device], parameter: target.path,
+          onebased: target.onebased },
+        wires: [[tagId]]
+      })
+      nodes.push({
+        id: eventId, type: 'Event', z: subflowId,
+        name: `Watch ${target.device} ${target.path}`,
+        x: 440, y: 420 + index * 170,
+        mojo: { version: '1.0', device: [target.device], event: target.path,
+          eventKind: 'Parameter', paramType: event.eventType,
+          onebased: target.onebased, ...event.eventOptions },
+        wires: [[tagId]]
+      })
+      nodes.push({
+        id: tagId, type: 'change', z: subflowId,
+        name: `Identify ${target.device} ${target.path}`,
+        x: 900, y: 390 + index * 170,
+        rules: [
+          { t: 'set', p: 'kind', pt: 'msg', to: 'device-feedback', tot: 'str' },
+          { t: 'set', p: 'device', pt: 'msg', to: target.device, tot: 'str' },
+          { t: 'set', p: 'path', pt: 'msg', to: target.path, tot: 'str' }
+        ],
+        wires: [[]]
+      })
+    }
+  }
+
+  const commandSwitchId = `${scopeId}-commands`
+  const routerId = `${scopeId}-router`
+  if (commandRules.length) {
+    nodes.push({
+      id: commandSwitchId, type: 'switch', z: subflowId,
+      name: 'Control ID', property: 'controlId', propertyType: 'msg',
+      x: 1440, y: 140,
+      rules: commandRules, checkall: 'false', repair: false,
+      outputs: commandRules.length, wires: commandWires
+    })
+  }
+  nodes.push({
+    id: routerId, type: 'switch', z: subflowId,
+    name: 'Command or initial read', property: 'kind', propertyType: 'msg',
+    x: 430, y: 150,
+    rules: [
+      { t: 'eq', v: 'bound-command', vt: 'str' },
+      { t: 'eq', v: 'read-all', vt: 'str' }
+    ],
+    checkall: 'false', repair: false, outputs: 2,
+    wires: [commandRules.length ? [commandSwitchId] : [],
+      [...readTargets.values()].map(target => target.statusId)]
+  })
+  const subflow = {
+    id: subflowId, type: 'subflow', name: `Binding bridge ${scopeId}`,
+    info: 'Generated local PoC. Requires a Controller node and authenticated command source.',
+    category: 'panel binding',
+    in: [{ x: 170, y: 150, wires: [{ id: routerId }] }],
+    out: readTargets.size
+      ? [{ x: 1290, y: Math.round((390 + (readTargets.size + 1) * 85) / 10) * 10,
+        wires: [...readTargets.values()].map(target => ({ id: target.tagId, port: 0 })) }]
+      : [],
+    env: [], meta: {}, color: '#96bca7'
+  }
+  return {
+    nodes: [subflow, ...nodes],
+    manifest: {
+      subflowId,
+      controls: routes.size,
+      nativeReads: readTargets.size,
+      nativeWrites: writeTargets.size,
+      requiresController: true,
+      initialReadMessage: { kind: 'read-all' }
+    }
+  }
+}
+
+module.exports = { compileNativeBindingPlan }

package/package.json

@@ -1,18 +1,40 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "Room panel message generator and authenticated region gateway for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
-  "keywords": ["node-red"],
+  "keywords": [
+    "node-red"
+  ],
   "dependencies": {
+    "@vue/compiler-sfc": "^3.5.42",
     "acorn": "^8.15.0",
     "escodegen": "^2.1.0"
   },
-  "files": ["gateway.cjs", "room-gateway.js", "room-gateway.html", "room-message.js", "room-message.html", "control-panel.js", "control-panel.html", "control-policy.js", "CONTROL_PANEL_AI_GUIDE.md", "README.md"],
+  "files": [
+    "assets/panel-login-bg.png",
+    "gateway.cjs",
+    "control-panel.js",
+    "control-panel.html",
+    "control-bound-protocol.js",
+    "control-catalog.js",
+    "control-type-contract.json",
+    "control-type-model.js",
+    "panel-template-instrumentation.js",
+    "panel-visual-bindings.js",
+    "panel-visual-apply.js",
+    "panel-editor-auth.js",
+    "panel-binding-editor.js",
+    "native-binding-plan.js",
+    "managed-native-bridge.js",
+    "managed-bridge-revision.js",
+    "managed-bridge-admin.js",
+    "control-policy.js",
+    "CONTROL_PANEL_AI_GUIDE.md",
+    "README.md"
+  ],
   "node-red": {
     "nodes": {
-      "room-gateway": "room-gateway.js",
-      "room-message": "room-message.js",
       "ui-control-panel": "control-panel.js"
     }
   }