homebridge-ecobee-security 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.0
+
+- `offerNight`: adds Night to the Home app; it arms ecobee's Stay and keeps showing Night. Changing
+  the setting recreates the security system in HomeKit (the Home app doesn't pick up new modes on an
+  existing control).
+- `alarmTrigger: "entryDelay"`: show Alarm triggered only once an intrusion has outlasted the entry
+  delay without a disarm, instead of as soon as ecobee opens the incident. Smoke still shows at once.
+- `smokeSensor` (on by default): a separate Smoke Alarm accessory that detects smoke while ecobee has a smoke-alarm
+  incident open.
+- Air quality (`airQuality`, on by default): for ecobee thermostats with an air quality sensor, an
+  Air Quality Sensor (level, VOC) and a Carbon Dioxide Sensor (ppm, alert at `co2Alert`, 1000 ppm).
+- The accessory reports the plugin version as its firmware version.
+- The hold API refuses a hold while any alarm incident is open, whichever `alarmTrigger` is set.
+
+## 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

package/README.md

@@ -1,7 +1,9 @@
 # homebridge-ecobee-security
 
 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
+**disarm**, and **Alarm triggered** when ecobee has an open intrusion or smoke incident. It also adds
+**air quality** sensors for ecobee thermostats that have one (ecobee Premium), which ecobee's own
+HomeKit integration leaves out. Works with
 Siri ("set the security system to away") and Home automations. ecobee removed Smart Security from
 its HomeKit integration; this brings it back.
 
@@ -27,21 +29,25 @@ Running it as a child bridge is recommended. Requires Node 22 or 24 and Homebrid
 
 ## 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:
+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.
 
-```
-node <plugin folder>/bin/ecobee-login.js
-```
+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.
 
-(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.
+**Without the Homebridge UI**, sign in from a terminal and paste the printed token into the config:
 
-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.
+```
+node <plugin folder>/bin/ecobee-login.js            # email, password, MFA code
+node <plugin folder>/bin/ecobee-login.js --browser  # website sign-in
+```
 
 ## Config
 
@@ -51,12 +57,25 @@ You only need to sign in again if ecobee revokes the token (for example after a
   "name": "Security System",
   "refreshToken": "…",
   "pollInterval": 10,
+  "offerNight": false,
+  "alarmTrigger": "incident",
+  "smokeSensor": true,
+  "airQuality": true,
+  "co2Alert": 1000,
   "_bridge": { "username": "…", "port": 51926, "name": "Ecobee Security Bridge" }
 }
 ```
 
 `homeId` is only needed if the account has several homes (the log lists them).
 
+| Setting | Default | |
+|---|---|---|
+| `offerNight` | `false` | Adds Night to the Home app. ecobee has no Night mode, so Night arms Stay and the tile keeps showing Night until the state changes (a Stay armed elsewhere shows as Stay). HomeKit only picks up a changed list of modes on a new control, so changing this setting recreates the security system in the Home app: set up scenes and automations that use it again. |
+| `alarmTrigger` | `"incident"` | When the tile enters **Triggered**: `"incident"` immediately, when ecobee opens an incident as a door or sensor trips while armed (mirrors the ecobee app); `"entryDelay"` only after the entry (disarm) delay runs out without a disarm. Smoke alarms always trigger immediately. |
+| `smokeSensor` | `true` | Adds a separate **Smoke Alarm** accessory (a Smoke Sensor) that detects smoke while ecobee has a smoke-alarm incident open, for automations and Home app smoke notifications. Set to `false` to remove it. |
+| `airQuality` | `true` | For each thermostat with an air quality sensor: an accessory "&lt;thermostat&gt; Air Quality" with an **Air Quality Sensor** (overall level; VOC as ecobee reports it, in ppb, which the Home app labels µg/m³) and a **Carbon Dioxide Sensor** (ppm). Read every 5 minutes. The level follows the ecobee app's Clean–Poor bar: its first two segments are Excellent, then Good, Fair, Inferior, Poor; Unknown while the sensor calibrates. |
+| `co2Alert` | `1000` | CO2 (ppm) at or above which the Carbon Dioxide Sensor reports abnormal levels. |
+
 ## How it behaves
 
 - **Arm Away** uses ecobee's Away exit delay (60 s by default), just like the app. During the
@@ -64,13 +83,10 @@ You only need to sign in again if ecobee revokes the token (for example after a
   (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.
+- **Alarm triggered** while ecobee lists an open incident (see `alarmTrigger` above for when it
+  starts showing). Disarming clears it. Every change in the incident list is logged.
+- **Siri:** the Home app calls Stay "Home". Asking Siri for Home or for Stay mode both arm Stay.
+- **Night** is only offered with `offerNight`; ecobee has no Night mode of its own.
 - After three failed reads in a row the accessory shows a fault; reads back off up to 5 minutes.
 - **Hold for other plugins:** a Unix socket at `<homebridge storage>/ecobee-security/control.sock`
   (mode 600, homebridge user only) lets another plugin, e.g. homebridge-narwal, ask for a temporary

package/bin/ecobee-login.js

@@ -1,56 +1,70 @@
 #!/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';
+// 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 { AUDIENCE, AUTH, CLIENT_ID, REDIRECT_URI, SCOPE, tokenRequest } from '../lib/ecobee.js';
+import { browserSignInLink, finishBrowserSignIn, finishMfa, passwordSignIn } from '../lib/auth.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());
-    });
-  });
+// 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 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));
+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):
 
-${url.href}
+${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: '));
+}
 
-  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');
-  }
+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.
@@ -59,7 +73,7 @@ ${tokens.refresh_token}
 `);
 }
 
