homebridge-ecobee-security 0.5.0 → 0.7.1

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>
@@ -67,20 +67,20 @@
   <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 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 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 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/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>
+    <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>
 
@@ -91,19 +91,34 @@
       <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 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">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 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">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 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>
 
@@ -113,12 +128,23 @@
     <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.
+  <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>
 
@@ -141,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
@@ -177,6 +203,7 @@
     homebridge.toast.success('Signed in to ecobee.');
     await showStatus({ justSignedIn: true });
     await showSettings();
+    await showKeypad();
     await showHolds();
   }
 
@@ -302,6 +329,7 @@
     $('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 = '';
@@ -350,8 +378,70 @@
     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();
   await showSettings();
+  await showKeypad();
   await showHolds();
 })();
 </script>

package/homebridge-ui/server.js

@@ -72,6 +72,16 @@ class UiServer extends HomebridgePluginUiServer {
       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();
   }
 

package/lib/control.js

@@ -1,7 +1,11 @@
 // 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>&plugin=<package>     -> { ok, held, state, reason? }
-//   POST /release?by=<name>&plugin=<package>  -> { released, state, waiting? }  (Away only once every holder has released)
+//   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
@@ -23,6 +27,7 @@ export function startControlServer({ path, log, getSystem, isAllowed, noteReques
     // 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));
@@ -33,7 +38,7 @@ export function startControlServer({ path, log, getSystem, isAllowed, noteReques
     const system = getSystem();
     const releasing = url.pathname === '/release';
     noteRequest?.({ key, plugin, by });
-    if (!(releasing && system?.holders().includes(by))) {
+    if (!(releasing && (system?.holders().includes(by) || system?.returningNames().includes(by)))) {
       const allowed = isAllowed(key);
       if (allowed !== true) {
         const why = allowed === 'off'
@@ -47,7 +52,7 @@ export function startControlServer({ path, log, getSystem, isAllowed, noteReques
       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();
+  });
+}

package/lib/keypad.js

@@ -0,0 +1,240 @@
+// Disarm on a keypad unlock: watch the locks on the other bridges of this Homebridge for an unlock
+// that the lock says was done with its keypad (HomeKit's Lock Last Known Action). Child bridges run
+// in their own processes, so the locks are read over HAP on 127.0.0.1, which Homebridge allows with
+// just the bridge's PIN in insecure mode (the Homebridge UI's accessory control uses the same).
+// HAP events need a paired session, so the locks are polled; reading a few values locally every
+// second costs next to nothing.
+
+import { readFileSync } from 'node:fs';
+
+const POLL = 1000;
+// No locks found (or a bridge went away): look again this often.
+const RESCAN = 10 * 60 * 1000;
+// Other child bridges may still be starting: rescan every 30 s for this long.
+const GRACE = 3 * 60 * 1000;
+const GRACE_RESCAN = 30 * 1000;
+const TIMEOUT = 3000;
+// An unlock whose "by keypad" comes in a later update than the state still counts within this.
+const LABEL_LAG = 5000;
+
+const INFO = '3E';
+const LOCK = '45';
+const NAME = '23';
+const CONFIGURED_NAME = 'E3';
+const SERIAL = '30';
+const CURRENT = '1D';
+const LAST_ACTION = '1C';
+
+const UNSECURED = 0;
+const UNSECURED_BY_KEYPAD = 5;
+
+/** Apple's HAP types come as "45" or "00000045-0000-1000-8000-0026BB765291". */
+function shortType(type) {
+  const t = String(type).toUpperCase();
+  if (t.includes('-') && !t.endsWith('-0000-1000-8000-0026BB765291')) {
+    return t;
+  }
+  return t.split('-')[0].replace(/^0+/, '');
+}
+
+export class KeypadLocks {
+  /**
+   * @param {object} opts
+   * @param {string} opts.configPath Homebridge's config.json (bridge ports and PINs)
+   * @param {string} opts.ownPlatform this plugin's platform name (its own bridge is skipped)
+   * @param {(lock: {key: string, name: string, bridge: string}) => void} opts.onKeypadUnlock
+   * @param {(locks: {key: string, name: string, bridge: string}[]) => void} [opts.onLocks] the locks found, after each scan
+   */
+  constructor({ configPath, ownPlatform, log, onKeypadUnlock, onLocks }) {
+    this.configPath = configPath;
+    this.ownPlatform = ownPlatform;
+    this.log = log;
+    this.onKeypadUnlock = onKeypadUnlock;
+    this.onLocks = onLocks;
+    /** @type {Map<string, object>} key → lock: { key, name, bridge, aid, current, last, state, lastAction, pendingUntil } */
+    this.locks = new Map();
+    this.scannedAt = 0;
+    this.warned = new Set();
+  }
+
+  start() {
+    this.startedAt = Date.now();
+    this.timer = setInterval(() => this.poll(), POLL);
+    this.poll();
+  }
+
+  stop() {
+    clearInterval(this.timer);
+  }
+
+  /** Every bridge in config.json with a fixed port, except this plugin's own. */
+  bridges() {
+    const config = JSON.parse(readFileSync(this.configPath, 'utf8'));
+    const main = config.bridge ?? {};
+    const list = [{ name: main.name ?? 'Homebridge', port: main.port, pin: main.pin }];
+    for (const block of [...(config.platforms ?? []), ...(config.accessories ?? [])]) {
+      const child = block?._bridge;
+      if (child?.port && block.platform !== this.ownPlatform) {
+        list.push({ name: child.name ?? block.platform ?? block.accessory, port: child.port, pin: child.pin ?? main.pin });
+      }
+    }
+    return list.filter(b => b.port && b.pin);
+  }
+
+  async request(bridge, path) {
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${path}`, {
+      headers: { Authorization: bridge.pin },
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (response.status === 401 || response.status === 470) {
+      const error = new Error('not allowed');
+      error.auth = true;
+      throw error;
+    }
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return response.json();
+  }
+
+  /** Find every lock that reports how it was last locked or unlocked. */
+  async scan() {
+    this.scannedAt = Date.now();
+    let bridges;
+    try {
+      bridges = this.bridges();
+    } catch (error) {
+      this.warnOnce('config', `Keypad unlock: could not read the Homebridge config (${error.message}).`);
+      return;
+    }
+    const found = new Map();
+    let denied = 0;
+    for (const bridge of bridges) {
+      let data;
+      try {
+        data = await this.request(bridge, '/accessories');
+      } catch (error) {
+        denied += error.auth ? 1 : 0;
+        continue;
+      }
+      for (const accessory of data.accessories ?? []) {
+        const services = accessory.services ?? [];
+        const lock = services.find(s => shortType(s.type) === LOCK);
+        const all = services.flatMap(s => s.characteristics ?? []);
+        const current = lock?.characteristics?.find(c => shortType(c.type) === CURRENT);
+        const last = all.find(c => shortType(c.type) === LAST_ACTION);
+        if (!current || !last) {
+          continue;
+        }
+        const info = services.find(s => shortType(s.type) === INFO)?.characteristics ?? [];
+        const nameOf = chars => chars.find(c => shortType(c.type) === CONFIGURED_NAME)?.value
+          || chars.find(c => shortType(c.type) === NAME)?.value;
+        const name = nameOf(lock.characteristics) || nameOf(info) || `Lock ${accessory.aid}`;
+        const serial = info.find(c => shortType(c.type) === SERIAL)?.value;
+        const key = serial ? String(serial) : `${bridge.name}/${name}`;
+        const known = this.locks.get(key);
+        found.set(key, {
+          key, name, bridge, aid: accessory.aid, current: current.iid, last: last.iid,
+          // Keep what we knew if it's the same lock on the same bridge; otherwise start from its first read.
+          ...(known?.bridge.port === bridge.port && known.aid === accessory.aid
+            ? { state: known.state, lastAction: known.lastAction, pendingUntil: known.pendingUntil } : {}),
+        });
+      }
+    }
+    if (denied && denied === bridges.length) {
+      this.warnOnce('denied', 'Keypad unlock: Homebridge didn\'t let the plugin read the other bridges. Turn on insecure mode '
+        + '(Homebridge Settings > Homebridge Insecure Mode / Accessory Control) and restart Homebridge.');
+    }
+    const before = [...this.locks.keys()].sort().join();
+    this.locks = found;
+    if ([...found.keys()].sort().join() !== before) {
+      if (found.size) {
+        this.log.info(`Keypad unlock: watching ${[...found.values()].map(l => `"${l.name}" (${l.bridge.name})`).join(', ')}.`);
+        this.warned.delete('none');
+      }
+      this.onLocks?.([...found.values()].map(({ key, name, bridge }) => ({ key, name, bridge: bridge.name })));
+    }
+    if (!found.size && !this.starting()) {
+      this.warnOnce('none', 'Keypad unlock: no lock on this Homebridge reports keypad unlocks; checking again every 10 minutes.');
+    }
+  }
+
+  async poll() {
+    if (this.polling) {
+      return;
+    }
+    this.polling = true;
+    try {
+      const every = this.starting() ? GRACE_RESCAN : RESCAN;
+      if (this.rescan || (!this.locks.size && Date.now() - this.scannedAt >= every)) {
+        this.rescan = false;
+        await this.scan();
+      }
+      const byBridge = new Map();
+      for (const lock of this.locks.values()) {
+        byBridge.set(lock.bridge.port, [...(byBridge.get(lock.bridge.port) ?? []), lock]);
+      }
+      await Promise.all([...byBridge.values()].map(locks => this.read(locks)));
+    } finally {
+      this.polling = false;
+    }
+  }
+
+  async read(locks) {
+    const ids = locks.flatMap(l => [`${l.aid}.${l.current}`, `${l.aid}.${l.last}`]).join(',');
+    let values;
+    try {
+      const data = await this.request(locks[0].bridge, `/characteristics?id=${ids}`);
+      values = new Map((data.characteristics ?? []).map(c => [`${c.aid}.${c.iid}`, c.value]));
+    } catch {
+      // Bridge restarting (or the lock moved): forget the states, so an unlock isn't seen in
+      // whatever it reports when it's back, and look for the locks again (at most every 30 s).
+      locks.forEach(l => Object.assign(l, { state: undefined, lastAction: undefined, pendingUntil: undefined }));
+      if (Date.now() - this.scannedAt >= GRACE_RESCAN) {
+        this.rescan = true;
+      }
+      return;
+    }
+    for (const lock of locks) {
+      this.update(lock, values.get(`${lock.aid}.${lock.current}`), values.get(`${lock.aid}.${lock.last}`));
+    }
+  }
+
+  /**
+   * Only an unlock counts, never a label: the lock must go to unlocked while saying it was unlocked
+   * with its keypad (in the same update, or within a few seconds after). An app unlock passes through
+   * other labels, and a label left from an earlier keypad unlock has no state change to go with it.
+   */
+  update(lock, state, lastAction) {
+    if (state === undefined || lastAction === undefined) {
+      return;
+    }
+    const first = lock.state === undefined;
+    const unlocked = !first && state === UNSECURED && lock.state !== UNSECURED;
+    const now = Date.now();
+    if (state !== lock.state) {
+      lock.pendingUntil = unlocked ? now + LABEL_LAG : undefined;
+    }
+    lock.state = state;
+    lock.lastAction = lastAction;
+    if (lock.pendingUntil && now > lock.pendingUntil) {
+      lock.pendingUntil = undefined;
+    }
+    if (lock.pendingUntil && lastAction === UNSECURED_BY_KEYPAD) {
+      lock.pendingUntil = undefined;
+      this.onKeypadUnlock({ key: lock.key, name: lock.name, bridge: lock.bridge.name });
+    }
+  }
+
+  /** Within the start-up grace period, when other bridges may not be up yet. */
+  starting() {
+    return Date.now() - this.startedAt < GRACE;
+  }
+
+  warnOnce(key, message) {
+    if (!this.warned.has(key)) {
+      this.warned.add(key);
+      this.log.warn(message);
+    }
+  }
+}