homebridge-ecobee-security 0.4.2 → 0.7.0

package/homebridge-ui/public/index.html

@@ -8,7 +8,7 @@
 
   <div id="signed-in" hidden>
     <div class="alert alert-success mb-2" role="status" id="signed-in-text">Signed in to ecobee.</div>
-    <p class="hint mb-2" id="signed-in-hint">You only need to sign in again if the log says ecobee signed the plugin out (for example after a password change).</p>
+    <p class="hint mb-2" id="signed-in-hint">Sign in again only if the log says ecobee signed the plugin out, for example after a password change.</p>
     <button type="button" class="btn btn-secondary" id="sign-in-again">Sign in again</button>
   </div>
 
@@ -22,7 +22,7 @@
     <div class="mb-2">
       <label for="password" class="form-label">Password</label>
       <input type="password" class="form-control" id="password" autocomplete="current-password" required>
-      <div class="hint mt-1">Sent only to ecobee to sign in. The plugin keeps a sign-in token, never your password.</div>
+      <div class="hint mt-1">Sent only to ecobee. The plugin saves a sign-in token, not your password.</div>
     </div>
     <button type="submit" class="btn btn-primary">Sign in</button>
     <button type="button" class="btn btn-link" id="sign-in-cancel" hidden>Cancel</button>
@@ -41,12 +41,12 @@
 
   <details class="mt-3" id="browser">
     <summary>Sign in on ecobee's website instead</summary>
-    <p class="hint mt-2 mb-2">Use this if signing in above keeps failing (for example if ecobee asks for a CAPTCHA). You'll need a desktop browser with developer tools.</p>
+    <p class="hint mt-2 mb-2">Use this if signing in above keeps failing, for example if ecobee asks for a CAPTCHA. You need a desktop browser with developer tools.</p>
     <ol class="small ps-3">
       <li>In Chrome, open a new tab, open DevTools (Option-Command-I or F12), go to <b>Network</b> and tick <b>Preserve log</b>.</li>
       <li>In that tab, open <a id="browser-link" href="#" target="_blank" rel="noopener">this sign-in link</a> and sign in.</li>
       <li>When the page goes blank, type <code>code=</code> in the Network filter, right-click the entry and choose <b>Copy &gt; Copy URL</b>. It starts with <code>com.ecobee.athenamobile://</code></li>
-      <li>Paste it here straight away (the code expires within a minute):</li>
+      <li>Paste it here within a minute, before it expires:</li>
     </ol>
     <form id="browser-form" class="d-flex gap-2">
       <input type="text" class="form-control" id="callback" placeholder="com.ecobee.athenamobile://…" required>
@@ -56,6 +56,98 @@
   </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 your account has more than one home. The log lists your homes.</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 a Night mode to use in automations. ecobee has no Night mode, so Night arms ecobee's Stay.</div>
+    <div class="hint mt-1">Changing this recreates the security system in the Home app, so you need to set up its scenes and automations 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 delay</option></select>
+    <div class="hint mt-1">Immediately: as soon as a door or sensor trips while armed, like the ecobee app. After the entry delay: only if no one disarms in time, so automations don't run while you walk in. 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 Smoke Alarm accessory that detects smoke when ecobee reports a smoke alarm. Use it for Home app notifications and automations.</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">Adds 2 sensors for each ecobee Premium thermostat: air quality (with VOC) and CO2. ecobee's own HomeKit integration doesn't include them. Updates 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">At or above this level, the CO2 sensor reports abnormal CO2. Use it for notifications and automations, like turning on ventilation.</div>
+  </div>
+</div>
+
+<div class="card card-body mb-3" id="keypad-card" hidden>
+  <h5 class="mb-2">Door keypads</h5>
+  <div class="form-check form-switch mb-1">
+    <input class="form-check-input" type="checkbox" role="switch" id="keypad-disarm">
+    <label class="form-check-label" for="keypad-disarm">Disarm when a door is unlocked with its keypad</label>
+  </div>
+  <p class="hint mb-2">Entering a code on a smart lock's keypad turns the security system off, so family and guests
+    can use their lock codes. Restart the bridge after changing this.
+    <a href="https://github.com/seanfletchr/homebridge-ecobee-security#keypad-unlock" target="_blank" rel="noopener">Learn more…</a></p>
+  <div id="keypad-locks-box" hidden>
+    <div class="mb-1">Locks that disarm</div>
+    <div id="keypad-locks"></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, keep the system from arming Away while they work:
+    Away is switched to Home, and comes back when they're done. Away asked for in the Home app meanwhile
+    waits until 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 class="form-check form-switch mt-3 mb-1">
+      <input class="form-check-input" type="checkbox" role="switch" id="arm-away-now">
+      <label class="form-check-label" for="arm-away-now">Arm Away Now switch</label>
+    </div>
+    <div class="hint">Adds a switch to the Home app that arms Away now and asks any task that's running to stop (a robot goes back to its base). Restart the
+      bridge after changing this.</div>
+    <label for="s-taskWaitSeconds" class="form-label mt-3 mb-1">Extra time for tasks to finish (seconds)</label>
+    <input class="form-control" type="number" step="10" min="0" max="300" id="s-taskWaitSeconds" data-key="taskWaitSeconds" data-type="int" data-default="120">
+    <div class="hint mt-1">If Away is armed while a task is running, like a robot heading back to its base, the countdown
+      waits up to this much longer, and arms as soon as it's done. 0: no waiting.</div>
+  </div>
+</div>
+
 <script>
 (async () => {
   const PLATFORM = 'EcobeeSecurityPlatform';
@@ -75,7 +167,7 @@
     $('signed-in').hidden = !signedIn;
     $('signin').hidden = signedIn;
     $('signed-in-text').textContent = justSignedIn
-      ? 'Signed in and saved. Restart the bridge this plugin runs on (or Homebridge) to use the new sign-in.'
+      ? 'Signed in and saved. Restart this plugin\'s bridge, or Homebridge, to use the new sign-in.'
       : 'Signed in to ecobee.';
     $('sign-in-cancel').hidden = !block?.refreshToken;
     $('signin-hint').textContent = block?.refreshToken
@@ -100,11 +192,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 +202,9 @@
     $('browser').open = false;
     homebridge.toast.success('Signed in to ecobee.');
     await showStatus({ justSignedIn: true });
+    await showSettings();
+    await showKeypad();
+    await showHolds();
   }
 
   passwordForm.addEventListener('submit', async event => {
@@ -176,7 +268,180 @@
     }
   });
 
