homebridge-withings-environment-data 0.1.5 → 0.3.1

package/README.md

@@ -54,14 +54,38 @@ Fields:
   matching the scale's own upload cadence).
 - **CO2 Detected Threshold (ppm)**: ppm above which the CarbonDioxideSensor
   reports "abnormal" (default 1000).
+- **ntfy Topic (optional)**: if set, sends a push notification via
+  [ntfy.sh](https://ntfy.sh) to this topic the first time a poll fails
+  (not repeated on every subsequent failure in the same streak — only once
+  a poll succeeds again does the next failure trigger a fresh
+  notification). Leave blank to disable.
+
+## How authentication works
+
+The plugin reuses a long-lived (~1 week) `session_key`, the same
+mechanism Withings' own web app relies on to stay logged in without
+re-entering credentials each time.
+
+That session is cached in a small file in Homebridge's own storage
+directory, `withings-environment-data-session.json`, and reused across
+polls and restarts. Email/password only get used as a fallback, the rare
+times that cached session actually expires, and the fresh session that
+fallback produces is automatically written back to the same file for next
+time. In normal operation the plugin should hit the password endpoint very
+infrequently, roughly weekly at most.
 
 ## When it stops working
 
-If the Homebridge log shows a "session not trusted (landed on confirm_totp)"
-error, the device-trust cookie has been invalidated (e.g. after a password
-change, or Withings revoking trusted devices). The Home app will keep
-showing the last known good reading, it won't go blank, but a fault
-indicator appears on the sensors until this is fixed. Fix:
+Most of the time this is self-healing: if the cached session has expired,
+the plugin automatically falls back to a full login and caches the new
+session it gets back, no action needed. A fault indicator appears on the
+sensors during a failed poll, but the Home app keeps showing the last known
+good reading rather than going blank.
+
+If the Homebridge log instead shows a "session not trusted (landed on
+confirm_totp)" error, the *trust cookie* itself has been invalidated (e.g.
+after a password change, or Withings revoking trusted devices) — this is
+what the fallback login relies on, so it can't self-heal on its own. Fix:
 
 1. Recapture the trust cookie: see [Getting the trust
    cookie](#getting-the-trust-cookie) below.

package/config.schema.json

@@ -48,6 +48,18 @@
         "type": "integer",
         "default": 1000,
         "minimum": 400
+      },
+      "noResponseAfterMissedPolls": {
+        "title": "No Response After Missed Polls",
+        "type": "integer",
+        "default": 2,
+        "minimum": 0,
+        "description": "Consecutive failed polls to tolerate (keeping the last known readings) before the Home app shows \"No Response\". 0 means show it immediately on any failure."
+      },
+      "ntfyTopic": {
+        "title": "ntfy Topic (optional)",
+        "type": "string",
+        "description": "If set, sends a push notification via ntfy.sh to this topic the first time a poll fails (not repeated on every subsequent failure in the same streak). Leave blank to disable."
       }
     }
   }

package/index.js

@@ -1,6 +1,10 @@
-const { login } = require('./lib/login');
+const fs = require('fs');
+const path = require('path');
+const { login, resumeSession } = require('./lib/login');
 const { discoverDevice } = require('./lib/discover');
 
+const SESSION_STATE_FILENAME = 'withings-environment-data-session.json';
+
 const MEASURE_URL = 'https://scalews.withings.com/cgi-bin/v2/measure';
 // Reverse-engineered/unofficial: not part of the documented Withings API.
 const MEASTYPE_CO2 = 35;
