homebridge-ecobee-security 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.3.0
+
+- Sign in from the plugin's settings page in the Homebridge UI with your ecobee email, password
+  and MFA code. No terminal or browser developer tools needed; the website sign-in is still there
+  as a fallback.
+- `bin/ecobee-login.js` signs in with email and password by default; `--browser` for the old way.
+
+## 0.2.0
+
+- Control socket (`control.sock`) so other plugins can hold the system at Stay and release it to
+  Away afterwards (used by homebridge-narwal while the robot vacuum cleans).
+
+## 0.1.0
+
+- First release: arm Stay / Away, disarm and alarm state in Apple Home, browser sign-in script.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Fletcher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# homebridge-ecobee-security
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shows **ecobee Smart Security** in Apple Home as a security system: arm **Stay**, arm **Away**,
+**disarm**, and **Alarm triggered** when ecobee has an open intrusion or smoke incident. Works with
+Siri ("set the security system to away") and Home automations. ecobee removed Smart Security from
+its HomeKit integration; this brings it back.
+
+Unofficial. It uses the same cloud API as the ecobee iOS app (Auth0 sign-in at `auth.ecobee.com`,
+GraphQL at `federated-api.prod.federated-graph.generacapis.com`), which ecobee can change at any time.
+No dependencies.
+
+> [!WARNING]
+> Not affiliated with or endorsed by ecobee. The plugin signs in as the ecobee iOS app, which
+> ecobee may not allow, and it can stop working whenever ecobee changes its app or API.
+> If you have **professional monitoring**, testing an alarm (opening a door while armed) can
+> lead to a call from the monitoring centre or a dispatch, just as it would with the ecobee app.
+
+## Install
+
+In the Homebridge UI, search the Plugins tab for **ecobee Smart Security**, or:
+
+```
+npm install -g homebridge-ecobee-security
+```
+
+Running it as a child bridge is recommended. Requires Node 22 or 24 and Homebridge 1.8 or 2.x.
+
+## Sign-in
+
+Open the plugin's **Settings** in the Homebridge UI and sign in with your ecobee email and password,
+then the verification code if your account uses MFA. The plugin saves a refresh token in its config;
+your password is sent only to ecobee and isn't stored. Restart the bridge afterwards.
+
+The plugin renews its access token every 2 hours and keeps the current refresh token in
+`<homebridge storage>/ecobee-security/state.json` (mode 600). A newly saved token always replaces the
+stored one. You only need to sign in again if ecobee revokes the token (for example after a password
+change or "sign out of all devices"); the log then says so and the accessory shows a fault.
+
+**If sign-in fails** (for example ecobee asks for a CAPTCHA), the settings page also offers sign-in
+on ecobee's website: you sign in in a desktop browser and paste the final redirect URL from its
+developer tools.
+
+**Without the Homebridge UI**, sign in from a terminal and paste the printed token into the config:
+
+```
+node <plugin folder>/bin/ecobee-login.js            # email, password, MFA code
+node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
+```
+
+## Config
+
+```json
+{
+  "platform": "EcobeeSecurityPlatform",
+  "name": "Security System",
+  "refreshToken": "…",
+  "pollInterval": 10,
+  "_bridge": { "username": "…", "port": 51926, "name": "Ecobee Security Bridge" }
+}
+```
+
+`homeId` is only needed if the account has several homes (the log lists them).
+
+## How it behaves
+
+- **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.
+- **Alarm triggered** while ecobee lists an incident whose status isn't resolved/closed/cancelled.
+  ecobee opens an incident as soon as a door opens while armed, during the entry delay, so the
+  tile shows Alarm triggered from that moment, as the ecobee app does; disarming clears it.
+  Every change in the incident list is logged.
+- **Siri** calls Stay "Home": "set the security system to Home". Saying "arm … for stay" makes
+  Siri pick Away.
+- **Night** isn't offered; ecobee has no Night mode.
+- 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.
+
+## API notes
+
+[docs/api.md](docs/api.md) describes the sign-in flow and GraphQL calls the plugin uses, for anyone
+fixing it after an ecobee change or adding features.
+
+## License
+
+MIT

package/bin/ecobee-login.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Sign-in for homebridge-ecobee-security from a terminal, for when the Homebridge UI isn't
+// available (its plugin settings page has the same sign-in). Prints a refresh token to paste into
+// the plugin config.
+//
+//   ecobee-login.js            email, password and MFA code (the password is never saved)
+//   ecobee-login.js --browser  sign in on ecobee's web page instead and paste the callback URL
+import readline from 'node:readline';
+
+import { browserSignInLink, finishBrowserSignIn, finishMfa, passwordSignIn } from '../lib/auth.js';
+
+// One reader for the whole run. Lines are queued, so piped input that arrives before the next
+// question isn't lost.
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: process.stdin.isTTY });
+let muted = false;
+rl._writeToOutput = text => {
+  if (!muted) {
+    rl.output.write(text);
+  }
+};
+const lines = [];
+const waiting = [];
+rl.on('line', line => (waiting.length ? waiting.shift()(line) : lines.push(line)));
+rl.on('close', () => waiting.splice(0).forEach(resolve => resolve('')));
+
+async function ask(question, { hidden = false } = {}) {
+  rl.output.write(question);
+  // Hide what's typed after the prompt.
+  muted = hidden;
+  const answer = lines.length ? lines.shift() : await new Promise(resolve => waiting.push(resolve));
+  muted = false;
+  if (hidden) {
+    rl.output.write('\n');
+  }
+  return answer.trim();
+}
+
+async function withPassword() {
+  console.log('\nSign in to ecobee. Your password goes only to auth.ecobee.com and isn\'t saved.\n');
+  const username = await ask('ecobee email: ');
+  const password = await ask('Password (hidden): ', { hidden: true });
+  const { tokens, mfa } = await passwordSignIn(username, password);
+  if (tokens) {
+    return tokens;
+  }
+  const code = await ask(mfa.method === 'oob' ? 'Code ecobee just sent you: ' : 'Code from your authenticator app: ');
+  return finishMfa(mfa, code);
+}
+
+async function withBrowser() {
+  const link = browserSignInLink();
+  console.log(`
+1. In Chrome, open a new tab, press Option-Command-I, go to Network and tick "Preserve log".
+2. Open this link in that tab and sign in (email, password, CAPTCHA, MFA code):
+
+${link.url}
+
+3. When the page goes blank, type  code=  in the Network filter, right-click the entry and
+   Copy > Copy URL (or: the last "resume" request > Headers > Response Headers > location).
+   It starts with com.ecobee.athenamobile://
+4. Paste it below straight away; the code expires quickly.
+`);
+  return finishBrowserSignIn(link, await ask('Callback URL: '));
+}
+
+async function main() {
+  const tokens = process.argv.includes('--browser') ? await withBrowser() : await withPassword();
+  console.log(`
+Signed in. Paste this refresh token into the plugin settings ("Refresh token"), save, and restart
+the bridge. Treat it like a password: it gives full access to your ecobee account.
+
+${tokens.refresh_token}
+`);
+}
+
+main().then(() => rl.close(), error => {
+  console.error(`Sign-in failed: ${error.message}`);
+  process.exit(1);
+});