+
+  // ── 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;
+    $('arm-away-now').checked = block.armAwayNowSwitch === 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)]);
+  });
+
+  $('arm-away-now').addEventListener('change', async () => {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    block.armAwayNowSwitch = $('arm-away-now').checked;
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  });
+
+  // ── Door keypads ──
+
+  async function showKeypad() {
+    const [block = {}] = await homebridge.getPluginConfig();
+    $('keypad-card').hidden = !block.refreshToken;
+    $('keypad-disarm').checked = block.keypadDisarm === true;
+    $('keypad-locks-box').hidden = block.keypadDisarm !== true;
+    const locks = await homebridge.request('/keypad-locks').catch(() => []);
+    const box = $('keypad-locks');
+    box.textContent = '';
+    if (!locks.length) {
+      const p = document.createElement('p');
+      p.className = 'hint mb-0';
+      p.textContent = block.keypadDisarm === true
+        ? 'No lock found yet. Locks show up here a minute after the bridge restarts; the log says if none report keypad unlocks.'
+        : 'Turn this on and restart the bridge to find your locks.';
+      box.append(p);
+      return;
+    }
+    // Without a list, every lock disarms.
+    const allowed = Array.isArray(block.keypadLocks) ? block.keypadLocks : locks.map(l => l.key);
+    for (const lock of locks) {
+      const id = `lock-${lock.key.replace(/[^a-z0-9]/gi, '-')}`;
+      const input = Object.assign(document.createElement('input'), {
+        className: 'form-check-input', type: 'checkbox', id, checked: allowed.includes(lock.key),
+      });
+      input.addEventListener('change', () => setLock(locks, lock.key, input.checked));
+      const label = Object.assign(document.createElement('label'), { className: 'form-check-label', htmlFor: id });
+      label.textContent = lock.name;
+      const hint = Object.assign(document.createElement('div'), { className: 'hint' });
+      hint.textContent = lock.bridge;
+      const row = Object.assign(document.createElement('div'), { className: 'form-check mb-1' });
+      row.append(input, label, hint);
+      box.append(row);
+    }
+  }
+
+  async function setLock(locks, key, on) {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    const current = Array.isArray(block.keypadLocks) ? block.keypadLocks : locks.map(l => l.key);
+    block.keypadLocks = on ? [...new Set([...current, key])] : current.filter(k => k !== key);
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+  }
+
+  $('keypad-disarm').addEventListener('change', async () => {
+    const blocks = await homebridge.getPluginConfig();
+    const block = blocks[0];
+    block.keypadDisarm = $('keypad-disarm').checked;
+    $('keypad-locks-box').hidden = !block.keypadDisarm;
+    await homebridge.updatePluginConfig([block, ...blocks.slice(1)]);
+    await showKeypad();
+  });
+
   await showStatus();