@@ -81,9 +85,74 @@ class WithingsEnvironmentDataPlatform {
     this.deviceId = null;
     this.userId = null;
 
+    // Cached last-known reading, served by the onGet handlers below so the
+    // Home app keeps showing real data through transient poll failures.
+    // Only once missedCycles exceeds the configured threshold do those
+    // handlers throw, which is what actually makes the Home app show
+    // "No Response" (StatusFault alone isn't reliably surfaced there).
+    this.hasEverSucceeded = false;
+    this.missedCycles = 0;
+    this.lastReading = { co2: null, temperature: null };
+    // Only send one ntfy notification per failure streak, not on every
+    // missed poll — reset once a poll succeeds again.
+    this.hasNotifiedFailure = false;
+
+    // The long-lived (~1 week) session_key that lets us skip email/password/2FA
+    // entirely on most polls — see lib/login.js's resumeSession(). Persisted to
+    // disk so it survives Homebridge restarts, and only a full login() refreshes
+    // it, since repeatedly hitting the password endpoint appears to be heavily
+    // throttled by Withings.
+    this.sessionStatePath = path.join(this.api.user.storagePath(), SESSION_STATE_FILENAME);
+    this.sessionKey = this.loadSessionKey();
+
     this.api.on('didFinishLaunching', () => this.discoverDevices());
   }
 
