homebridge-ring-secure-video 1.0.0-beta.2 → 1.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # homebridge-ring-secure-video
 
+## 1.0.0-beta.3 (2026-11-13)
+
+Fixes from a full independent review of 1.0.0-beta.2.
+
+- A second visit 30–65 s after the first now turns HomeKit motion on again, so it is recorded and
+  notified. Ring keeps a motion alert active for 65 s and only reports changes, while the plugin
+  turns motion off after 30 s; a new alert in between gave nothing. A repeat of the same alert
+  (Ring's follow-up with the snapshot, a resend) is not a new visit, and the event-history
+  fallback no longer adds its own "no motion" after 65 s, which could cut a later visit short.
+- A media setting the plugin can't use (for example a maximum bitrate below the bitrate, which
+  the settings form allows, or a stray key) no longer stops the plugin's bridge from starting
+  (which took the alarm down with it). It is ignored with a warning naming it, and the older
+  setting or the default is used. Default maximum bitrate and buffer size derived from a high
+  bitrate stay within their limits.
+- After a forced Ring refresh ("Force Ring Push Credential Refresh" or "Force Ring API Session
+  Refresh"), every new Ring token is saved, not only the first; before, the next start
+  registered with Ring again. The force settings are cleared once, and a token that can't be
+  saved is logged.
+- config.json and .ring.json are written to a temporary file and then renamed into place, so a
+  power cut or a full disk during a token renewal can't leave them cut short (Homebridge would not
+  start). Permissions, group and symlinks are kept; where that can't work (a bind-mounted file,
+  a file owned by another user, ...) they are written in place as before.
+
 ## 1.0.0-beta.2 (2026-11-13)
 
 - The Homebridge UI shows the plugin as "Ring Secure Video" (was "Homebridge Ring Secure Video"),

package/lib/camera.js

@@ -1,11 +1,45 @@
 import { hap } from "./hap.js";
+import { PushNotificationAction } from 'ring-client-api';
 import { BaseDataAccessory } from "./base-data-accessory.js";
 import { catchError, exhaustMap, filter, map, mergeMap, share, switchMap, throttleTime, } from 'rxjs/operators';
 import { CameraSource } from "./camera-source.js";
 import { TargetValueTimer } from "./target-value-timer.js";
 import { delay, logError, logInfo } from 'ring-client-api/util';
-import { EMPTY, firstValueFrom, from, merge, of, timer } from 'rxjs';
+import { defer, EMPTY, firstValueFrom, from, merge, of, timer } from 'rxjs';
 export const MOTION_WATCHDOG_MS = 30_000;
