@homebridge-plugins/homebridge-eufy-security 5.0.0-beta.6 → 5.0.0-beta.8

package/dist/diagnostics.js

@@ -35,6 +35,17 @@ export function unconfirmedWriteCondition(property) {
 }
 /** Why a live session gave its source back: a stop from outside it, or the session ending itself. */
 const LIVE_SESSION_RELEASES = ['requested', 'failed'];
+/** The claims that contend for a station's one live channel, and the decisions taken over it. */
+const STATION_CLAIMS = ['live', 'recording', 'snapshot'];
+const STATION_CLAIM_ACTIONS = ['held', 'yielded', 'refused', 'released'];
+/**
+ * The widest camera index a station may name as the one it is serving.
+ *
+ * A base fans a bounded number of cameras over one session, and an index beyond that is a value this plugin
+ * did not expect rather than a channel. The index carries no identity: which camera holds it is stated by the
+ * records about that camera.
+ */
+const MAX_STATION_CHANNEL = 63;
 /** The bounded reasons a stream request is refused before it reaches the source. */
 const REFUSAL_REASONS = new Set(['disabled', 'at-capacity', 'cancelled', 'prepare-failed']);
 /**
@@ -56,7 +67,15 @@ const HOMEKIT_LIVE_REQUEST_EVENTS = new Set([
  * failure. A station refusing a second camera is one of these identities, because a base serving another of its
  * cameras is working correctly and must not read as a fault.
  */
-const SDK_ERROR_TYPES = ['Error', 'RangeError', 'SessionExpiredError', 'StationBusyError', 'TypeError'];
+const SDK_ERROR_TYPES = [
+    'Error',
+    'RangeError',
+    'SessionExpiredError',
+    'StationBusyError',
+    'StationKeyUnavailableError',
+    'StationUnreachableError',
+    'TypeError',
+];
 /**
  * The retained fields that stand for a device rather than describing one, which is the privacy class a manifest
  * declares for them. Each holds a per-case alias: stable within one archive, and resolvable to a device only by
@@ -87,7 +106,12 @@ const DIAGNOSTICS_DIRECTORY = 'diagnostics';
 const GUIDED_SESSION_FILE = 'session.json';
 const REPRODUCTION_MARKERS_FILE = 'reproduction-markers.jsonl';
 const UI_EVENTS_FILE = 'ui-events.jsonl';
-const FFMPEG_ENVIRONMENT_FILE = 'ffmpeg.json';
+const HOST_ENVIRONMENT_FILE = 'host.json';
+const FLEET_FILE = 'fleet.json';
+/** The longest device model or adapter key retained, which bounds values this plugin does not choose alone. */
+const MAX_DEVICE_MODEL_LENGTH = 64;
+/** How many HomeKit services one fleet entry names, which is above what any single device is represented by. */
+const MAX_FLEET_SERVICES = 12;
 /** How much of an FFmpeg path or version banner is kept, which is more than either needs. */
 const MAX_FFMPEG_IDENTITY_LENGTH = 256;
 const DEBUG_AUTHORIZATION_MS = 72 * 60 * 60 * 1_000;
@@ -327,54 +351,135 @@ function boundedText(value, maximumLength) {
         .trim();
     return printable === '' ? undefined : printable;
 }
