homebridge-ecobee-security 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.0
+
+- The `pollInterval` setting is gone: the security state is read every 10 s, as often as the ecobee
+  app does (it has no live updates either). A value left in the config is ignored.
+- Settings: the whole page is now cards (account, Security system, Sensors, Security holds), with
+  **Security holds** at the bottom; the standard settings form is no longer shown.
+- Settings: a **Security holds** section with the **Allow security holds** switch and a checkbox per
+  plugin (`holdPlugins`): installed plugins that declare they use holds, and any that asked. Hold
+  requests can name their plugin (`&plugin=<package>`); unticked plugins are refused.
+- Declares the hold socket in package.json (`"homebridge-security-hold": { "socket": … }`), so
+  plugins that support the hold, like homebridge-narwal-freo, list it in their settings.
+- Hold API: several plugins (e.g. two robot vacuums) can hold Stay at once; Away comes back only
+  when the last one releases. `/release` answers `waiting: [names]` while others still hold.
+- New setting **Allow security holds** (`allowHolds`, off by default): other plugins can only hold
+  Stay with it turned on; otherwise `/hold` and `/release` answer 403 with the reason, and a hold
+  left over from before is dropped without re-arming Away. **If you use homebridge-narwal-freo's
+  security hold, turn this on and tick Narwal Freo.**
+- Hold and release decide on ecobee's live state, read at the moment of the request, not the last
+  poll: a disarm in the ecobee app seconds before a robot finishes is no longer armed over with
+  Away. If ecobee can't be read, a hold is refused and a release doesn't arm (the caller retries).
+
 ## 0.4.2
 
 - New plugin icon.

package/README.md

@@ -58,10 +58,10 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
   "platform": "EcobeeSecurityPlatform",
   "name": "Security System",
   "refreshToken": "…",
-  "pollInterval": 10,
   "offerNight": false,
   "alarmTrigger": "incident",
   "smokeSensor": true,
+  "allowHolds": false,
   "airQuality": true,
   "co2Alert": 1000,
   "_bridge": { "username": "…", "port": 51926, "name": "Ecobee Security Bridge" }
@@ -75,6 +75,7 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
 | `offerNight` | `false` | Adds Night to the Home app. ecobee has no Night mode, so Night arms Stay and the tile keeps showing Night until the state changes (a Stay armed elsewhere shows as Stay). HomeKit only picks up a changed list of modes on a new control, so changing this setting recreates the security system in the Home app: set up scenes and automations that use it again. |
 | `alarmTrigger` | `"incident"` | When the tile enters **Triggered**: `"incident"` immediately, when ecobee opens an incident as a door or sensor trips while armed (mirrors the ecobee app); `"entryDelay"` only after the entry (disarm) delay runs out without a disarm. Smoke alarms always trigger immediately. |
 | `smokeSensor` | `true` | Adds a separate **Smoke Alarm** accessory (a Smoke Sensor) that detects smoke while ecobee has a smoke-alarm incident open, for automations and Home app smoke notifications. Set to `false` to remove it. |
+| `allowHolds` | `false` | Lets other Homebridge plugins ask for a **security hold** (see below), e.g. so a robot vacuum can clean while you're away without setting off the motion sensors. Off: hold requests are refused, and a hold left over from before is dropped without re-arming Away. |
 | `airQuality` | `true` | For each thermostat with an air quality sensor: an accessory "&lt;thermostat&gt; Air Quality" with an **Air Quality Sensor** (overall level; VOC as ecobee reports it, in ppb, which the Home app labels µg/m³) and a **Carbon Dioxide Sensor** (ppm). Read every 5 minutes. The level follows the ecobee app's Clean–Poor bar: its first two segments are Excellent, then Good, Fair, Inferior, Poor; Unknown while the sensor calibrates. |
 | `co2Alert` | `1000` | CO2 (ppm) at or above which the Carbon Dioxide Sensor reports abnormal levels. |
 
@@ -83,19 +84,64 @@ node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
 - **Arm Away** uses ecobee's Away exit delay (60 s by default), just like the app. During the
   delay the Home app shows "Arming…" (current Disarmed, target Away). Stay uses the Stay exit delay
   (0 by default). Disarm needs no PIN.