+/**
+ * Motion from Ring's push notifications, as HomeKit needs it: true for every new motion alert.
+ *
+ * ring-client-api's onMotionDetected is true while any motion alert is active (each lasts 65 s)
+ * and only reports changes, so a new alert while an earlier one is still active gives nothing.
+ * The watchdog below turns motion off after 30 s, so a second visit 30-65 s after the first
+ * would never turn it on again: no recording and no notification. So every new motion
+ * notification gives a true (restarting the watchdog), and onMotionDetected only adds its
+ * false once all alerts have expired. A notification repeating an alert seen in the last two
+ * minutes (Ring sends a second one with the snapshot; a reconnect can resend) is not a new visit.
+ */
+export const REPEATED_ALERT_WINDOW_MS = 120_000;
+export function getPushMotionEvents(camera) {
+    return defer(() => {
+        const seenAt = new Map();
+        return merge(camera.onMotionDetected.pipe(filter((motion) => !motion)), camera.onNewNotification.pipe(filter((notification) => {
+            if (notification.android_config?.category !== PushNotificationAction.Motion) {
+                return false;
+            }
+            const now = Date.now(), id = notification.data?.event?.ding?.id;
+            for (const [seenId, at] of seenAt) {
+                if (now - at > REPEATED_ALERT_WINDOW_MS)
+                    seenAt.delete(seenId);
+            }
+            if (id === undefined)
+                return true;
+            if (seenAt.has(String(id)))
+                return false;
+            seenAt.set(String(id), now);
+            return true;
+        }), map(() => true)));
+    });
+}
 export function addMotionWatchdog(motionEvents, watchdogMs = MOTION_WATCHDOG_MS) {
     return motionEvents.pipe(switchMap((motion) => {
         if (!motion) {
@@ -183,7 +217,7 @@ export class Camera extends BaseDataAccessory {
         }
     }
     getMotionDetectedObservable() {
-        const pollSeconds = Math.max(this.config.cameraStatusPollingSeconds ?? 20, 10), startedAt = Date.now() - 5000, seenEventIds = new Set(), pushMotionEvents = this.device.onMotionDetected, enableMotionHistoryFallback = this.config.enableCameraMotionHistory !== false;
+        const pollSeconds = Math.max(this.config.cameraStatusPollingSeconds ?? 20, 10), startedAt = Date.now() - 5000, seenEventIds = new Set(), pushMotionEvents = getPushMotionEvents(this.device), enableMotionHistoryFallback = this.config.enableCameraMotionHistory !== false;
         let historyFailureCount = 0;
         let nextHistoryPollAt = 0;
         const baseHistoryRetryMs = Math.max(pollSeconds * 1000, 30_000), polledNewMotionEvents = timer(pollSeconds * 1000, pollSeconds * 1000).pipe(exhaustMap(() => {
@@ -218,10 +252,10 @@ export class Camera extends BaseDataAccessory {
                 logError(`${this.device.name} failed to poll Ring event history for motion fallback; retrying in ${Math.ceil(retryDelayMs / 1000)} seconds`);
                 return EMPTY;
             }));
-        }), 
-        // The false timer below has a second subscriber. Sharing keeps one
-        // history request per poll instead of duplicating Ring API traffic.
-        share()), polledMotionEvents = merge(polledNewMotionEvents, polledNewMotionEvents.pipe(switchMap(() => timer(65000).pipe(map(() => false)))));
+        })), 
+        // No separate "motion off" for these: the watchdog below turns motion off 30 s after the
+        // last event, and a 65 s one from here could cut a later push-started visit short.
+        polledMotionEvents = polledNewMotionEvents;
         if (enableMotionHistoryFallback) {
             this.device.onNewNotification.subscribe((notification) => {
                 const dingId = notification.data?.event?.ding?.id;

package/lib/config.js

@@ -1,14 +1,124 @@
-import { logError } from 'ring-client-api/util';
-import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { logError, logInfo } from 'ring-client-api/util';
+import { closeSync, fchmodSync, fchownSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'fs';
 import { createHash, randomBytes } from 'crypto';
-import { join } from 'path';
+import { basename, dirname, join } from 'path';
 const systemIdFileName = '.ring.json';
 export const controlCenterDisplayName = 'homebridge-ring-secure-video';
+// Errors where a temporary file next to the target can't be created or can't replace it, but
+// writing the file in place may still work: a folder you can't write to, a file bind-mounted on
+// its own (Docker), a file another program has open on Windows, another file system, an owner or
+// group a container can't map (EINVAL from fchown).
+const writeInPlaceOn = new Set(['EACCES', 'EPERM', 'EBUSY', 'EXDEV', 'EROFS', 'EINVAL']);
+const reportedInPlace = new Set();
+function writeInPlace(filePath, contents, reason) {
+    // Once per file: a bind-mounted config.json would otherwise log this with every token renewal.
+    if (!reportedInPlace.has(filePath)) {
+        reportedInPlace.add(filePath);
+        logInfo(`Writing ${filePath} in place (${reason})`);
+    }
+    writeFileSync(filePath, contents);
+}
+function removeStaleTemporaryFiles(folder, name) {
+    try {
+        for (const entry of readdirSync(folder)) {
+            if (!entry.startsWith(`.${name}.`) || !entry.endsWith('.tmp'))
+                continue;
+            const file = join(folder, entry);
+            // Older than a minute: left behind by a crash, not another writer's work in progress.
+            if (Date.now() - statSync(file).mtimeMs > 60_000)
+                rmSync(file, { force: true });
+        }
+    }
+    catch {
+        // best effort
+    }
+}
+/**
+ * Replaces a file's contents so that it is never left half-written: the new contents go to a
+ * temporary file next to it, are flushed to disk, and then take the file's place in one step. A
+ * power cut or a full disk on a Raspberry Pi would otherwise leave config.json cut short, and
+ * Homebridge would not start. A symlinked file is written where its link points, and the file
+ * keeps its permissions. Where that can't work (the file belongs to someone else and this isn't
+ * root, a folder you can't write to, a bind-mounted file, ...) it is written in place as before.
+ */
+export function writeFileAtomic(filePath, contents) {
+    let target = filePath, previous;
+    try {
+        target = realpathSync(filePath);
+        previous = statSync(target);
+    }
+    catch {
+        let dangling = false;
+        try {
+            dangling = lstatSync(filePath).isSymbolicLink();
+        }
+        catch {
+            // a new file
+        }
+        if (dangling) {
+            return writeInPlace(filePath, contents, 'its link points nowhere yet');
+        }
+    }
+    const uid = process.getuid?.();
+    if (previous && uid !== undefined && uid !== 0 && previous.uid !== uid) {
+        // A new file would be owned by this user instead of the file's owner.
+        return writeInPlace(target, contents, 'it belongs to another user');
+    }
+    const folder = dirname(target), name = basename(target), temporary = join(folder, `.${name}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            // Unlike writeSync, this writes everything or throws (e.g. ENOSPC on a full disk).
+            writeFileSync(fd, contents);
+            // Owner and group first: changing them clears setuid/setgid bits set by a chmod.
+            if (previous && uid === 0) {
+                fchownSync(fd, previous.uid, previous.gid);
+            }
+            else if (previous && previous.gid !== process.getgid?.()) {
+                // A shared group (e.g. for the Homebridge UI); EPERM writes in place, keeping it.
+                fchownSync(fd, -1, previous.gid);
+            }
+            fchmodSync(fd, previous ? previous.mode & 0o7777 : 0o644 & ~process.umask());
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, target);
+    }
+    catch (error) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            // the original error matters
+        }
+        const code = error.code;
+        if (code && writeInPlaceOn.has(code)) {
+            return writeInPlace(target, contents, code);
+        }
+        throw error;
+    }
+    // Make the rename itself survive a power cut (best effort; not possible on every system).
+    try {
+        const dir = openSync(folder, 'r');
+        try {
+            fsyncSync(dir);
+        }
+        finally {
+            closeSync(dir);
+        }
+    }
+    catch {
+        // ignore
+    }
+    removeStaleTemporaryFiles(folder, name);
+}
 export function updateHomebridgeConfig(homebridge, update) {
     try {
         const configPath = homebridge.user.configPath(), config = readFileSync(configPath).toString(), updatedConfig = update(config);
         if (config !== updatedConfig) {
-            writeFileSync(configPath, updatedConfig);
+            writeFileAtomic(configPath, updatedConfig);
             return true;
         }
     }
@@ -35,7 +145,7 @@ export function getSystemId(homebridgeStoragePath) {
     const systemId = createSystemId(), ringContext = { systemId };
     try {
         mkdirSync(homebridgeStoragePath, { recursive: true });
-        writeFileSync(filePath, JSON.stringify(ringContext));
+        writeFileAtomic(filePath, JSON.stringify(ringContext));
     }
     catch (error) {
         logError('Failed to persist Ring system id');
@@ -47,7 +157,7 @@ export function rotateSystemId(homebridgeStoragePath) {
     const filePath = join(homebridgeStoragePath, systemIdFileName), systemId = createSystemId(), ringContext = { systemId };
     try {
         mkdirSync(homebridgeStoragePath, { recursive: true });
-        writeFileSync(filePath, JSON.stringify(ringContext));
+        writeFileAtomic(filePath, JSON.stringify(ringContext));
     }
     catch (error) {
         logError('Failed to rotate Ring system id');

package/lib/media-config.js

@@ -25,8 +25,18 @@ const recordingKeys = new Set([
     'maxQueuedBytes',
     'maxConcurrentRecordings',
 ]);
+/** A media setting that can't be used; path is where it is, e.g. "media.recording.crf". */
+export class MediaConfigError extends Error {
+    path;
+    expectation;
+    constructor(path, expectation) {
+        super(`Invalid media configuration at ${path}: expected ${expectation}`);
+        this.path = path;
+        this.expectation = expectation;
+    }
+}
 function invalid(path, expectation) {
-    throw new Error(`Invalid media configuration at ${path}: expected ${expectation}`);
+    throw new MediaConfigError(path, expectation);
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -126,8 +136,8 @@ export function normalizeMediaConfig(config) {
     const input = media.recording;
     const lowPower = profile === 'lowPower';
     const bitrateKbps = preferInteger(input.bitrateKbps, config.hksvVideoBitrateKbps, 'media.recording.bitrateKbps', lowPower ? 1000 : profile === 'quality' ? 5000 : 3000, 256, 12000);
-    const maxBitrateKbps = preferInteger(input.maxBitrateKbps, config.hksvVideoMaxBitrateKbps, 'media.recording.maxBitrateKbps', bitrateKbps * 2, bitrateKbps, 20000);
-    const bufferSizeKbps = preferInteger(input.bufferSizeKbps, config.hksvVideoBufferSizeKbps, 'media.recording.bufferSizeKbps', maxBitrateKbps * 2, maxBitrateKbps, 40000);
+    const maxBitrateKbps = preferInteger(input.maxBitrateKbps, config.hksvVideoMaxBitrateKbps, 'media.recording.maxBitrateKbps', Math.min(bitrateKbps * 2, 20000), bitrateKbps, 20000);
+    const bufferSizeKbps = preferInteger(input.bufferSizeKbps, config.hksvVideoBufferSizeKbps, 'media.recording.bufferSizeKbps', Math.min(maxBitrateKbps * 2, 40000), maxBitrateKbps, 40000);
     return {
         profile,
         recording: {
@@ -147,6 +157,49 @@ export function normalizeMediaConfig(config) {
         },
     };
 }
+// Error paths are "media", "media.<key>", "media.recording" or "media.recording.<key>", where
+// <key> is the user's own key and may itself contain dots.
+function removeSetting(config, path) {
+    const media = config.media;
+    const recordingKey = path.slice('media.recording.'.length);
+    if (path.startsWith('media.recording.') &&
+        isRecord(media) &&
+        isRecord(media.recording) &&
+        Object.hasOwn(media.recording, recordingKey)) {
+        delete media.recording[recordingKey];
+    }
+    else if (path.startsWith('media.') && isRecord(media)) {
+        delete media[path.slice('media.'.length)];
+    }
+    else {
+        delete config.media;
+    }
+}
+/**
+ * Like normalizeMediaConfig, but never throws: each media setting that can't be used is taken out
+ * of config (in memory only, so every later normalizeMediaConfig call agrees) and reported, and the
+ * older flat setting or the default is used instead. A bad value, for example a maximum bitrate below the bitrate, would
+ * otherwise stop the plugin from starting and take everything on its bridge down with it.
+ */
+export function sanitizeMediaConfig(config) {
+    const ignored = [];
+    // Each round removes one setting. After 64 (only possible with many unknown keys), all media
+    // settings are dropped below.
+    for (let round = 0; round < 64; round++) {
+        try {
+            return { media: normalizeMediaConfig(config), ignored };
+        }
+        catch (e) {
+            if (!(e instanceof MediaConfigError))
+                throw e;
+            ignored.push(e);
+            removeSetting(config, e.path);
+        }
+    }
+    delete config.media;
+    ignored.push(new MediaConfigError('media', 'fewer than 64 unusable settings, so all of them are ignored'));
+    return { media: normalizeMediaConfig(config), ignored };
+}
 /** Maps v15 profiles to the legacy names used by existing camera code. */
 export function getLegacyHksvPerformanceMode(config) {
     const profile = normalizeMediaConfig(config).profile;

package/lib/ring-platform.js

@@ -30,7 +30,7 @@ import { Thermostat } from "./thermostat.js";
 import { UnknownZWaveSwitchSwitch } from "./unknown-zwave-switch.js";
 import { Intercom } from "./intercom.js";
 import { Valve } from "./valve.js";
-import { normalizeMediaConfig } from "./media-config.js";
+import { sanitizeMediaConfig } from "./media-config.js";
 import { configureHksvResourceGovernor } from "./hksv-work-queue.js";
 import { getMotionNotificationSensorUuid, setUpMotionNotificationSensor, } from "./motion-notification-sensor.js";
 const ignoreHiddenDeviceTypes = [
@@ -151,6 +151,37 @@ function updateRefreshTokenInConfig(configContents, oldRefreshToken, newRefreshT
         return configContents.replace(oldRefreshToken, newRefreshToken);
     }
 }
+/**
+ * Saves each new Ring refresh token into config.json, replacing the token that is there now.
+ *
+ * The token in config.json is tracked here rather than taken from ring-client-api's
+ * "oldRefreshToken": after a forced refresh, ring-client-api starts from a modified token that
+ * was never written to config.json, and following its old token would save only the first new
+ * token and none after it (so the next start would register with Ring again).
+ */
+export function createRefreshTokenSaver(api, tokenInConfig, clearRefreshFlags) {
+    let current = tokenInConfig, 
+    // Only with the first save: turning a force setting back on later must survive renewals.
+    clearFlags = clearRefreshFlags, warned = false;
+    return ({ oldRefreshToken, newRefreshToken, }) => {
+        const replace = current ?? oldRefreshToken;
+        if (!replace || newRefreshToken === replace) {
+            return;
+        }
+        const saved = updateHomebridgeConfig(api, (configContents) => {
+            return updateRefreshTokenInConfig(configContents, replace, newRefreshToken, clearFlags);
+        });
+        if (saved) {
+            current = newRefreshToken;
+            clearFlags = false;
+        }
+        else if (!warned) {
+            // Once per run: after a new sign-in while running, every renewal would end up here.
+            warned = true;
+            logInfo('Could not save a new Ring token to config.json (it may have been changed or signed in again while running). If you did not sign in again, the next start may register with Ring again.');
+        }
+    };
+}
 export class RingPlatform {
     homebridgeAccessories = {};
     log;
@@ -184,7 +215,10 @@ export class RingPlatform {
         config.locationModePollingSeconds = config.locationModePollingSeconds ?? 20;
         // Media resources are platform-wide. Configure the singleton once before
         // cameras are constructed; individual cameras must never overwrite it.
-        const media = normalizeMediaConfig(config);
+        const { media, ignored } = sanitizeMediaConfig(config);
+        for (const setting of ignored) {
+            this.log.warn(`Ignoring the media setting ${setting.path} (expected ${setting.expectation}); the older setting or the default is used instead. Correct it in the plugin settings.`);
+        }
         configureHksvResourceGovernor({
             recordingConcurrency: media.recording.maxConcurrentRecordings,
             queueTimeoutMs: 30_000,
@@ -233,18 +267,8 @@ export class RingPlatform {
                 ? { refreshToken: refreshTokenWithoutPushCredentials }
                 : {}),
             systemId,
-        }), refreshTokenToReplace = refreshTokenWithoutPushCredentials && config.refreshToken
-            ? config.refreshToken
-            : undefined;
-        ringApi.onRefreshTokenUpdated.subscribe(({ oldRefreshToken, newRefreshToken }) => {
-            const configRefreshToken = refreshTokenToReplace ?? oldRefreshToken;
-            if (!configRefreshToken) {
-                return;
-            }
-            updateHomebridgeConfig(this.api, (configContents) => {
-                return updateRefreshTokenInConfig(configContents, configRefreshToken, newRefreshToken, Boolean(refreshTokenWithoutPushCredentials));
-            });
         });
+        ringApi.onRefreshTokenUpdated.subscribe(createRefreshTokenSaver(this.api, config.refreshToken, Boolean(refreshTokenWithoutPushCredentials)));
         const locations = await ringApi.getLocations(), cachedAccessoryIds = Object.keys(this.homebridgeAccessories), platformAccessories = [], externalAccessories = [], activeAccessoryIds = [];
         logInfo('Found the following locations:');
         locations.forEach((location) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-ring-secure-video",
   "displayName": "Ring Secure Video",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "Homebridge plugin for Ring devices with HomeKit Secure Video recording, based on homebridge-ring and homebridge-ring-hksv",
   "type": "module",
   "main": "./lib/index.js",
@@ -9,7 +9,7 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('lib', { recursive: true, force: true })\" && tsc && node -e \"require('fs').cpSync('./homebridge-ui/public', './lib/homebridge-ui/public', { recursive: true })\"",
     "lint": "eslint .",
-    "test": "npm run build && node --test test/v15-media.test.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
     "prepack": "npm run build",
     "dev": "concurrently -c yellow,blue --kill-others \"npm:dev:build\" \"npm:dev:run\" ",
     "dev:build": "tsc --watch --preserveWatchOutput",