-function ffmpegEnvironmentPath(storageRoot) {
-    return join(storageRoot, DIAGNOSTICS_DIRECTORY, FFMPEG_ENVIRONMENT_FILE);
+function fleetPath(storageRoot) {
+    return join(storageRoot, DIAGNOSTICS_DIRECTORY, FLEET_FILE);
 }
 /**
- * Records which FFmpeg this run resolved, so a support archive states the build a failure came from.
+ * Records what the account's devices are and what each becomes, replacing the record whole.
  *
- * It is persisted rather than held in memory because the process that resolves it is not the one that
- * assembles an archive, and it is rewritten on every start so a path or binary that changed between runs
- * cannot be reported as the one in use. A write that fails is dropped: the archive then declares the
- * environment without an FFmpeg identity, which is honest, whereas failing startup over a diagnostic file
- * would cost the user their cameras.
+ * Written by the process that holds both the inventory and the accessory aliases, because an archive is
+ * assembled by another one. Rewritten on every complete inventory, so a device withdrawn or newly recognised
+ * cannot be reported as still present. A write that fails is dropped: an archive then declares no fleet, which
+ * is honest, whereas failing over a diagnostic file would cost the user their cameras.
  */
-export function recordFfmpegEnvironment(storageRoot, ffmpeg) {
+export function recordFleet(storageRoot, fleet) {
     try {
-        const path = ffmpegEnvironmentPath(storageRoot);
+        const path = fleetPath(storageRoot);
         mkdirSync(dirname(path), { mode: 0o700, recursive: true });
-        writeFileSync(path, `${JSON.stringify({ version: 1, ffmpeg })}\n`, { mode: 0o600 });
+        writeFileSync(path, `${JSON.stringify({ version: 1, devices: fleet })}\n`, { mode: 0o600 });
     }
     catch { }
 }
+/** Reads the recorded fleet, keeping each entry whose own fields narrow and dropping each that does not. */
+function readFleet(storageRoot) {
+    try {
+        const candidate = JSON.parse(readFileSync(fleetPath(storageRoot), 'utf8'));
+        if (candidate.version !== 1 || !Array.isArray(candidate.devices)) {
+            return undefined;
+        }
+        const devices = candidate.devices.flatMap((entry) => {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+                return [];
+            const row = entry;
+            const accessory = opaqueAccessoryAlias(row.accessory);
+            if (accessory === undefined || typeof row.represented !== 'boolean' || typeof row.attached !== 'boolean') {
+                return [];
+            }
+            const model = typeof row.model === 'string' ? boundedText(row.model, MAX_DEVICE_MODEL_LENGTH) : undefined;
+            const services = (Array.isArray(row.services) ? row.services : [])
+                .filter((service) => typeof service === 'string')
+                .slice(0, MAX_FLEET_SERVICES)
+                .flatMap((service) => {
+                const bounded = boundedText(service, MAX_DEVICE_MODEL_LENGTH);
+                return bounded === undefined ? [] : [bounded];
+            });
+            return [
+                {
+                    accessory,
+                    ...(model === undefined ? {} : { model }),
+                    represented: row.represented,
+                    attached: row.attached,
+                    services,
+                },
+            ];
+        });
+        return devices.length === 0 ? undefined : devices.slice(0, MAX_ACCESSORY_ALIASES);
+    }
+    catch {
+        return undefined;
+    }
+}
+function hostEnvironmentPath(storageRoot) {
+    return join(storageRoot, DIAGNOSTICS_DIRECTORY, HOST_ENVIRONMENT_FILE);
+}
+/** The longest host version string retained, which bounds a value this plugin does not choose. */
+const MAX_HOST_VERSION_LENGTH = 64;
 /**
- * Reads the recorded adaptation binary, refusing a record whose own fields do not narrow.
+ * Records what this run is hosted by, so a support archive states the host a failure came from.
  *
- * The path and the banner are kept as written rather than pattern-replaced, because naming the binary is the
- * entire purpose of the record and a redacted one answers nothing. Neither is device or account material: the
- * path is this plugin's own setting or the binary it ships, and the banner is that build's public identity.
+ * It is persisted rather than held in memory because the process that knows these facts is not the one that
+ * assembles an archive, and it is rewritten on every start so a host or binary that changed between runs
+ * cannot be reported as the one in use. Each call replaces the record whole, so a caller states everything it
+ * knows rather than accumulating into a file two writers would race for.
+ *
+ * A write that fails is dropped: the archive then declares the environment without these facts, which is
+ * honest, whereas failing startup over a diagnostic file would cost the user their cameras.
  */
-function readFfmpegEnvironment(storageRoot) {
+export function recordHostEnvironment(storageRoot, host) {
     try {
-        const candidate = JSON.parse(readFileSync(ffmpegEnvironmentPath(storageRoot), 'utf8'));
-        const ffmpeg = candidate.ffmpeg;
-        if (candidate.version !== 1 || !ffmpeg || typeof ffmpeg !== 'object' || Array.isArray(ffmpeg)) {
+        const path = hostEnvironmentPath(storageRoot);
+        mkdirSync(dirname(path), { mode: 0o700, recursive: true });
+        writeFileSync(path, `${JSON.stringify({ version: 2, ...host })}\n`, { mode: 0o600 });
+    }
+    catch { }
+}
+/**
+ * Reads what this run is hosted by, keeping each fact that narrows and dropping each that does not.
+ *
+ * The facts are independent, so a malformed binary identity does not withhold a host version, and a record
+ * stating neither is no record at all.
+ */
+function readHostEnvironment(storageRoot) {
+    try {
+        const candidate = JSON.parse(readFileSync(hostEnvironmentPath(storageRoot), 'utf8'));
+        if (candidate.version !== 2) {
             return undefined;
         }
-        const recorded = ffmpeg;
-        if (typeof recorded.path !== 'string' || (recorded.source !== 'bundled' && recorded.source !== 'configured')) {
+        const homebridge = typeof candidate.homebridge === 'string' ? boundedText(candidate.homebridge, MAX_HOST_VERSION_LENGTH) : undefined;
+        const ffmpeg = readFfmpegIdentity(candidate.ffmpeg);
+        if (homebridge === undefined && ffmpeg === undefined) {
             return undefined;
         }
-        const path = boundedText(recorded.path, MAX_FFMPEG_IDENTITY_LENGTH);
-        const version = typeof recorded.version === 'string' ? boundedText(recorded.version, MAX_FFMPEG_IDENTITY_LENGTH) : undefined;
-        return path === undefined
-            ? undefined
-            : { path, source: recorded.source, ...(version === undefined ? {} : { version }) };
+        return {
+            ...(homebridge === undefined ? {} : { homebridge }),
+            ...(ffmpeg === undefined ? {} : { ffmpeg }),
+        };
     }
     catch {
         return undefined;
     }
 }
+/**
+ * The recorded adaptation binary, or nothing where the record's own fields do not narrow.
+ *
+ * The path and the banner are kept as written rather than pattern-replaced, because naming the binary is the
+ * entire purpose of the record and a redacted one answers nothing. Neither is device or account material: the
+ * path is this plugin's own setting or the binary it ships, and the banner is that build's public identity.
+ */
+function readFfmpegIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const recorded = value;
+    if (recorded.source !== 'bundled' && recorded.source !== 'configured') {
+        return undefined;
+    }
+    const path = typeof recorded.path === 'string' ? boundedText(recorded.path, MAX_FFMPEG_IDENTITY_LENGTH) : undefined;
+    const version = typeof recorded.version === 'string' ? boundedText(recorded.version, MAX_FFMPEG_IDENTITY_LENGTH) : undefined;
+    return path === undefined
+        ? undefined
+        : { path, source: recorded.source, ...(version === undefined ? {} : { version }) };
+}
 /**
  * The one log evidence class a retained record belongs to.
  *
@@ -651,7 +756,8 @@ export class GuidedDiagnostics {
         }
     }
     async collectSupportEvidence(session) {
-        const ffmpeg = readFfmpegEnvironment(this.storageRoot);
+        const host = readHostEnvironment(this.storageRoot);
+        const fleet = readFleet(this.storageRoot);
         const evidence = [
             ...(session.affectedDevices === undefined
                 ? []
@@ -672,22 +778,45 @@ export class GuidedDiagnostics {
                         ],
                     },
                 ]),
+            ...(fleet === undefined
+                ? []
+                : [
+                    {
+                        evidence: 'fleet',
+                        privacyClass: 'operational',
+                        contentType: 'application/json',
+                        content: `${JSON.stringify({ version: 1, devices: fleet })}\n`,
+                        /**
+                         * What each device is and becomes, against the alias every other record about it carries. A model
+                         * and an admission outcome are product facts rather than device identity; the alias is what makes
+                         * an entry resolvable to a device, and only by the owner whose console paired it with a name.
+                         */
+                        fields: [
+                            { field: 'version', privacyClass: 'operational' },
+                            { field: 'devices', privacyClass: 'pseudonymous' },
+                        ],
+                    },
+                ]),
             {
                 evidence: 'environment',
                 privacyClass: 'operational',
                 contentType: 'application/json',
-                content: `${JSON.stringify({ version: 2, plugin: PLUGIN_VERSION, sdk: SDK_VERSION, node: process.version, platform: process.platform, arch: process.arch, ...(ffmpeg ? { ffmpeg } : {}) })}\n`,
+                content: `${JSON.stringify({ version: 3, plugin: PLUGIN_VERSION, sdk: SDK_VERSION, node: process.version, ...(host?.homebridge ? { homebridge: host.homebridge } : {}), platform: process.platform, arch: process.arch, ...(host?.ffmpeg ? { ffmpeg: host.ffmpeg } : {}) })}\n`,
                 /**
                  * The record is operational and one field is classified above it: a resolved FFmpeg path is an
                  * environment fact, but it can carry the home directory of the account Homebridge runs as, so it is
                  * declared as diagnostic rather than presented alongside the host's own architecture.
+                 *
+                 * The Homebridge version is operational and load-bearing: this plugin requires Homebridge 2, and a
+                 * host that predates it loads the plugin and then fails in ways a media fault cannot be told from.
                  */
                 fields: [
                     ...['version', 'plugin', 'sdk', 'node', 'platform', 'arch'].map((field) => ({
                         field,
                         privacyClass: 'operational',
                     })),
-                    ...(ffmpeg ? [{ field: 'ffmpeg', privacyClass: 'diagnostic' }] : []),
+                    ...(host?.homebridge ? [{ field: 'homebridge', privacyClass: 'operational' }] : []),
+                    ...(host?.ffmpeg ? [{ field: 'ffmpeg', privacyClass: 'diagnostic' }] : []),
                 ],
             },
         ];