+  loadSessionKey() {
+    try {
+      const raw = fs.readFileSync(this.sessionStatePath, 'utf8');
+      return JSON.parse(raw).sessionKey ?? null;
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        this.log.warn(`Could not read session state file: ${err.message}`);
+      }
+      return null;
+    }
+  }
+
+  saveSessionKey(sessionKey) {
+    try {
+      fs.writeFileSync(this.sessionStatePath, JSON.stringify({ sessionKey }));
+    } catch (err) {
+      this.log.warn(`Could not persist session state file: ${err.message}`);
+    }
+  }
+
+  async authenticate() {
+    if (this.sessionKey) {
+      try {
+        return await resumeSession(this.sessionKey, this.config.trustCookieName, this.config.trustCookieValue);
+      } catch (err) {
+        this.log.warn(`Withings session resume failed, falling back to full login: ${err.message}`);
+      }
+    }
+
+    const result = await login(
+      this.config.email,
+      this.config.password,
+      this.config.trustCookieName,
+      this.config.trustCookieValue
+    );
+
+    if (result.sessionKey && result.sessionKey !== this.sessionKey) {
+      this.sessionKey = result.sessionKey;
+      this.saveSessionKey(result.sessionKey);
+      this.log.info('Withings full login succeeded; cached the new session for future polls.');
+    }
+
+    return result;
+  }
+
   configureAccessory(accessory) {
     this.log.info('Loading accessory from cache:', accessory.displayName);
     this.accessories.push(accessory);
@@ -122,6 +191,19 @@ class WithingsEnvironmentDataPlatform {
     this.temperatureService =
       accessory.getService(this.Service.TemperatureSensor) ||
       accessory.addService(this.Service.TemperatureSensor, 'Temperature', 'temperature');
+
+    this.co2Service
+      .getCharacteristic(this.Characteristic.CarbonDioxideLevel)
+      .onGet(() => this.getCo2LevelOrThrow());
+    this.co2Service
+      .getCharacteristic(this.Characteristic.CarbonDioxideDetected)
+      .onGet(() => this.getCo2DetectedOrThrow());
+    this.airQualityService
+      .getCharacteristic(this.Characteristic.AirQuality)
+      .onGet(() => this.getAirQualityOrThrow());
+    this.temperatureService
+      .getCharacteristic(this.Characteristic.CurrentTemperature)
+      .onGet(() => this.getTemperatureOrThrow());
   }
 
   startPolling() {
@@ -134,12 +216,7 @@ class WithingsEnvironmentDataPlatform {
 
   async poll() {
     try {
-      const { cookieHeader, sessionToken } = await login(
-        this.config.email,
-        this.config.password,
-        this.config.trustCookieName,
-        this.config.trustCookieValue
-      );
+      const { cookieHeader, sessionToken } = await this.authenticate();
 
       if (!this.deviceId || !this.userId) {
         const discovered = await discoverDevice(cookieHeader);
@@ -160,20 +237,89 @@ class WithingsEnvironmentDataPlatform {
 
       this.applyReading(co2, temperature);
       this.setFault(false);
+      this.missedCycles = 0;
+      this.hasNotifiedFailure = false;
     } catch (err) {
       // Deliberately do not touch the value characteristics here — the Home app
-      // should keep showing the last known good reading, not go blank, when a
-      // poll fails (e.g. the trust cookie expired and login needs recapturing).
-      this.log.error(`Withings poll failed: ${err.message}`);
+      // should keep showing the last known good reading, not go blank, on a
+      // single poll failure (e.g. the trust cookie expired and login needs
+      // recapturing). Only once missedCycles crosses the configured threshold
+      // do the onGet handlers below start throwing, which is what actually
+      // surfaces "No Response" in the Home app.
+      this.missedCycles += 1;
+      this.log.error(`Withings poll failed (missed cycle ${this.missedCycles}): ${err.message}`);
       this.setFault(true);
+
+      if (!this.hasNotifiedFailure) {
+        this.hasNotifiedFailure = true;
+        await this.sendNtfyNotification(err.message);
+      }
     }
   }
 
-  applyReading(co2, temperature) {
+  async sendNtfyNotification(errorMessage) {
+    const topic = this.config.ntfyTopic;
+    if (!topic) return;
+
+    try {
+      await fetch(`https://ntfy.sh/${encodeURIComponent(topic)}`, {
+        method: 'POST',
+        headers: { Title: 'Homebridge: Getting Withings Environment Data Failed!' },
+        body: `${errorMessage}\n\nThe Home app will keep showing the last known reading until this is resolved.`,
+      });
+    } catch (err) {
+      this.log.warn(`Failed to send ntfy notification: ${err.message}`);
+    }
+  }
+
+  getCo2Threshold() {
     const threshold = Number(this.config.co2DetectedThresholdPpm);
-    const co2Threshold = Number.isFinite(threshold) && threshold > 0 ? threshold : 1000;
+    return Number.isFinite(threshold) && threshold > 0 ? threshold : 1000;
+  }
+
+  getNoResponseThreshold() {
+    const threshold = Number(this.config.noResponseAfterMissedPolls);
+    return Number.isFinite(threshold) && threshold >= 0 ? threshold : 2;
+  }
+
+  isStale() {
+    return !this.hasEverSucceeded || this.missedCycles > this.getNoResponseThreshold();
+  }
+
+  throwIfStale() {
+    if (this.isStale()) {
+      throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
+    }
+  }
+
+  getCo2LevelOrThrow() {
+    this.throwIfStale();
+    return this.lastReading.co2;
+  }
+
+  getCo2DetectedOrThrow() {
+    this.throwIfStale();
+    return this.lastReading.co2 > this.getCo2Threshold()
+      ? this.Characteristic.CarbonDioxideDetected.CO2_LEVELS_ABNORMAL
+      : this.Characteristic.CarbonDioxideDetected.CO2_LEVELS_NORMAL;
+  }
+
+  getAirQualityOrThrow() {
+    this.throwIfStale();
+    return mapCo2ToAirQuality(this.lastReading.co2, this.Characteristic.AirQuality);
+  }
+
+  getTemperatureOrThrow() {
+    this.throwIfStale();
+    return this.lastReading.temperature;
+  }
+
+  applyReading(co2, temperature) {
+    const co2Threshold = this.getCo2Threshold();
 
     if (co2 !== null && co2 !== undefined) {
+      this.lastReading.co2 = co2;
+      this.hasEverSucceeded = true;
       this.co2Service.updateCharacteristic(this.Characteristic.CarbonDioxideLevel, co2);
       this.co2Service.updateCharacteristic(
         this.Characteristic.CarbonDioxideDetected,
@@ -188,6 +334,8 @@ class WithingsEnvironmentDataPlatform {
     }
 
     if (temperature !== null && temperature !== undefined) {
+      this.lastReading.temperature = temperature;
+      this.hasEverSucceeded = true;
       this.temperatureService.updateCharacteristic(this.Characteristic.CurrentTemperature, temperature);
     }
   }

package/lib/login.js

@@ -34,6 +34,10 @@ class CookieJar {
     this.cookies.set(name, value);
   }
 
+  get(name) {
+    return this.cookies.get(name);
+  }
+
   toHeader() {
     return Array.from(this.cookies.entries())
       .map(([name, value]) => `${name}=${value}`)
@@ -91,12 +95,51 @@ async function requestFollowingRedirects(method, url, body, jar, maxHops = 10) {
   throw new Error(`Withings login exceeded ${maxHops} redirect hops starting from ${url}`);
 }
 
+function buildResult(jar) {
+  const sessionTokenCookie = jar.findByPrefix('2fa_token_');
+  if (!sessionTokenCookie) {
+    throw new Error(
+      'Withings session established but no 2fa_token_* cookie was found — the login flow may have changed.'
+    );
+  }
+
+  return {
+    cookieHeader: jar.toHeader(),
+    sessionToken: sessionTokenCookie.value,
+    sessionKey: jar.get('session_key') ?? null,
+  };
+}
+
+// Fast path: account.withings.com hands out a long-lived (~1 week) session_key
+// cookie that, when replayed, skips straight past email/password/2FA entirely
+// (redirects to /new_workflow/exit instead of asking for credentials at all).
+// Confirmed empirically this doesn't need w_uuid alongside it. Throws if the
+// session_key has expired/is invalid, signaling the caller to fall back to login().
+async function resumeSession(sessionKey, trustCookieName, trustCookieValue) {
+  const jar = new CookieJar();
+  jar.set(trustCookieName, trustCookieValue);
+  jar.set('session_key', sessionKey);
+
+  const { finalUrl } = await requestFollowingRedirects(
+    'GET',
+    `${ACCOUNT_BASE}/new_workflow/login`,
+    undefined,
+    jar
+  );
+
+  if (!finalUrl.includes('/new_workflow/exit')) {
+    throw new Error('Withings session_key did not resume a session (did not land on /new_workflow/exit)');
+  }
+
+  return buildResult(jar);
+}
+
+// Full fallback flow: email + password + trust cookie. Only needed the first
+// time, or once the long-lived session_key from resumeSession() has actually
+// expired — this is what Withings appears to throttle heavily if hit too
+// often, so resumeSession() should always be tried first.
 async function login(email, password, trustCookieName, trustCookieValue) {
   const jar = new CookieJar();
-  // This cookie (scoped to account.withings.com) is the "this device already passed
-  // 2FA" marker — its name has stayed stable across many logins. It must be sent on
-  // the very first request of a fresh login attempt, before email/password. Confirmed
-  // empirically that no other cookie (e.g. w_uuid) is needed alongside it.
   jar.set(trustCookieName, trustCookieValue);
 
   await requestFollowingRedirects('GET', `${ACCOUNT_BASE}/`, undefined, jar);
@@ -126,17 +169,7 @@ async function login(email, password, trustCookieName, trustCookieValue) {
     );
   }
 
-  const sessionTokenCookie = jar.findByPrefix('2fa_token_');
-  if (!sessionTokenCookie) {
-    throw new Error(
-      'Withings login completed but no 2fa_token_* cookie was found — the login flow may have changed.'
-    );
-  }
-
-  return {
-    cookieHeader: jar.toHeader(),
-    sessionToken: sessionTokenCookie.value,
-  };
+  return buildResult(jar);
 }
 
-module.exports = { login };
+module.exports = { login, resumeSession };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-withings-environment-data",
-  "version": "0.1.5",
+  "version": "0.3.1",
   "description": "Homebridge plugin exposing ambient CO2/air-quality and room temperature readings from a Withings WS-50 scale as HomeKit sensors",
   "main": "index.js",
   "files": [
@@ -9,7 +9,14 @@
     "config.schema.json"
   ],
   "keywords": [
-    "homebridge-plugin"
+    "homebridge-plugin",
+    "withings",
+    "ws-50",
+    "environment-data",
+    "temperature",
+    "co2",
+    "air-quality",
+    "homekit"
   ],
   "engines": {
     "homebridge": ">=1.6.0",