-- **Changes from elsewhere** (ecobee app, keypad, ecobee automations) show up within the poll
-  interval (10 s by default), and quickly after an exit delay ends.
+- **Changes from elsewhere** (ecobee app, keypad, ecobee automations) show up within 10 s, about
+  as fast as in the ecobee app (it polls too), and quickly after an exit delay ends.
 - **Alarm triggered** while ecobee lists an open incident (see `alarmTrigger` above for when it
   starts showing). Disarming clears it. Every change in the incident list is logged.
 - **Siri:** the Home app calls Stay "Home". Asking Siri for Home or for Stay mode both arm Stay.
 - **Night** is only offered with `offerNight`; ecobee has no Night mode of its own.
 - After three failed reads in a row the accessory shows a fault; reads back off up to 5 minutes.
-- **Hold for other plugins:** a Unix socket at `<homebridge storage>/ecobee-security/control.sock`
-  (mode 600, homebridge user only) lets another plugin, e.g. homebridge-narwal, ask for a temporary
-  Stay: `POST /hold?by=<name>` switches Away (or arming Away) to Stay and remembers it;
-  `POST /release?by=<name>` arms Away again — unless the state was changed by anyone in between, in
-  which case the hold is just dropped. The hold survives restarts (in `state.json`). `/hold`
-  answers `ok: false` when the alarm is triggered or the state is unknown.
+- **Security holds** for other plugins, with `allowHolds`: see below.
+
+## Security holds
+
+A security hold lets another Homebridge plugin, such as a robot vacuum, keep the motion sensors from
+going off while it moves around the house when you're away. The plugin can only *ask*; this plugin
+decides, by four rules:
+
+1. **Hold:** if the system is armed Away (or arming Away), it's switched to Stay. If an alarm is in
+   progress, or ecobee can't be read, the hold is refused. Otherwise nothing changes.
+2. **Release:** once **every** plugin that asked is done, and the system is still in Stay, it's
+   armed Away again (with the normal exit delay).
+3. **Your change wins:** anything someone else does during a hold — disarm, arm Away, a change in
+   the Home app, an alarm — cancels it, and the system is left as it is.
+4. **No timers:** nothing changes unless a plugin asks or you act.
+
+Every decision uses ecobee's state read at that moment, not the last poll. Holds are off until you
+turn on **Allow security holds** in the settings' **Security holds** section and tick each plugin that
+may ask (`holdPlugins`): it lists installed plugins that declare they use holds, and any plugin that
+has asked. A plugin that isn't ticked is refused (it can still release a hold it already has).
+Turning holds off drops a hold left over from before (without arming Away).
+
+**Limits** that follow from these rules:
+
+- **Your own Stay looks like the hold's Stay.** If you disarm and re-arm Stay in the ecobee app or at
+  the keypad within a few seconds (between two reads), or while the bridge is restarting, the
+  release still arms Away: ecobee doesn't say who last changed the state. Changes in the Home app are
+  always seen.
+- **Your change wins even with a robot still out.** After you cancel a hold (say, disarm), arming
+  Away while the robot is still cleaning can set off the motion sensors: a plugin only asks for a
+  hold when it starts.
+- **Plugins identify themselves.** Any plugin running as the homebridge user can reach the socket,
+  and the plugin name it gives is its own claim: the list keeps honest plugins apart, it isn't a
+  lock. Two requests with the same name share one hold.
+- **A plugin that never releases leaves the system in Stay** until you change it.
+
+**API** (for plugin authors): a Unix socket at `<homebridge storage>/ecobee-security/control.sock`
+(mode 600, homebridge user only), declared in `package.json` as
+`"homebridge-security-hold": { "socket": "ecobee-security/control.sock" }` so plugins that support
+holds, like homebridge-narwal-freo, can list it. Plugins that ask for holds can declare
+`"homebridge-security-hold": { "client": true }` to show up in the list before their first request.
+The full API: [Security hold](https://github.com/seanfletchr/homebridge-narwal-freo/blob/main/docs/security-hold.md).
+
+- `POST /hold?by=<name>&plugin=<package>` → `{ "ok": true, "held": true|false, "state": "…" }`,
+  or `"ok": false` with a `"reason"`: don't start. `plugin` is optional; without it the plugin is
+  listed (and allowed) under its `by` name.
+- `POST /release?by=<name>&plugin=<package>` → `{ "released": true|false, "state": "…", "waiting": [names] }`;
+  `waiting` lists holders still out.
+- With `allowHolds` off or the plugin not ticked, both answer 403 (a release from a current holder
+  is always accepted); if ecobee can't be read (release) or isn't connected
+  yet, a 5xx with `"error"` — try again later. Holds survive restarts (in `state.json`).
 
 ## API notes
 

package/config.schema.json

@@ -26,18 +26,11 @@
         "type": "string",
         "description": "Only needed if the account has more than one home; the log lists them."
       },