@@ -1223,6 +1352,14 @@ function allowlistedLabel(value, allowed) {
  * like any other field that fails its shape.
  */
 const MAX_STARTUP_WINDOW_MS = 60_000;
+/** Why a level-2 wait ended without a key, which is the whole of what such an ending states. */
+const LEVEL2_UNAVAILABLE_REASONS = [
+    'no-cipher-key',
+    'derivation-failed',
+    'not-negotiating',
+    'session-closed',
+    'grace-elapsed',
+];
 /** The three phases whose only field is the action they report, which the union fixes at `start`. */
 const retainedStart = (candidate) => candidate.action === 'start' ? { action: 'start' } : undefined;
 /** A phase whose only field is one bounded integer, retained under the name the SDK declares for it. */
@@ -1268,7 +1405,49 @@ const LIVE_TRACE_PHASES = {
     'sequence-restart': retainedInteger('dataType', 3),
     'level2-wait': retainedInteger('waitMs', MAX_STARTUP_WINDOW_MS),
     'level2-ready': retainedInteger('cipherId', 65535),
-    'level2-absent': retainedInteger('waitedMs', MAX_STARTUP_WINDOW_MS),
+    'session-connect-wait': retainedInteger('waitMs', MAX_STARTUP_WINDOW_MS),
+    'session-connected': retainedInteger('waitedMs', MAX_STARTUP_WINDOW_MS),
+    'session-unreachable': retainedInteger('waitedMs', MAX_STARTUP_WINDOW_MS),
+    /**
+     * Why a level-2 wait ended without a key, and what it had to name.
+     *
+     * The reason is the record: a wait that ran out states how long it waited, and one answered without waiting
+     * states nothing more, because the negotiation is one-shot per connection. Only a reason reached under a
+     * negotiation has a cipher to name, so both durations are optional and each is retained where it is stated.
+     */
+    'level2-unavailable': (c) => {
+        const reason = allowlistedLabel(c.reason, LEVEL2_UNAVAILABLE_REASONS);
+        if (!reason) {
+            return undefined;
+        }
+        const cipherId = boundedInteger(c.cipherId, 65535);
+        const waitedMs = boundedInteger(c.waitedMs, MAX_STARTUP_WINDOW_MS);
+        return {
+            reason,
+            ...(cipherId === undefined ? {} : { cipherId }),
+            ...(waitedMs === undefined ? {} : { waitedMs }),
+        };
+    },
+    /** The cipher a station asked for, beside the one whose material answered it. */
+    'cipher-fallback': (c) => {
+        const cipherId = boundedInteger(c.cipherId, 65535);
+        const answeredCipherId = boundedInteger(c.answeredCipherId, 65535);
+        return cipherId === undefined || answeredCipherId === undefined ? undefined : { cipherId, answeredCipherId };
+    },
+    'level2-negotiating': retainedInteger('cipherId', 65535),
+    /**
+     * What a call resolved a station as, which decides what its failure means.
+     *
+     * An attached camera's media start has no unencrypted form, so the topology is what separates a key that
+     * never arrived from a start that had no form to be sent in. The channel is an index on a base and the
+     * administrator is a relation to the signed-in account: neither is an identity of its own.
+     */
+    'station-resolved': (c) => {
+        const topology = allowlistedLabel(c.topology, ['attached', 'own']);
+        const stationAdmin = allowlistedLabel(c.stationAdmin, ['self', 'other', 'unstated']);
+        const channel = boundedInteger(c.channel, MAX_STATION_CHANNEL);
+        return topology && stationAdmin && channel !== undefined ? { topology, channel, stationAdmin } : undefined;
+    },
     /**
      * How long a connection's path has answered nothing, which is the station stating the path is gone.
      *
@@ -1276,6 +1455,19 @@ const LIVE_TRACE_PHASES = {
      * silence longer than that belongs to a session nothing is waiting on.
      */
     'path-stale': retainedInteger('silentMs', MAX_STARTUP_WINDOW_MS),
+    /**
+     * How long a camera's own channel delivered nothing, and whether the station was asked to serve it again.
+     *
+     * Both halves are the record: a station re-tasked to a sibling is repaired by the re-assert, and a pull
+     * nothing is attached to declines it so the station is left with the camera someone is watching. A picture
+     * that stopped advancing while no such record exists stopped for a reason the station's attention does not
+     * reach.
+     */
+    'channel-silent': (c) => {
+        const silentMs = boundedInteger(c.silentMs, MAX_STARTUP_WINDOW_MS);
+        const outcome = allowlistedLabel(c.outcome, ['declined', 'reasserted']);
+        return silentMs !== undefined && outcome ? { silentMs, outcome } : undefined;
+    },
     'media-command-unsent': (c) => {
         const reason = allowlistedLabel(c.reason, ['level2-key', 'address']);
         return reason ? { reason } : undefined;
@@ -1486,6 +1678,7 @@ const REASONS = new Set([
     'source-input-unstable',
     'source-stopped',
     'source-unavailable',
+    'station-busy',
     'stored-download-failed',
     'stored-failed',
     'stored-invalid-image',
@@ -1566,6 +1759,13 @@ const ADAPTATION_EVENTS = new Set([
     'exited-while-streaming',
     'output',
 ]);
+/**
+ * Why a process was started, on the record that reports it starting.
+ *
+ * A replacement carries the identity of the stream the previous process was already sending on, so what it
+ * started mid-flight is judged against what that one left. A first adaptation has nothing behind it.
+ */
+const ADAPTATION_CAUSES = ['first', 'controller-selection', 'source-configuration'];
 /**
  * Which of those events is a failure, and so the ones a record is levelled `warn` for.
  *
@@ -1832,6 +2032,10 @@ function sanitizeStructuredEvent(message) {
         return { scope: 'media-notice', level: notice.level, code: value.code, messageKey: notice.messageKey };
     }
     if (value.scope === 'homekit') {
+        if (value.event === 'station-claim') {
+            const claim = sanitizeStationClaim(value);
+            return claim ? { scope: 'homekit', level: 'debug', ...claim } : undefined;
+        }
         if (value.adapter === 'camera.streaming' && value.event === 'live-video-selected') {
             const selection = sanitizeLiveVideoSelection(value);
             return selection ? { scope: 'homekit', level: 'debug', ...selection } : undefined;
@@ -1980,6 +2184,36 @@ export function reportInvalidSnapshotCache(target) {
  * `aliasFor` resolves the trace's device identity to the support-case alias the conditions about that accessory
  * already carry. The identity itself never reaches the record: an unresolved one is recorded as no accessory.
  */
+/**
+ * Narrows one offered station arbitration decision, or nothing where its own labels do not narrow.
+ *
+ * Read by both halves of the path — {@link reportStationClaim} builds the record and the file sink rebuilds
+ * it — because a record only one of them recognises is written to a console nobody is reading and dropped
+ * before it reaches a support archive.
+ */
+function sanitizeStationClaim(value) {
+    const action = allowlistedLabel(value.action, STATION_CLAIM_ACTIONS);
+    const claim = allowlistedLabel(value.claim, STATION_CLAIMS);
+    if (!action || !claim) {
+        return undefined;
+    }
+    const against = allowlistedLabel(value.displaced ?? value.to ?? value.by ?? value.against, STATION_CLAIMS);
+    return { event: 'station-claim', action, claim, ...(against === undefined ? {} : { against }) };
+}
+/**
+ * Records one arbitration decision over a station's single live channel as `homekit-log` evidence.
+ *
+ * A station serves one camera at a time and the SDK refuses a second outright, so a refused live request is
+ * attributable either to this plugin's own policy or to the station, and the two are indistinguishable
+ * afterwards without this. The record carries the claims and the decision alone: a station identity is a
+ * serial, and the camera holding it is already named by the records about that camera.
+ */
+export function reportStationClaim(target, decision) {
+    const claim = sanitizeStationClaim(decision);
+    if (target.debug && claim) {
+        target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...claim }));
+    }
+}
 export function reportHomeKitEvent(target, trace, aliasFor) {
     const alias = typeof trace.serial === 'string' ? aliasFor?.(trace.serial) : undefined;
     const offered = { ...trace, accessory: alias };
@@ -2121,11 +2355,13 @@ function sanitizeAdaptationNotice(value, level) {
         .filter((line) => line !== undefined)
         .slice(-MAX_ADAPTATION_STDERR_LINES);
     const sourceFragments = nonNegativeInteger(value.sourceFragments);
+    const cause = allowlistedLabel(value.cause, ADAPTATION_CAUSES);
     return {
         scope: 'ffmpeg',
         level,
         role: value.role,
         event: value.event,
+        ...(cause === undefined ? {} : { cause }),
         ...(code === undefined ? {} : { code }),
         ...(signal === undefined ? {} : { signal }),
         ...(sourceFragments === undefined ? {} : { sourceFragments }),
@@ -2140,7 +2376,19 @@ function sanitizeLiveSessionTrace(value) {
     const accessory = alias === undefined ? {} : { accessory: alias };
     if (value.event === 'live-session-released') {
         const release = allowlistedLabel(value.release, LIVE_SESSION_RELEASES);
-        return release ? { adapter: value.adapter, event: value.event, release, ...accessory } : undefined;
+        if (!release) {
+            return undefined;
+        }
+        const reports = nonNegativeInteger(value.reports);
+        const sinceLastReportMs = boundedInteger(value.sinceLastReportMs, MAX_STARTUP_WINDOW_MS);
+        return {
+            adapter: value.adapter,
+            event: value.event,
+            release,
+            ...(reports === undefined ? {} : { reports }),
+            ...(sinceLastReportMs === undefined ? {} : { sinceLastReportMs }),
+            ...accessory,
+        };
     }
     if (value.event === 'live-session-streaming') {
         return { adapter: value.adapter, event: value.event, ...accessory };
@@ -2163,11 +2411,13 @@ function sanitizeLiveSessionTrace(value) {
         !HOMEKIT_LIVE_SESSION_STAGES.has(value.stage)) {
         return undefined;
     }
+    const servingChannel = boundedInteger(value.servingChannel, MAX_STATION_CHANNEL);
     return {
         adapter: value.adapter,
         event: value.event,
         outcome: value.outcome,
         reason: value.reason,
+        ...(servingChannel === undefined ? {} : { servingChannel }),
         stage: value.stage,
         ...accessory,
     };