package/config.schema.json

@@ -0,0 +1,38 @@
+{
+  "pluginAlias": "EcobeeSecurityPlatform",
+  "pluginType": "platform",
+  "singular": true,
+  "customUi": true,
+  "headerDisplay": "Shows ecobee Smart Security as a security system in Apple Home (arm Stay / Away, disarm, alarm state). Unofficial: uses the same ecobee cloud as the app.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Security System",
+        "description": "Name shown in the Home app."
+      },
+      "refreshToken": {
+        "title": "Refresh token",
+        "type": "string",
+        "x-schema-form": {
+          "type": "password"
+        },
+        "description": "Filled in when you sign in above. Only needed again if ecobee signs the plugin out (password change, 'sign out everywhere')."
+      },
+      "homeId": {
+        "title": "Home ID",
+        "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."
+      }
+    }
+  }
+}

package/homebridge-ui/public/index.html

@@ -0,0 +1,182 @@
+<style>
+  /* Inherit the theme's text colour; Bootstrap's muted grey is unreadable on Homebridge's dark themes. */
+  .hint { opacity: 0.75; font-size: 0.875em; }
+</style>
+
+<div class="card card-body mb-3">
+  <h5 class="mb-3">ecobee account</h5>
+
+  <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>
+    <button type="button" class="btn btn-secondary" id="sign-in-again">Sign in again</button>
+  </div>
+
+  <div id="signin" hidden>
+  <p class="hint mb-3" id="signin-hint">Sign in with your ecobee account to connect the plugin.</p>
+  <form id="password-form" autocomplete="on">
+    <div class="mb-2">
+      <label for="email" class="form-label">ecobee email</label>
+      <input type="email" class="form-control" id="email" autocomplete="username" required>
+    </div>
+    <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>
+    <button type="submit" class="btn btn-primary">Sign in</button>
+    <button type="button" class="btn btn-link" id="sign-in-cancel" hidden>Cancel</button>
+  </form>
+
+  <form id="mfa-form" hidden>
+    <div class="mb-2">
+      <label for="code" class="form-label" id="code-label">Verification code</label>
+      <input type="text" class="form-control" id="code" inputmode="numeric" autocomplete="one-time-code" maxlength="10" required>
+    </div>
+    <button type="submit" class="btn btn-primary">Verify</button>
+    <button type="button" class="btn btn-link" id="mfa-cancel">Start over</button>
+  </form>
+
+  <div id="error" class="alert alert-danger mt-3 mb-0" role="alert" hidden></div>
+
+  <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>
+    <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>
+    </ol>
+    <form id="browser-form" class="d-flex gap-2">
+      <input type="text" class="form-control" id="callback" placeholder="com.ecobee.athenamobile://…" required>
+      <button type="submit" class="btn btn-primary">Finish</button>
+    </form>
+  </details>
+  </div>
+</div>
+
+<script>
+(async () => {
+  const PLATFORM = 'EcobeeSecurityPlatform';
+  const $ = id => document.getElementById(id);
+  const passwordForm = $('password-form');
+  const mfaForm = $('mfa-form');
+
+  function showError(message) {
+    $('error').textContent = message;
+    $('error').hidden = !message;
+  }
+
+  /** Show the signed-in summary, or the sign-in forms if there's no token (or the user asked). */
+  async function showStatus({ justSignedIn = false, signIn = false } = {}) {
+    const [block] = await homebridge.getPluginConfig();
+    const signedIn = Boolean(block?.refreshToken) && !signIn;
+    $('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 to ecobee.';
+    $('sign-in-cancel').hidden = !block?.refreshToken;
+    $('signin-hint').textContent = block?.refreshToken
+      ? 'Signing in again replaces the saved sign-in.'
+      : 'Sign in with your ecobee account to connect the plugin.';
+  }
+
+  async function call(path, body) {
+    showError('');
+    homebridge.showSpinner();
+    try {
+      return await homebridge.request(path, body);
+    } catch (error) {
+      showError(error.message || 'Sign-in failed.');
+      return undefined;
+    } finally {
+      homebridge.hideSpinner();
+    }
+  }
+
+  async function saveToken(refreshToken) {
+    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;
+    mfaForm.hidden = true;
+    $('callback').value = '';
+    $('browser').open = false;
+    homebridge.toast.success('Signed in to ecobee.');
+    await showStatus({ justSignedIn: true });
+  }
+
+  passwordForm.addEventListener('submit', async event => {
+    event.preventDefault();
+    const result = await call('/password', { email: $('email').value, password: $('password').value });
+    $('password').value = '';
+    if (result?.refreshToken) {
+      await saveToken(result.refreshToken);
+    } else if (result?.mfa) {
+      $('code-label').textContent = result.mfa === 'oob'
+        ? 'Enter the code ecobee just sent you'
+        : 'Enter the code from your authenticator app';
+      passwordForm.hidden = true;
+      mfaForm.hidden = false;
+      $('code').focus();
+    }
+  });
+
+  mfaForm.addEventListener('submit', async event => {
+    event.preventDefault();
+    const result = await call('/mfa', { code: $('code').value });
+    $('code').value = '';
+    if (result?.refreshToken) {
+      await saveToken(result.refreshToken);
+    }
+  });
+
+  $('mfa-cancel').addEventListener('click', () => {
+    showError('');
+    mfaForm.reset();
+    mfaForm.hidden = true;
+    passwordForm.hidden = false;
+  });
+
+  $('sign-in-again').addEventListener('click', async () => {
+    showError('');
+    await showStatus({ signIn: true });
+    $('email').focus();
+  });
+
+  $('sign-in-cancel').addEventListener('click', async () => {
+    showError('');
+    passwordForm.reset();
+    await showStatus();
+  });
+
+  $('browser').addEventListener('toggle', async () => {
+    if ($('browser').open) {
+      const result = await call('/browser-link');
+      if (result?.url) {
+        $('browser-link').href = result.url;
+      }
+    }
+  });
+
+  $('browser-form').addEventListener('submit', async event => {
+    event.preventDefault();
+    const result = await call('/browser-finish', { callbackUrl: $('callback').value });
+    if (result?.refreshToken) {
+      await saveToken(result.refreshToken);
+    }
+  });
+
+  await showStatus();
+  homebridge.showSchemaForm();
+})();
+</script>

package/homebridge-ui/server.js

@@ -0,0 +1,66 @@
+// 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 { HomebridgePluginUiServer, RequestError } from '@homebridge/plugin-ui-utils';
+
+import { browserSignInLink, finishBrowserSignIn, finishMfa, passwordSignIn, SignInError } from '../lib/auth.js';
+
+class UiServer extends HomebridgePluginUiServer {
+  constructor() {
+    super();
+    this.mfa = undefined;
+    this.link = undefined;
+
+    this.onRequest('/password', ({ email, password } = {}) => this.guard(async () => {
+      if (!email || !password) {
+        throw new SignInError('Enter your ecobee email and password.', 'missing');
+      }
+      this.mfa = undefined;
+      const { tokens, mfa } = await passwordSignIn(String(email).trim(), String(password));
+      if (tokens) {
+        return { refreshToken: tokens.refresh_token };
+      }
+      this.mfa = mfa;
+      return { mfa: mfa.method };
+    }));
+
+    this.onRequest('/mfa', ({ code } = {}) => this.guard(async () => {
+      if (!this.mfa) {
+        throw new SignInError('The sign-in timed out. Enter your email and password again.', 'no_mfa');
+      }
+      const tokens = await finishMfa(this.mfa, code ?? '');
+      this.mfa = undefined;
+      return { refreshToken: tokens.refresh_token };
+    }));
+
+    this.onRequest('/browser-link', () => {
+      this.link = browserSignInLink();
+      return { url: this.link.url };
+    });
+
+    this.onRequest('/browser-finish', ({ callbackUrl } = {}) => this.guard(async () => {
+      if (!this.link) {
+        throw new SignInError('Get a sign-in link first.', 'no_link');
+      }
+      const tokens = await finishBrowserSignIn(this.link, callbackUrl ?? '');
+      this.link = undefined;
+      return { refreshToken: tokens.refresh_token };
+    }));
+
+    this.ready();
+  }
+
+  /** Turn sign-in failures into RequestErrors so the page can show ecobee's reason. */
+  async guard(fn) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (error instanceof SignInError) {
+        throw new RequestError(error.message, { code: error.code });
+      }
+      throw new RequestError(`Sign-in failed: ${error.message}`, { code: 'unexpected' });
+    }
+  }
+}
+
+(() => new UiServer())();