-      "pollInterval": {
-        "title": "Check every (seconds)",
-        "type": "integer",
-        "default": 10,
-        "minimum": 5,
-        "description": "How often to read the armed state, so changes made in the ecobee app or at the keypad show up in Apple Home."
-      },
       "offerNight": {
         "title": "Offer Night",
         "type": "boolean",
         "default": false,
-        "description": "Adds Night to the Home app, for automations or Siri that use it. ecobee has no Night mode, so Night arms Stay; the Home app keeps showing Night until the state changes. Changing this setting recreates the security system in the Home app, so scenes and automations that use it have to be set up again."
+        "description": "Adds the Night setting for more specific automations. ecobee has no \"Night\" mode, so Night arms Stay. Changing this recreates the security system in the Home app; scenes and automations using it must be set up again."
       },
       "alarmTrigger": {
         "title": "Enter Triggered State",
@@ -65,6 +58,20 @@
         "default": true,
         "description": "Adds a separate \"Smoke Alarm\" accessory to the Home app that detects smoke whenever ecobee reports a smoke-alarm incident, so you can use it in automations and get Home app smoke notifications."
       },
+      "allowHolds": {
+        "title": "Allow security holds",
+        "type": "boolean",
+        "default": false,
+        "description": "Lets other Homebridge plugins (for example a robot vacuum, so it can clean while you're away) switch Away to Stay for a while and back to Away when they're done. Each plugin also has to be allowed in holdPlugins (the settings page lists the ones that asked). See \"Security holds\" in the README."
+      },
+      "holdPlugins": {
+        "title": "Plugins allowed to ask for holds",
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Package names (or, for a plugin that doesn't say, the name it asks with). Without this list, every plugin may ask once Allow security holds is on."
+      },
       "airQuality": {
         "title": "Air quality sensors",
         "type": "boolean",

package/homebridge-ui/public/index.html

@@ -56,6 +56,72 @@
   </div>
 </div>
 
+
+<div class="card card-body mb-3" id="system-card" hidden>
+  <h5 class="mb-3">Security system</h5>
+  <div class="mb-3">
+    <label for="s-name" class="form-label">Name</label>
+    <input class="form-control" type="text" id="s-name" data-key="name" data-type="text" data-default="Security System">
+    <div class="hint mt-1">Name shown in the Home app.</div>
+  </div>
+  <div class="mb-3">
+    <label for="s-homeId" class="form-label">Home ID</label>
+    <input class="form-control" type="text" id="s-homeId" data-key="homeId" data-type="text" data-default="">
+    <div class="hint mt-1">Only needed if the account has more than one home; the log lists them.</div>
+  </div>
+  <div class="mb-3">
+    <div class="form-check form-switch">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-offerNight" data-key="offerNight" data-type="bool" data-default="false">
+      <label class="form-check-label" for="s-offerNight">Offer Night</label>
+    </div>
+    <div class="hint">Adds the Night setting for more specific automations. ecobee has no "Night" mode, so Night arms Stay.</div>
+    <div class="hint mt-1">Changing this recreates the security system in the Home app; scenes and automations using it must be set up again.</div>
+  </div>
+  <div class="mb-0">
+    <label for="s-alarmTrigger" class="form-label">Enter Triggered State</label>
+    <select class="form-select" id="s-alarmTrigger" data-key="alarmTrigger" data-type="select" data-default="incident"><option value="incident">Immediately (mirror ecobee app)</option><option value="entryDelay">After the Entry/Disarm delay</option></select>
+    <div class="hint mt-1">ecobee opens an incident as soon as a door or sensor trips while armed. "After the Entry/Disarm delay" waits until that delay runs out without a disarm, so automations on Triggered don't fire while you're walking in to disarm. Smoke alarms always trigger immediately.</div>
+  </div>
+</div>
+
+<div class="card card-body mb-3" id="sensors-card" hidden>
+  <h5 class="mb-3">Sensors</h5>
+  <div class="mb-3">
+    <div class="form-check form-switch">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-smokeSensor" data-key="smokeSensor" data-type="bool" data-default="true">
+      <label class="form-check-label" for="s-smokeSensor">Smoke sensor</label>
+    </div>
+    <div class="hint">Adds a separate "Smoke Alarm" accessory to the Home app that detects smoke whenever ecobee reports a smoke-alarm incident, so you can use it in automations and get Home app smoke notifications.</div>
+  </div>
+  <div class="mb-3">
+    <div class="form-check form-switch">
+      <input class="form-check-input" type="checkbox" role="switch" id="s-airQuality" data-key="airQuality" data-type="bool" data-default="true">
+      <label class="form-check-label" for="s-airQuality">Air quality sensors</label>
+    </div>
+    <div class="hint">For ecobee thermostats with an air quality sensor (ecobee Premium): adds an Air Quality Sensor (overall level and VOC) and a Carbon Dioxide Sensor (CO2 in ppm) per thermostat. ecobee's own HomeKit integration doesn't show these. Updated every 5 minutes.</div>
+  </div>
+  <div class="mb-0" id="co2-box">
+    <label for="s-co2Alert" class="form-label">CO2 alert level (ppm)</label>
+    <input class="form-control" type="number" step="1" min="400" id="s-co2Alert" data-key="co2Alert" data-type="int" data-default="1000">
+    <div class="hint mt-1">The Carbon Dioxide Sensor reports abnormal CO2 at or above this level, for Home app notifications and automations (for example, turning on ventilation).</div>
+  </div>
+</div>
+
+<div class="card card-body mb-3" id="holds-card" hidden>
+  <h5 class="mb-2">Security holds</h5>
+  <div class="form-check form-switch mb-1">
+    <input class="form-check-input" type="checkbox" role="switch" id="allow-holds">
+    <label class="form-check-label" for="allow-holds">Allow security holds</label>
+  </div>
+  <p class="hint mb-2">Lets supported plugins, like a robot vacuum, switch Away to Home while they work and back to
+    Away when they're done.
+    <a href="https://github.com/seanfletchr/homebridge-ecobee-security#security-holds" target="_blank" rel="noopener">Learn more…</a></p>
+  <div id="hold-plugins-box" hidden>
+    <div class="mb-1">Allowed plugins</div>
+    <div id="hold-plugins"></div>
+  </div>
+</div>
+
 <script>
 (async () => {
   const PLATFORM = 'EcobeeSecurityPlatform';
@@ -100,11 +166,8 @@
     const blocks = await homebridge.getPluginConfig();
     const block = blocks[0] ?? { platform: PLATFORM, name: 'Security System' };
     block.refreshToken = refreshToken;
-    // Re-show the settings form afterwards so it picks up the new token.
-    homebridge.hideSchemaForm();
     await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
     await homebridge.savePluginConfig();
-    homebridge.showSchemaForm();
     passwordForm.reset();
     mfaForm.reset();
     passwordForm.hidden = false;
@@ -113,6 +176,8 @@
     $('browser').open = false;
     homebridge.toast.success('Signed in to ecobee.');
     await showStatus({ justSignedIn: true });
+    await showSettings();
+    await showHolds();
   }
 
   passwordForm.addEventListener('submit', async event => {
@@ -176,7 +241,117 @@
     }
   });
 
+
+  // ── Settings cards ──
+
+  const controls = [...document.querySelectorAll('[data-key]')];
+
+  /** Fill the cards from the config; show defaults where nothing is set. */
+  async function showSettings() {
+    const [block] = await homebridge.getPluginConfig();
+    const signedIn = Boolean(block?.refreshToken);
+    $('system-card').hidden = !signedIn;
+    $('sensors-card').hidden = !signedIn;
+    for (const input of controls) {
+      const value = block?.[input.dataset.key];
+      if (input.dataset.type === 'bool') {
+        input.checked = value ?? input.dataset.default === 'true';
+      } else {
+        input.value = value ?? input.dataset.default;
+      }
+    }
+    $('co2-box').hidden = block?.airQuality === false;
+  }
+
+  /** Write one setting. Top-level keys are cleared with undefined, never deleted (the UI merges shallowly). */
+  async function setSetting(key, value) {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0] ?? { platform: PLATFORM, name: 'Security System' };
+    block[key] = value;
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  }
+
+  for (const input of controls) {
+    input.addEventListener('change', async () => {
+      const { key, type } = input.dataset;
+      if (type === 'bool') {
+        await setSetting(key, input.checked);
+        if (key === 'airQuality') {
+          $('co2-box').hidden = !input.checked;
+        }
+      } else if (type === 'int') {
+        const number = input.value.trim() === '' ? undefined : Number(input.value);
+        const valid = number === undefined || (Number.isInteger(number) && number >= Number(input.min));
+        input.classList.toggle('is-invalid', !valid);
+        if (valid) {
+          await setSetting(key, number);
+        }
+      } else if (type === 'select') {
+        await setSetting(key, input.value);
+      } else {
+        await setSetting(key, input.value.trim() === '' ? undefined : input.value.trim());
+      }
+    });
+  }
+
+  // ── Security holds ──
+
+  async function showHolds() {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0] ?? {};
+    $('holds-card').hidden = !block.refreshToken;
+    $('allow-holds').checked = block.allowHolds === true;
+    $('hold-plugins-box').hidden = block.allowHolds !== true;
+    const plugins = await homebridge.request('/hold-plugins').catch(() => []);
+    const box = $('hold-plugins');
+    box.textContent = '';
+    if (!plugins.length) {
+      const p = document.createElement('p');
+      p.className = 'hint mb-0';
+      p.textContent = 'No plugin has asked for a hold yet.';
+      box.append(p);
+      return;
+    }
+    // Without a list (settings from before it), every plugin is allowed.
+    const allowed = Array.isArray(block.holdPlugins) ? block.holdPlugins : plugins.map(p => p.key);
+    for (const plugin of plugins) {
+      const id = `hold-${plugin.key.replace(/[^a-z0-9]/gi, '-')}`;
+      const input = Object.assign(document.createElement('input'), {
+        className: 'form-check-input', type: 'checkbox', id, checked: allowed.includes(plugin.key),
+      });
+      input.addEventListener('change', () => setAllowed(plugins, plugin.key, input.checked));
+      const label = Object.assign(document.createElement('label'), { className: 'form-check-label', htmlFor: id });
+      label.textContent = plugin.displayName === plugin.key ? plugin.key : `${plugin.displayName} (${plugin.key})`;
+      const row = Object.assign(document.createElement('div'), { className: 'form-check mb-1' });
+      row.append(input, label);
+      if (plugin.names.length || plugin.lastAsked) {
+        const hint = Object.assign(document.createElement('div'), { className: 'hint' });
+        const when = plugin.lastAsked ? `last asked ${new Date(plugin.lastAsked).toLocaleString()}` : '';
+        hint.textContent = [plugin.names.length ? `for ${plugin.names.join(', ')}` : '', when].filter(Boolean).join(', ');
+        row.append(hint);
+      }
+      box.append(row);
+    }
+  }
+
+  async function setAllowed(plugins, key, on) {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    const current = Array.isArray(block.holdPlugins) ? block.holdPlugins : plugins.map(p => p.key);
+    block.holdPlugins = on ? [...new Set([...current, key])] : current.filter(k => k !== key);
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  }
+
+  $('allow-holds').addEventListener('change', async () => {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    block.allowHolds = $('allow-holds').checked;
+    $('hold-plugins-box').hidden = !block.allowHolds;
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  });
+
   await showStatus();