-main().catch(error => {
+main().then(() => rl.close(), error => {
   console.error(`Sign-in failed: ${error.message}`);
   process.exit(1);
 });

package/config.schema.json

@@ -2,10 +2,10 @@
   "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).",
+  "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",
-    "required": ["refreshToken"],
     "properties": {
       "name": {
         "title": "Name",
@@ -16,8 +16,10 @@
       "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')."
+        "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",
@@ -30,6 +32,54 @@
         "default": 10,
         "minimum": 5,
         "description": "How often to read the armed state, so changes made in the ecobee app or at the keypad show up in Apple Home."
+      },
+      "offerNight": {
+        "title": "Offer Night",
+        "type": "boolean",
+        "default": false,
+        "description": "Adds Night to the Home app, for automations or Siri that use it. ecobee has no Night mode, so Night arms Stay; the Home app keeps showing Night until the state changes. Changing this setting recreates the security system in the Home app, so scenes and automations that use it have to be set up again."
+      },
+      "alarmTrigger": {
+        "title": "Enter Triggered State",
+        "type": "string",
+        "default": "incident",
+        "oneOf": [
+          {
+            "title": "Immediately (mirror ecobee app)",
+            "enum": [
+              "incident"
+            ]
+          },
+          {
+            "title": "After the Entry/Disarm delay",
+            "enum": [
+              "entryDelay"
+            ]
+          }
+        ],
+        "description": "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."
+      },
+      "smokeSensor": {
+        "title": "Smoke sensor",
+        "type": "boolean",
+        "default": true,
+        "description": "Adds a separate \"Smoke Alarm\" accessory to the Home app that detects smoke whenever ecobee reports a smoke-alarm incident, so you can use it in automations and get Home app smoke notifications."
+      },
+      "airQuality": {
+        "title": "Air quality sensors",
+        "type": "boolean",
+        "default": true,
+        "description": "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."
+      },
+      "co2Alert": {
+        "title": "CO2 alert level (ppm)",
+        "type": "integer",
+        "default": 1000,
+        "minimum": 400,
+        "description": "The Carbon Dioxide Sensor reports abnormal CO2 at or above this level, for Home app notifications and automations (for example, turning on ventilation).",
+        "condition": {
+          "functionBody": "return model.airQuality !== false;"
+        }
       }
     }
   }

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())();