package/index.js

@@ -0,0 +1,5 @@
+import { EcobeeSecurityPlatform, PLATFORM_NAME } from './lib/platform.js';
+
+export default (api) => {
+  api.registerPlatform(PLATFORM_NAME, EcobeeSecurityPlatform);
+};

package/lib/auth.js

@@ -0,0 +1,121 @@
+// ecobee sign-in, shared by bin/ecobee-login.js and the Homebridge UI settings page.
+//
+// Password sign-in goes straight to Auth0's token endpoint as the ecobee app's client (no login
+// page, so no CAPTCHA), followed by the account's MFA code if it has MFA. The browser sign-in is
+// the fallback: the user signs in on ecobee's page and pastes the app callback URL.
+// Only the refresh token is kept; passwords and codes are passed through and never stored.
+import { createHash, randomBytes } from 'node:crypto';
+
+import { AUDIENCE, AUTH, CLIENT_ID, REDIRECT_URI, SCOPE } from './ecobee.js';
+
+const TIMEOUT = 20 * 1000;
+
+/** A sign-in step failed; `message` is ecobee's reason, fit to show the user. */
+export class SignInError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+}
+
+async function post(path, body) {
+  let res;
+  try {
+    res = await fetch(`${AUTH}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ client_id: CLIENT_ID, ...body }),
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+  } catch (error) {
+    throw new SignInError(`Could not reach ecobee (${error.message})`, 'network');
+  }
+  const json = await res.json().catch(() => ({}));
+  return { status: res.status, json };
+}
+
+function fail({ status, json }) {
+  const reason = json.error_description || json.error || `HTTP ${status}`;
+  return new SignInError(reason.endsWith('.') ? reason : `${reason}.`, json.error ?? `http_${status}`);
+}
+
+function tokens(json) {
+  if (!json.refresh_token) {
+    throw new SignInError('Signed in, but ecobee returned no refresh token.', 'no_refresh_token');
+  }
+  return json;
+}
+
+/**
+ * Step 1 of password sign-in. Resolves `{ tokens }` when no MFA is needed, otherwise
+ * `{ mfa }` to pass to finishMfa() together with the code ecobee asks for. `mfa.method` is
+ * 'otp' (authenticator app) or 'oob' (a code ecobee sends by SMS or email).
+ */
+export async function passwordSignIn(username, password) {
+  const first = await post('/oauth/token', { grant_type: 'password', username, password, audience: AUDIENCE, scope: SCOPE });
+  if (first.status === 200) {
+    return { tokens: tokens(first.json) };
+  }
+  if (first.json.error !== 'mfa_required') {
+    throw fail(first);
+  }
+  const mfaToken = first.json.mfa_token;
+  const challenge = await post('/mfa/challenge', { mfa_token: mfaToken, challenge_type: 'otp oob' });
+  if (challenge.status !== 200) {
+    throw fail(challenge);
+  }
+  return {
+    mfa: {
+      token: mfaToken,
+      method: challenge.json.challenge_type === 'oob' ? 'oob' : 'otp',
+      oobCode: challenge.json.oob_code,
+    },
+  };
+}
+
+/** Step 2 of password sign-in: the MFA code. */
+export async function finishMfa(mfa, code) {
+  const otp = String(code).replace(/\s+/g, '');
+  const result = mfa.method === 'oob'
+    ? await post('/oauth/token', { grant_type: 'http://auth0.com/oauth/grant-type/mfa-oob', mfa_token: mfa.token, oob_code: mfa.oobCode, binding_code: otp })
+    : await post('/oauth/token', { grant_type: 'http://auth0.com/oauth/grant-type/mfa-otp', mfa_token: mfa.token, otp });
+  if (result.status !== 200) {
+    throw fail(result);
+  }
+  return tokens(result.json);
+}
+
+/** Browser sign-in, step 1: the link to open, plus what finishBrowserSignIn() needs later. */
+export function browserSignInLink() {
+  const verifier = randomBytes(32).toString('base64url');
+  const state = randomBytes(24).toString('base64url');
+  const url = new URL('/authorize', AUTH);
+  Object.entries({
+    audience: AUDIENCE, client_id: CLIENT_ID, redirect_uri: REDIRECT_URI, scope: SCOPE,
+    response_type: 'code', prompt: 'login', state, nonce: randomBytes(16).toString('hex'),
+    code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256',
+  }).forEach(([k, v]) => url.searchParams.set(k, v));
+  return { url: url.href, verifier, state };
+}
+
+/** Browser sign-in, step 2: the com.ecobee.athenamobile://…?code=… URL the user copied. */
+export async function finishBrowserSignIn(link, callbackUrl) {
+  let callback;
+  try {
+    callback = new URL(String(callbackUrl).trim());
+  } catch {
+    throw new SignInError('That isn\'t a URL. It should start with com.ecobee.athenamobile://', 'bad_url');
+  }
+  if (callback.searchParams.get('state') !== link.state) {
+    throw new SignInError('That URL is from a different sign-in attempt. Get a new link and try again.', 'bad_state');
+  }
+  const code = callback.searchParams.get('code');
+  if (!code) {
+    throw new SignInError('There\'s no code= in that URL.', 'bad_url');
+  }
+  const result = await post('/oauth/token', { grant_type: 'authorization_code', code, code_verifier: link.verifier, redirect_uri: REDIRECT_URI });
+  if (result.status !== 200) {
+    throw fail(result);
+  }
+  return tokens(result.json);
+}

package/lib/control.js

@@ -0,0 +1,38 @@
+// 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 }
+// It's a Unix socket in the plugin's storage folder (mode 600), so only the homebridge user can use it.
+
+import { chmodSync, rmSync } from 'node:fs';
+import { createServer } from 'node:http';
+
+export function startControlServer({ path, log, getSystem }) {
+  rmSync(path, { force: true });
+  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);
+    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' });
+    }
+    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));
+    } catch (error) {
+      reply(502, { error: error.message });
+    }
+  });
+  server.on('error', error => log.error(`Control socket ${path}: ${error.message}`));
+  server.listen(path, () => {
+    chmodSync(path, 0o600);
+    log.debug(`Control socket listening at ${path}`);
+  });
+  return server;
+}

package/lib/ecobee.js

@@ -0,0 +1,157 @@
+// ecobee cloud client: Auth0 refresh-token sign-in + the app's GraphQL API (see docs in README).
+
+export const AUTH = 'https://auth.ecobee.com';
+export const GRAPHQL = 'https://federated-api.prod.federated-graph.generacapis.com/graphql';
+export const CLIENT_ID = 'CuGkX8Ai7OWD2V1F32rFa7UJGRVRsnbv';
+export const REDIRECT_URI = 'com.ecobee.athenamobile://auth.ecobee.com/ios/com.ecobee.athenamobile/callback';
+export const AUDIENCE = 'https://prod.ecobee.com/api/v1';
+export const SCOPE = 'openid profile offline_access smartWrite piiWrite piiRead';
+
+const APP_VERSION = '26.18.0+607111';
+const USER_AGENT = 'ecobee/607111 CFNetwork/3896.100.1.2.1 Darwin/27.0.0';
+const TIMEOUT = 20 * 1000;
+
+export const ArmedState = {
+  STAY: 'ARMED_STAY',
+  AWAY: 'ARMED_AWAY',
+  DISARMED: 'DISARMED',
+};
+
+const MONITORING_FIELDS = 'armedState delayedArmedState { desiredArmedState delayedUntil }';
+
+const STATE_QUERY = `query HomesSecurity { homes { id name capabilities monitoring { ${MONITORING_FIELDS} `
+  + 'incidents { id status detectedIntrusion detectedSmokeAlarm } '
+  + 'homeMonitoringSettings { isProfessionalMonitoringEnabled armedStateSettings { '
+  + 'armedAway { entryDelayDuration exitDelayDuration } armedStay { entryDelayDuration exitDelayDuration } } } } } }';
+
+const SET_MUTATION = 'mutation SetArmedStateForHome($input: SetArmedStateForHomeInput!) { '
+  + `setArmedStateForHome(input: $input) { home { id monitoring { ${MONITORING_FIELDS} } } success } }`;
+
+/** The refresh token was rejected; a new browser sign-in is needed. */
+export class SignInRequiredError extends Error {}
+
+export class EcobeeCloud {
+  /**
+   * @param {object} options
+   * @param {string} options.refreshToken
+   * @param {(token: string) => void} options.onRefreshToken called when Auth0 hands out a new refresh token
+   * @param {import('homebridge').Logging} options.log
+   */
+  constructor({ refreshToken, onRefreshToken, log }) {
+    this.refreshToken = refreshToken;
+    this.onRefreshToken = onRefreshToken;
+    this.log = log;
+    this.accessToken = undefined;
+    this.expiresAt = 0;
+    this.renewing = undefined;
+  }
+
+  async token() {
+    if (this.accessToken && Date.now() < this.expiresAt - 5 * 60 * 1000) {
+      return this.accessToken;
+    }
+    // Several polls/commands may need a token at once; renew only once.
+    this.renewing ??= this.renew().finally(() => {
+      this.renewing = undefined;
+    });
+    return this.renewing;
+  }
+
+  async renew() {
+    if (!this.refreshToken) {
+      throw new SignInRequiredError('no refresh token');
+    }
+    const json = await tokenRequest({ grant_type: 'refresh_token', refresh_token: this.refreshToken });
+    this.accessToken = json.access_token;
+    this.expiresAt = Date.now() + (json.expires_in ?? 7200) * 1000;
+    if (json.refresh_token && json.refresh_token !== this.refreshToken) {
+      this.refreshToken = json.refresh_token;
+      this.onRefreshToken(json.refresh_token);
+    }
+    this.log.debug(`Signed in to ecobee (token valid ${Math.round((json.expires_in ?? 7200) / 60)} min)`);
+    return this.accessToken;
+  }
+
+  async graphql(operationName, query, variables, retry = true) {
+    const token = await this.token();
+    const res = await fetch(GRAPHQL, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json',
+        authorization: `Bearer ${token}`,
+        'apollographql-client-name': 'com.ecobee.athenamobile-apollo-ios',
+        'apollographql-client-version': APP_VERSION,
+        'x-apollo-operation-name': operationName,
+        'user-agent': USER_AGENT,
+      },
+      body: JSON.stringify({ operationName, query, variables }),
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+    if (res.status === 401 && retry) {
+      this.accessToken = undefined;
+      return this.graphql(operationName, query, variables, false);
+    }
+    const text = await res.text();
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`${operationName}: HTTP ${res.status}, unexpected reply ${text.slice(0, 120).replace(/\s+/g, ' ')}`);
+    }
+    if (json.errors?.length) {
+      const message = json.errors.map(e => e.message).join('; ');
+      if (retry && /unauth|expired|jwt/i.test(message)) {
+        this.accessToken = undefined;
+        return this.graphql(operationName, query, variables, false);
+      }
+      throw new Error(`${operationName}: ${message}`);
+    }
+    if (!res.ok) {
+      throw new Error(`${operationName}: HTTP ${res.status}`);
+    }
+    return json.data;
+  }
+
+  /** All homes on the account with their security state. */
+  async getHomes() {
+    const data = await this.graphql('HomesSecurity', STATE_QUERY);
+    return data.homes ?? [];
+  }
+
+  /**
+   * @param {string} homeId
+   * @param {string} armedState one of ArmedState
+   * @param {number} exitDelay seconds; the app sends the exit delay as a timestamp
+   * @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');
+    const data = await this.graphql('SetArmedStateForHome', SET_MUTATION, {
+      input: { homeId, armedState, exitDelayUntil },
+    });
+    const result = data.setArmedStateForHome;
+    if (!result?.success) {
+      throw new Error(`ecobee refused ${armedState}`);
+    }
+    return result.home?.monitoring;
+  }
+}
+
+export async function tokenRequest(body) {
+  const res = await fetch(`${AUTH}/oauth/token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ client_id: CLIENT_ID, ...body }),
+    signal: AbortSignal.timeout(TIMEOUT),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = `ecobee sign-in failed (${res.status} ${json.error ?? ''}: ${json.error_description ?? ''})`;
+    if (json.error === 'invalid_grant' || json.error === 'unauthorized_client') {
+      throw new SignInRequiredError(message);
+    }
+    throw new Error(message);
+  }
+  return json;
+}

package/lib/platform.js

@@ -0,0 +1,151 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { EcobeeCloud, SignInRequiredError } from './ecobee.js';
+import { startControlServer } from './control.js';
+import { SecuritySystem } from './security.js';
+
+export const PLUGIN_NAME = 'homebridge-ecobee-security';
+export const PLATFORM_NAME = 'EcobeeSecurityPlatform';
+
+const RETRY_START = 60 * 1000;
+
+export class EcobeeSecurityPlatform {
+  /**
+   * @param {import('homebridge').Logging} log
+   * @param {import('homebridge').PlatformConfig} config
+   * @param {import('homebridge').API} api
+   */
+  constructor(log, config, api) {
+    this.log = log;
+    this.config = config ?? {};
+    this.api = api;
+    this.cached = [];
+
+    const dir = join(api.user.storagePath(), 'ecobee-security');
+    mkdirSync(dir, { recursive: true });
+    this.storePath = join(dir, 'state.json');
+    this.store = this.load();
+
+    // A refresh token newly pasted into the settings wins over the one we've been keeping.
+    const configured = this.config.refreshToken?.trim();
+    if (configured && configured !== this.store.configuredToken) {
+      this.store.refreshToken = configured;
+      this.store.configuredToken = configured;
+      this.save();
+    }
+
+    if (!this.store.refreshToken) {
+      log.error('No ecobee refresh token. Sign in with bin/ecobee-login.js (see the plugin README), '
+        + 'paste the refresh token into the plugin settings and restart the bridge.');
+      return;
+    }
+
+    this.cloud = new EcobeeCloud({
+      refreshToken: this.store.refreshToken,
+      onRefreshToken: (token) => {
+        this.store.refreshToken = token;
+        this.save();
+      },
+      log,
+    });
+
+    api.on('didFinishLaunching', () => {
+      this.control = startControlServer({ path: join(dir, 'control.sock'), log, getSystem: () => this.system });
+      this.launch();
+    });
+    api.on('shutdown', () => {
+      clearTimeout(this.retryTimer);
+      this.control?.close();
+      this.system?.stop();
+    });
+  }
+
+  /** @param {import('homebridge').PlatformAccessory} accessory */
+  configureAccessory(accessory) {
+    this.cached.push(accessory);
+  }
+
+  load() {
+    try {
+      return JSON.parse(readFileSync(this.storePath, 'utf8'));
+    } catch {
+      return {};
+    }
+  }
+
+  save() {
+    try {
+      writeFileSync(this.storePath, JSON.stringify(this.store, null, 2), { mode: 0o600 });
+      chmodSync(this.storePath, 0o600);
+    } catch (error) {
+      this.log.warn(`Could not save plugin state: ${error.message}`);
+    }
+  }
+
+  async launch(retryIn = RETRY_START) {
+    try {
+      await this.setup();
+    } catch (error) {
+      if (error instanceof SignInRequiredError) {
+        this.log.error(`${error.message}. Sign in again with bin/ecobee-login.js (see the plugin README), `
+          + 'paste the new refresh token into the plugin settings and restart the bridge.');
+        return;
+      }
+      this.log.warn(`Startup failed (${error.message}); retrying in ${retryIn / 1000} s.`);
+      this.retryTimer = setTimeout(() => this.launch(Math.min(retryIn * 2, 30 * 60 * 1000)), retryIn);
+    }
+  }
+
+  async setup() {
+    const homes = await this.cloud.getHomes();
+    const wanted = this.config.homeId?.trim();
+    const home = wanted
+      ? homes.find(h => h.id === wanted)
+      : homes.find(h => h.capabilities?.includes('HOME_MONITORING') && h.monitoring) ?? homes.find(h => h.monitoring);
+    if (!home) {
+      this.log.error(wanted
+        ? `No home with id ${wanted} on this ecobee account. Homes: ${homes.map(h => `${h.name} (${h.id})`).join(', ')}`
+        : 'No home with Smart Security on this ecobee account.');
+      return;
+    }
+    if (!wanted && homes.length > 1) {
+      this.log.warn(`Several homes on this account; using "${home.name}". Set "homeId" in the plugin settings to pick another: `
+        + homes.map(h => `${h.name} (${h.id})`).join(', '));
+    }
+
+    const uuid = this.api.hap.uuid.generate(`ecobee-security:${home.id}`);
+    const stale = this.cached.filter(a => a.UUID !== uuid);
+    if (stale.length) {
+      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale);
+    }
+    let accessory = this.cached.find(a => a.UUID === uuid);
+    const isNew = !accessory;
+    if (isNew) {
+      accessory = new this.api.platformAccessory(this.config.name || 'Security System', uuid);
+    }
+
+    this.system = new SecuritySystem({
+      api: this.api,
+      log: this.log,
+      accessory,
+      cloud: this.cloud,
+      home,
+      pollInterval: Math.max(5, Number(this.config.pollInterval) || 10),
+      store: this.store,
+      save: () => this.save(),
+    });
+    if (isNew) {
+      this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+    } else {
+      this.api.updatePlatformAccessories([accessory]);
+    }
+    this.system.start();
+    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}).`);
+    }
+  }
+}

package/lib/security.js

@@ -0,0 +1,303 @@
+import { ArmedState, SignInRequiredError } from './ecobee.js';
+
+// HomeKit SecuritySystemCurrentState / TargetState values.
+const Hk = {
+  STAY: 0,
+  AWAY: 1,
+  NIGHT: 2,
+  DISARMED: 3,
+  TRIGGERED: 4,
+};
+
+const HK_NAMES = ['Armed Stay', 'Armed Away', 'Armed Night', 'Disarmed', 'Alarm triggered'];
+
+const TO_ECOBEE = {
+  [Hk.STAY]: ArmedState.STAY,
+  [Hk.AWAY]: ArmedState.AWAY,
+  [Hk.DISARMED]: ArmedState.DISARMED,
+};
+
+const FROM_ECOBEE = {
+  [ArmedState.STAY]: Hk.STAY,
+  [ArmedState.AWAY]: Hk.AWAY,
+  [ArmedState.DISARMED]: Hk.DISARMED,
+};
+
+// Incident statuses that mean the alarm is over. Anything else counts as triggered.
+const CLOSED_INCIDENT = /RESOLV|CLOS|CANCEL|DISMISS|END|FALSE|COMPLETE|EXPIRE/i;
+
+const MAX_BACKOFF = 5 * 60 * 1000;
+const FAULT_AFTER = 3;
+
+export class SecuritySystem {
+  /**
+   * @param {object} options
+   * @param {import('homebridge').API} options.api
+   * @param {import('homebridge').Logging} options.log
+   * @param {import('homebridge').PlatformAccessory} options.accessory
+   * @param {import('./ecobee.js').EcobeeCloud} options.cloud
+   * @param {object} options.home first GraphQL home object
+   * @param {number} options.pollInterval seconds
+   * @param {object} options.store persisted plugin state (`hold` lives here)
+   * @param {() => void} options.save persist `store`
+   */
+  constructor({ api, log, accessory, cloud, home, pollInterval, store, save }) {
+    this.api = api;
+    this.store = store;
+    this.save = save;
+    this.queue = Promise.resolve();
+    this.log = log;
+    this.accessory = accessory;
+    this.cloud = cloud;
+    this.homeId = home.id;
+    this.pollInterval = pollInterval * 1000;
+    this.failures = 0;
+    this.commandAt = 0;
+    this.stopped = false;
+
+    const { Service, Characteristic } = api.hap;
+    this.C = Characteristic;
+
+    accessory.getService(Service.AccessoryInformation)
+      .setCharacteristic(Characteristic.Manufacturer, 'ecobee')
+      .setCharacteristic(Characteristic.Model, 'Smart Security')
+      .setCharacteristic(Characteristic.SerialNumber, home.id);
+
+    this.service = accessory.getService(Service.SecuritySystem)
+      ?? accessory.addService(Service.SecuritySystem, accessory.displayName);
+    this.service.getCharacteristic(Characteristic.SecuritySystemCurrentState)
+      .setProps({ validValues: [Hk.STAY, Hk.AWAY, Hk.DISARMED, Hk.TRIGGERED] });
+    this.service.getCharacteristic(Characteristic.SecuritySystemTargetState)
+      .setProps({ validValues: [Hk.STAY, Hk.AWAY, Hk.DISARMED] })
+      .onSet(value => this.setTarget(value));
+    if (!this.service.testCharacteristic(Characteristic.StatusFault)) {
+      this.service.addCharacteristic(Characteristic.StatusFault);
+    }
+
+    this.apply(home);
+  }
+
+  start() {
+    this.schedule(this.pollInterval);
+  }
+
+  stop() {
+    this.stopped = true;
+    clearTimeout(this.timer);
+  }
+
+  schedule(delay) {
+    if (this.stopped) {
+      return;
+    }
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.poll(), delay);
+  }
+
+  async poll() {
+    const startedAt = Date.now();
+    let next = this.pollInterval;
+    try {
+      const homes = await this.cloud.getHomes();
+      const home = homes.find(h => h.id === this.homeId);
+      if (!home) {
+        throw new Error('the home is no longer on this ecobee account');
+      }
+      // A command that finished while this poll was running is newer than what we just read.
+      if (startedAt >= this.commandAt) {
+        this.apply(home);
+      }
+      if (this.failures >= FAULT_AFTER) {
+        this.log.info('ecobee is reachable again.');
+      }
+      this.failures = 0;
+      this.setFault(false);
+      const until = Date.parse(home.monitoring?.delayedArmedState?.delayedUntil ?? '');
+      if (until > Date.now()) {
+        // Catch the end of an exit delay promptly.
+        next = Math.min(next, until - Date.now() + 1500);
+      }
+    } catch (error) {
+      this.failures += 1;
+      if (error instanceof SignInRequiredError) {
+        this.setFault(true);
+        this.log.error(`${error.message}. Sign in again: run bin/ecobee-login.js (see the plugin README), `
+          + 'paste the new refresh token into the plugin settings and restart the bridge.');
+        return;
+      }
+      next = Math.min(this.pollInterval * 2 ** this.failures, MAX_BACKOFF);
+      if (this.failures === FAULT_AFTER) {
+        this.setFault(true);
+      }
+      const say = this.failures >= FAULT_AFTER ? 'warn' : 'debug';
+      this.log[say](`Could not read the security state (${error.message}); retrying in ${Math.round(next / 1000)} s.`);
+    }
+    this.schedule(next);
+  }
+
+  setFault(on) {
+    const { StatusFault } = this.C;
+    this.service.updateCharacteristic(StatusFault, on ? StatusFault.GENERAL_FAULT : StatusFault.NO_FAULT);
+  }
+
+  /** Apply a GraphQL home (or just its monitoring object) to HomeKit. */
+  apply(home) {
+    const monitoring = home.monitoring ?? {};
+    if (monitoring.homeMonitoringSettings) {
+      this.settings = monitoring.homeMonitoringSettings;
+    }
+    if (monitoring.incidents) {
+      this.noteIncidents(monitoring.incidents);
+    }
+    if (monitoring.armedState) {
+      this.monitoring = monitoring;
+    }
+    if (!this.monitoring) {
+      return;
+    }
+
+    const armed = FROM_ECOBEE[this.monitoring.armedState] ?? Hk.DISARMED;
+    const desired = this.monitoring.delayedArmedState?.desiredArmedState;
+    const target = desired ? (FROM_ECOBEE[desired] ?? armed) : armed;
+    const current = this.triggered ? Hk.TRIGGERED : armed;
+
+    const { SecuritySystemCurrentState, SecuritySystemTargetState } = this.C;
+    const before = this.current;
+    if (before !== current || this.target !== target) {
+      const pending = target !== armed ? ` (arming ${HK_NAMES[target]} until ${this.monitoring.delayedArmedState?.delayedUntil})` : '';
+      this.log.info(`Security system: ${HK_NAMES[current]}${pending}`);
+    }
+    this.current = current;
+    this.target = target;
+    if (this.store.hold && (target !== Hk.STAY || current === Hk.TRIGGERED)) {
+      this.log.info(`Security system changed to ${HK_NAMES[current === Hk.TRIGGERED ? current : target]} during the `
+        + `${this.store.hold.by} hold; it won't be put back to Away.`);
+      this.dropHold();
+    }
+    this.service.updateCharacteristic(SecuritySystemTargetState, target);
+    this.service.updateCharacteristic(SecuritySystemCurrentState, current);
+  }
+
+  noteIncidents(incidents) {
+    const active = incidents.filter(i => !CLOSED_INCIDENT.test(i.status ?? ''));
+    const summary = JSON.stringify(incidents);
+    if (summary !== this.incidentSummary) {
+      if (incidents.length || this.incidentSummary !== undefined) {
+        this.log.info(`Incidents: ${incidents.length ? summary : 'none'}`);
+      }
+      this.incidentSummary = summary;
+    }
+    this.triggered = active.length > 0;
+  }
+
+  exitDelay(value) {
+    const settings = this.settings?.armedStateSettings;
+    if (value === Hk.AWAY) {
+      return settings?.armedAway?.exitDelayDuration ?? 60;
+    }
+    if (value === Hk.STAY) {
+      return settings?.armedStay?.exitDelayDuration ?? 0;
+    }
+    return 0;
+  }
+
+  async setTarget(value) {
+    if (!TO_ECOBEE[value]) {
+      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.dropHold();
+    }
+    try {
+      await this.serial(() => this.arm(value, 'Home app'));
+    } catch (error) {
+      // Put the Home app's target back to what ecobee really has.
+      setTimeout(() => this.service.updateCharacteristic(this.C.SecuritySystemTargetState, this.target ?? Hk.DISARMED), 500);
+      throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+    }
+  }
+
+  /** Run hold/release/Home app commands one at a time. */
+  serial(fn) {
+    const run = this.queue.then(fn, fn);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+
+  async arm(value, source) {
+    const armedState = TO_ECOBEE[value];
+    const delay = this.exitDelay(value);
+    this.log.info(`${source}: ${value === Hk.DISARMED ? 'disarm' : `arm ${armedState === ArmedState.STAY ? 'Stay' : 'Away'}`}`
+      + (delay ? ` (exit delay ${delay} s)` : ''));
+    try {
+      const monitoring = await this.cloud.setArmedState(this.homeId, armedState, delay);
+      this.commandAt = Date.now();
+      if (monitoring) {
+        this.apply({ monitoring });
+      }
+      this.schedule(2000);
+    } catch (error) {
+      this.log.error(`Could not change the security system: ${error.message}`);
+      this.schedule(2000);
+      throw error;
+    }
+  }
+
+  dropHold() {
+    delete this.store.hold;
+    this.save();
+  }
+
+  /**
+   * 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
+   * `{ ok, held, state }`: `ok` false means it isn't safe to start (alarm triggered, or the
+   * state isn't known yet).
+   */
+  hold(by) {
+    return this.serial(async () => {
+      if (!this.monitoring || this.failures >= FAULT_AFTER) {
+        return { ok: false, held: false, state: 'unknown', reason: 'the security state is unknown' };
+      }
+      if (this.current === Hk.TRIGGERED) {
+        return { ok: false, held: false, state: HK_NAMES[this.current], reason: 'the alarm is triggered' };
+      }
+      if (this.store.hold) {
+        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.save();
+      return { ok: true, held: true, state: HK_NAMES[this.target] };
+    });
+  }
+
+  /** 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 () => {
+      if (!this.store.hold) {
+        return { released: false, state: HK_NAMES[this.target] };
+      }
+      if (this.target !== Hk.STAY || this.current === Hk.TRIGGERED) {
+        this.log.info(`${by} is done, but the security system is ${HK_NAMES[this.current]}; leaving it.`);
+        this.dropHold();
+        return { released: false, state: HK_NAMES[this.target] };
+      }
+      // Drop the hold first so apply() doesn't take our own Away for someone else's change.
+      const hold = this.store.hold;
+      this.dropHold();
+      try {
+        await this.arm(Hk.AWAY, `${by} done`);
+      } catch (error) {
+        this.store.hold = hold;
+        this.save();
+        throw error;
+      }
+      return { released: true, state: HK_NAMES[this.target] };
+    });
+  }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "homebridge-ecobee-security",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "displayName": "ecobee Smart Security",
+  "version": "0.3.0",
+  "description": "ecobee Smart Security as a HomeKit security system: arm Stay / Away, disarm, alarm state (unofficial, ecobee cloud)",
+  "type": "module",
+  "main": "index.js",
+  "license": "MIT",
+  "author": "Sean Fletcher",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanfletchr/homebridge-ecobee-security.git"
+  },
+  "bugs": {
+    "url": "https://github.com/seanfletchr/homebridge-ecobee-security/issues"
+  },
+  "homepage": "https://github.com/seanfletchr/homebridge-ecobee-security#readme",
+  "keywords": [
+    "homebridge-plugin",
+    "homebridge",
+    "homekit",
+    "ecobee",
+    "smart security",
+    "security system",
+    "alarm"
+  ],
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0",
+    "homebridge": "^1.8.0 || ^2.0.0"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "bin",
+    "homebridge-ui",
+    "config.schema.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@homebridge/plugin-ui-utils": "^2.2.6"
+  }
+}