-  homebridge.showSchemaForm();
+  await showSettings();
+  await showHolds();
 })();
 </script>

package/homebridge-ui/server.js

@@ -1,6 +1,11 @@
 // Server side of the plugin's settings page (spawned by the Homebridge UI while the settings are
 // open). Does the ecobee sign-in and hands only the refresh token back to the page, which saves it
 // in the plugin config. The MFA token and PKCE verifier stay here, in memory.
+import { readdirSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import { HomebridgePluginUiServer, RequestError } from '@homebridge/plugin-ui-utils';
 
 import { browserSignInLink, finishBrowserSignIn, finishMfa, passwordSignIn, SignInError } from '../lib/auth.js';
@@ -47,6 +52,26 @@ class UiServer extends HomebridgePluginUiServer {
       return { refreshToken: tokens.refresh_token };
     }));
 
+    // Plugins that use security holds: installed ones that declare it, and any that have asked.
+    // Only the request log leaves state.json (it also holds the ecobee sign-in).
+    this.onRequest('/hold-plugins', async () => {
+      const plugins = new Map();
+      for (const p of installedHoldClients(this.homebridgeStoragePath)) {
+        plugins.set(p.name, { key: p.name, displayName: p.displayName, names: [] });
+      }
+      let store = {};
+      try {
+        store = JSON.parse(await readFile(join(this.homebridgeStoragePath, 'ecobee-security', 'state.json'), 'utf8'));
+      } catch {
+        // Not started yet: only the installed ones.
+      }
+      for (const [key, r] of Object.entries(store.holdRequesters ?? {})) {
+        const known = plugins.get(key);
+        plugins.set(key, { key, displayName: known?.displayName ?? key, names: r.names ?? [], lastAsked: r.lastAsked });
+      }
+      return [...plugins.values()];
+    });
+
     this.ready();
   }
 
