homebridge-ecobee-security 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 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,89 @@
-# 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
+
+ecobee's login page shows a CAPTCHA to scripts and the account may use MFA, so the plugin doesn't
+take your password. You sign in once in Chrome and give the plugin a refresh token:
+
+```
+node <plugin folder>/bin/ecobee-login.js
+```
+
+(any machine with Node 22+; on the Homebridge Pi: `/opt/homebridge/bin/node /var/lib/homebridge/node_modules/homebridge-ecobee-security/bin/ecobee-login.js`).
+It prints a link and step-by-step instructions, then the refresh token. Paste the token into the
+plugin settings and restart the bridge. 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
+pasted 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.
+
+## 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,65 @@
+#!/usr/bin/env node
+// Browser sign-in for homebridge-ecobee-security. ecobee's login page shows a CAPTCHA to scripts,
+// so you sign in yourself in Chrome and paste the final redirect URL here. Prints a refresh token
+// to paste into the plugin settings (Homebridge UI > Plugins > ecobee Smart Security > Settings).
+import { createHash, randomBytes } from 'node:crypto';
+import readline from 'node:readline';
+
+import { AUDIENCE, AUTH, CLIENT_ID, REDIRECT_URI, SCOPE, tokenRequest } from '../lib/ecobee.js';
+
+function ask(question) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function main() {
+  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));
+
+  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):
+
+${url.href}
+
+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.
+`);
+
+  const callback = new URL(await ask('Callback URL: '));
+  if (callback.searchParams.get('state') !== state) {
+    throw new Error('that URL is from a different sign-in attempt; run this again');
+  }
+  const code = callback.searchParams.get('code');
+  if (!code) {
+    throw new Error('no code= in that URL');
+  }
+  const tokens = await tokenRequest({ grant_type: 'authorization_code', code, code_verifier: verifier, redirect_uri: REDIRECT_URI });
+  if (!tokens.refresh_token) {
+    throw new Error('signed in, but ecobee returned no refresh token');
+  }
+  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().catch(error => {
+  console.error(`Sign-in failed: ${error.message}`);
+  process.exit(1);
+});

package/config.schema.json

@@ -0,0 +1,36 @@
+{
+  "pluginAlias": "EcobeeSecurityPlatform",
+  "pluginType": "platform",
+  "singular": 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. To get a refresh token, run bin/ecobee-login.js from this plugin's folder (see README).",
+  "schema": {
+    "type": "object",
+    "required": ["refreshToken"],
+    "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": "From bin/ecobee-login.js. 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/index.js

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

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,40 @@
 {
   "name": "homebridge-ecobee-security",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "displayName": "ecobee Smart Security",
+  "version": "0.2.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",
+    "config.schema.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}