-  homebridge.showSchemaForm();
+  await showSettings();
+  await showKeypad();
+  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,36 @@ 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()];
+    });
+
+    // Locks the plugin found that report keypad unlocks (only that list leaves state.json).
+    this.onRequest('/keypad-locks', async () => {
+      try {
+        const store = JSON.parse(await readFile(join(this.homebridgeStoragePath, 'ecobee-security', 'state.json'), 'utf8'));
+        return store.keypadLocks ?? [];
+      } catch {
+        return [];
+      }
+    });
+
     this.ready();
   }
 
@@ -63,4 +98,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,21 @@
 // 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>[&halt=<endpoint>]  -> { ok, held, state, reason? }
+//     `halt`: a Unix socket path or http(s) URL where the plugin answers POST /halt?by=<name>; it's
+//     called when the system is armed Away while it's out (`&armAt=`: back at base or stopped by then;
+//     a robot that answers `returning` is waited for, see SecuritySystem.haltRobots).
+//   POST /release?by=<name>&plugin=<package>  -> { released, state, waiting? }  (Away only once every holder has released;
+//     also how a robot sent back to its base says it's in, or stopped, so an extended exit delay can end)
 // 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,19 +24,35 @@ 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 halt = (url.searchParams.get('halt') || '').slice(0, 500) || undefined;
     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) || system?.returningNames().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' });
     }
     try {
-      reply(200, url.pathname === '/hold' ? await system.hold(by) : await system.release(by));
+      reply(200, url.pathname === '/hold' ? await system.hold(by, { plugin, halt }) : await system.release(by));
     } catch (error) {
       reply(502, { error: error.message });
     }

package/lib/ecobee.js

@@ -163,10 +163,11 @@ export class EcobeeCloud {
    * @param {string} homeId
    * @param {string} armedState one of ArmedState
    * @param {number} exitDelay seconds; the app sends the exit delay as a timestamp
+   * @param {number} [until] the exit delay's end (ms) instead of `exitDelay`
    * @returns the home's monitoring state after the change
    */
-  async setArmedState(homeId, armedState, exitDelay = 0) {
-    const exitDelayUntil = new Date(Date.now() + exitDelay * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z');
+  async setArmedState(homeId, armedState, exitDelay = 0, until = Date.now() + exitDelay * 1000) {
+    const exitDelayUntil = new Date(until).toISOString().replace(/\.\d{3}Z$/, 'Z');
     const data = await this.graphql('SetArmedStateForHome', SET_MUTATION, {
       input: { homeId, armedState, exitDelayUntil },
     });

package/lib/halt.js

@@ -0,0 +1,51 @@
+// Ask a plugin that's out working (a robot vacuum) to head back to its base or stop where it is,
+// because the system is being armed Away. Plugins give their halt endpoint with their hold request (`&halt=`): a Unix socket path,
+// or an http(s) URL. POST <endpoint>/halt?by=<name>&armAt=<ISO time> -> 2xx, optionally JSON
+// { halted, returning?, reason? }. `armAt` is when the motion sensors arm (the end of the exit delay),
+// so a robot can head back to its base in time; without it, it stops where it is.
+
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+
+const TIMEOUT = 5 * 1000;
+
+/** Resolves `{ halted, returning?, reason? }`; rejects if the plugin can't be reached. */
+export function sendHalt(endpoint, by, armAt) {
+  const query = `?by=${encodeURIComponent(by)}` + (armAt ? `&armAt=${encodeURIComponent(new Date(armAt).toISOString())}` : '');
+  const options = { method: 'POST', timeout: TIMEOUT };
+  let request = httpRequest;
+  if (/^https?:\/\//i.test(endpoint)) {
+    const url = new URL(endpoint);
+    Object.assign(options, {
+      protocol: url.protocol, hostname: url.hostname, port: url.port || undefined,
+      auth: url.username ? `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}` : undefined,
+      path: `${url.pathname.replace(/\/$/, '')}/halt${query}`,
+    });
+    request = url.protocol === 'https:' ? httpsRequest : httpRequest;
+  } else {
+    Object.assign(options, { socketPath: endpoint, path: `/halt${query}` });
+  }
+  return new Promise((resolve, reject) => {
+    const req = request(options, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        let json = {};
+        try {
+          json = body.trim() ? JSON.parse(body) : {};
+        } catch {
+          // The status code is what counts.
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          return reject(new Error(json.error ?? `answered ${res.statusCode}`));
+        }
+        resolve({ halted: json.halted ?? true, returning: json.returning === true, reason: json.reason });
+      });
+    });
+    req.on('timeout', () => req.destroy(new Error('no answer')));
+    req.on('error', error => reject(error.code === 'ENOENT' || error.code === 'ECONNREFUSED'
+      ? new Error('the plugin is not running') : error));
+    req.end();
+  });
+}