@@ -63,4 +88,41 @@ class UiServer extends HomebridgePluginUiServer {
   }
 }
 
+/** Installed plugins that declare they ask for holds: "homebridge-security-hold": { "client": true }. */
+function installedHoldClients(storagePath) {
+  const folders = new Set([fileURLToPath(new URL('../../', import.meta.url))]);
+  if (storagePath) {
+    folders.add(join(storagePath, 'node_modules'));
+  }
+  const found = new Map();
+  const scan = folder => {
+    let entries = [];
+    try {
+      entries = readdirSync(folder, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const dir = join(folder, entry.name);
+      if (entry.name.startsWith('@')) {
+        scan(dir);
+        continue;
+      }
+      if (!entry.name.includes('homebridge')) {
+        continue;
+      }
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if (pkg['homebridge-security-hold']?.client === true && pkg.name && !found.has(pkg.name)) {
+          found.set(pkg.name, { name: pkg.name, displayName: pkg.displayName || pkg.name });
+        }
+      } catch {
+        // not a package
+      }
+    }
+  };
+  folders.forEach(scan);
+  return [...found.values()];
+}
+
 (() => new UiServer())();

package/lib/control.js

@@ -1,13 +1,17 @@
 // A local control socket so other Homebridge plugins (each child bridge is its own process)
 // can ask for a temporary Stay while they move around the house:
-//   POST /hold?by=<name>     -> { ok, held, state, reason? }
-//   POST /release?by=<name>  -> { released, state }
+//   POST /hold?by=<name>&plugin=<package>     -> { ok, held, state, reason? }
+//   POST /release?by=<name>&plugin=<package>  -> { released, state, waiting? }  (Away only once every holder has released)
 // It's a Unix socket in the plugin's storage folder (mode 600), so only the homebridge user can use it.
+// Holds need `allowHolds` and the asking plugin ticked in the settings (`isAllowed`); otherwise it
+// answers 403 so the caller can log why. Every request is noted (`noteRequest`) so the settings page
+// can list the plugins that asked. A release is always accepted from a current holder, so taking a
+// plugin's permission away can't leave the system stuck in Stay.
 
 import { chmodSync, rmSync } from 'node:fs';
 import { createServer } from 'node:http';
 
-export function startControlServer({ path, log, getSystem }) {
+export function startControlServer({ path, log, getSystem, isAllowed, noteRequest }) {
   try {
     rmSync(path, { force: true });
   } catch (error) {
@@ -16,14 +20,29 @@ export function startControlServer({ path, log, getSystem }) {
   const server = createServer(async (req, res) => {
     const url = new URL(req.url, 'http://localhost');
     const by = (url.searchParams.get('by') || 'another plugin').slice(0, 40);
+    // Requests are allowed per plugin; one that doesn't say which it is goes by its `by` name.
+    const plugin = (url.searchParams.get('plugin') || '').slice(0, 100) || undefined;
+    const key = plugin ?? by;
     const reply = (code, body) => {
       res.writeHead(code, { 'content-type': 'application/json' });
       res.end(JSON.stringify(body));
     };
-    const system = getSystem();
     if (req.method !== 'POST' || !['/hold', '/release'].includes(url.pathname)) {
       return reply(404, { error: 'POST /hold or /release' });
     }
+    const system = getSystem();
+    const releasing = url.pathname === '/release';
+    noteRequest?.({ key, plugin, by });
+    if (!(releasing && system?.holders().includes(by))) {
+      const allowed = isAllowed(key);
+      if (allowed !== true) {
+        const why = allowed === 'off'
+          ? 'security holds are turned off in the ecobee Smart Security settings'
+          : `${key} isn't allowed to ask for security holds in the ecobee Smart Security settings`;
+        log.warn(`${by}${plugin ? ` (${plugin})` : ''} asked for a security hold, but ${why}.`);
+        return reply(403, { ok: false, error: why });
+      }
+    }
     if (!system) {
       return reply(503, { error: 'not connected to ecobee yet' });
     }

package/lib/platform.js

@@ -60,7 +60,13 @@ export class EcobeeSecurityPlatform {
     });
 
     api.on('didFinishLaunching', () => {
-      this.control = startControlServer({ path: join(dir, 'control.sock'), log, getSystem: () => this.system });
+      this.control = startControlServer({
+        path: join(dir, 'control.sock'),
+        log,
+        getSystem: () => this.system,
+        isAllowed: key => this.holdAllowed(key),
+        noteRequest: request => this.noteHoldRequest(request),
+      });
       this.launch();
     });
     api.on('shutdown', () => {
@@ -150,7 +156,8 @@ export class EcobeeSecurityPlatform {
       accessory,
       cloud: this.cloud,
       home,
-      pollInterval: Math.max(5, Number(this.config.pollInterval) || 10),
+      // The ecobee app reads the security state about every 10 s; polling faster would stand out.
+      pollInterval: 10,
       store: this.store,
       save: () => this.save(),
       offerNight: this.config.offerNight === true,
@@ -171,12 +178,41 @@ export class EcobeeSecurityPlatform {
     const m = home.monitoring;
     this.log.info(`Connected to "${home.name}" (${m.armedState}; professional monitoring `
       + `${m.homeMonitoringSettings?.isProfessionalMonitoringEnabled ? 'on' : 'off'}).`);
-    if (this.store.hold) {
-      this.log.info(`Still holding Stay for ${this.store.hold.by} (since ${this.store.hold.since}).`);
+    if (this.store.hold && this.config.allowHolds !== true) {
+      this.log.info(`Security holds are off; dropping the hold for ${this.system.holders().join(' and ')} without re-arming Away.`);
+      this.system.dropHold();
+    } else if (this.store.hold) {
+      this.log.info(`Still holding Stay for ${this.system.holders().join(' and ')} (since ${this.store.hold.since}).`);
     }
     this.startAirQuality(home.id);
   }
 
+  /**
+   * May this plugin (or, if it doesn't say, this name) ask for a hold? `true`, `'off'` (holds are off),
+   * or `'not allowed'`. Without a `holdPlugins` list (settings from before it), every plugin may.
+   */
+  holdAllowed(key) {
+    if (this.config.allowHolds !== true) {
+      return 'off';
+    }
+    const list = this.config.holdPlugins;
+    return !Array.isArray(list) || list.includes(key) ? true : 'not allowed';
+  }
+
+  /** Remember who asked, for the settings page's list of plugins. */
+  noteHoldRequest({ key, plugin, by }) {
+    const requesters = this.store.holdRequesters ??= {};
+    const entry = requesters[key] ??= { names: [] };
+    if (plugin) {
+      entry.plugin = plugin;
+    }
+    if (!entry.names.includes(by)) {
+      entry.names = [...entry.names, by].slice(-10);
+    }
+    entry.lastAsked = new Date().toISOString();
+    this.save();
+  }
+
   /** Air quality sensors for thermostats that have them; failures here never affect the security system. */
   async startAirQuality(homeId) {
     const cached = this.cached.filter(a => a.context.kind === AIR_QUALITY);

package/lib/security.js

@@ -228,7 +228,7 @@ export class SecuritySystem {
     this.target = target;
     if (this.store.hold && (target !== Hk.STAY || this.incidents.length)) {
       this.log.info(`Security system changed to ${HK_NAMES[this.incidents.length ? Hk.TRIGGERED : target]} during the `
-        + `${this.store.hold.by} hold; it won't be put back to Away.`);
+        + `${this.holders().join(' and ')} hold; it won't be put back to Away.`);
       this.dropHold();
     }
     this.service.updateCharacteristic(SecuritySystemTargetState, target);
@@ -311,7 +311,7 @@ export class SecuritySystem {
       throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.INVALID_VALUE_IN_REQUEST);
     }
     if (this.store.hold) {
-      this.log.info(`Home app changed the security system during the ${this.store.hold.by} hold; it won't be put back to Away.`);
+      this.log.info(`Home app changed the security system during the ${this.holders().join(' and ')} hold; it won't be put back to Away.`);
       this.dropHold();
     }
     try {
@@ -358,11 +358,32 @@ export class SecuritySystem {
     }
   }
 
+  /** Read the state now (for hold decisions). Resolves false if ecobee can't be read. */
+  async refresh() {
+    try {
+      const home = (await this.cloud.getHomes()).find(h => h.id === this.homeId);
+      if (!home) {
+        throw new Error('the home is no longer on this ecobee account');
+      }
+      this.apply(home);
+      return true;
+    } catch (error) {
+      this.log.warn(`Could not read the security state for a hold (${error.message}).`);
+      return false;
+    }
+  }
+
   dropHold() {
     delete this.store.hold;
     this.save();
   }
 
+  /** Who is holding Stay (several robots can be out at once). Up to 0.4.x `by` was a single name. */
+  holders() {
+    const by = this.store.hold?.by;
+    return Array.isArray(by) ? by : by ? [by] : [];
+  }
+
   /**
    * Another plugin (the robot vacuum) is about to move around the house. If the system is
    * armed Away (or arming Away), switch it to Stay and remember to put it back. Returns
@@ -371,20 +392,26 @@ export class SecuritySystem {
    */
   hold(by) {
     return this.serial(async () => {
-      if (!this.monitoring || this.failures >= FAULT_AFTER) {
+      // Decide on ecobee's live state, not the last poll: a disarm moments ago must not become a Stay.
+      if (!(await this.refresh()) || !this.monitoring) {
         return { ok: false, held: false, state: 'unknown', reason: 'the security state is unknown' };
       }
       if (this.incidents.length) {
         return { ok: false, held: false, state: HK_NAMES[this.current], reason: 'an alarm incident is open' };
       }
       if (this.store.hold) {
+        if (!this.holders().includes(by)) {
+          this.store.hold = { ...this.store.hold, by: [...this.holders(), by] };
+          this.save();
+          this.log.info(`${by} joined the hold; Away comes back once ${this.holders().join(' and ')} are done.`);
+        }
         return { ok: true, held: true, state: HK_NAMES[this.target] };
       }
       if (this.target !== Hk.AWAY) {
         return { ok: true, held: false, state: HK_NAMES[this.target] };
       }
       await this.arm(Hk.STAY, `${by} hold`);
-      this.store.hold = { by, since: new Date().toISOString() };
+      this.store.hold = { by: [by], since: new Date().toISOString() };
       this.save();
       return { ok: true, held: true, state: HK_NAMES[this.target] };
     });
@@ -393,9 +420,22 @@ export class SecuritySystem {
   /** The vacuum is back: put the system back to Away if we moved it and nobody has changed it since. */
   release(by) {
     return this.serial(async () => {
+      // A change since the last poll (say, a disarm in the ecobee app) drops the hold in apply(),
+      // so a fresh read is what keeps us from arming Away over it. Can't read it: don't arm.
+      if (!(await this.refresh())) {
+        throw new Error('could not read the security state; not arming Away');
+      }
       if (!this.store.hold) {
         return { released: false, state: HK_NAMES[this.target] };
       }
+      const others = this.holders().filter(name => name !== by);
+      if (others.length) {
+        // Someone else is still out: keep Stay until the last one is done.
+        this.store.hold = { ...this.store.hold, by: others };
+        this.save();
+        this.log.info(`${by} is done; staying in Stay for ${others.join(' and ')}.`);
+        return { released: false, state: HK_NAMES[this.target], waiting: others };
+      }
       if (this.target !== Hk.STAY || this.incidents.length) {
         this.log.info(`${by} is done, but the security system is ${HK_NAMES[this.current]}; leaving it.`);
         this.dropHold();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ecobee-security",
   "displayName": "ecobee Smart Security",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "ecobee Smart Security as a HomeKit security system: arm Stay / Away, disarm, alarm state (unofficial, ecobee cloud)",
   "type": "module",
   "main": "index.js",
@@ -41,5 +41,8 @@
   ],
   "dependencies": {
     "@homebridge/plugin-ui-utils": "^2.2.6"
+  },
+  "homebridge-security-hold": {
+    "socket": "ecobee-security/control.sock"
   }
 }