@homebridge-plugins/homebridge-eufy-security 5.0.0-beta.5 → 5.0.0-beta.7

package/dist/diagnostics.js

@@ -33,6 +33,8 @@ export function unconfirmedWriteCondition(property) {
         ? undefined
         : { code: 'camera-control-operation-failed', ...named, active: true, reason: 'not-confirmed' };
 }
+/** 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 bounded reasons a stream request is refused before it reaches the source. */
 const REFUSAL_REASONS = new Set(['disabled', 'at-capacity', 'cancelled', 'prepare-failed']);
 /**
@@ -47,6 +49,28 @@ const HOMEKIT_LIVE_REQUEST_EVENTS = new Set([
     'live-session-released',
     'live-session-streaming',
 ]);
+/**
+ * The error identities an SDK record may name, which is all a record carries of one.
+ *
+ * A message is never among them, so an identity absent here is recorded as `Error` and reads as any other
+ * 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',
+    '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
+ * the owner whose console paired it with a name.
+ */
+const PSEUDONYMOUS_FIELDS = new Set(['accessory', 'accessoryAliases']);
 const MAX_SDK_DETAILS = 16;
 const MAX_LOG_RECORD_BYTES = 64 * 1024;
 const MAX_CURRENT_LOG_BYTES = 50 * 1024 * 1024;
@@ -71,7 +95,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;
@@ -153,6 +182,15 @@ const SDK_EVENT_KEYS = new Set([
     'transport-error',
 ]);
 const EN_MESSAGES = JSON.parse(readFileSync(new URL('../i18n/runtime/en.json', import.meta.url), 'utf8'));
+/**
+ * The reporter's answer as a support archive carries it: every device, or how many they named.
+ *
+ * The serials themselves stay on the host. They identify one household's hardware, and no evidence class in an
+ * archive carries a device identity.
+ */
+function countedAffectedDevices(affected) {
+    return affected === 'all' ? 'all' : new Set(affected).size;
+}
 /** The bounded UI events a support session may record, and the only vocabulary the sink accepts. */
 const DIAGNOSTICS_UI_EVENTS = [
     'background-started',
@@ -302,54 +340,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.
  *
@@ -626,7 +745,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
                 ? []
@@ -635,15 +755,34 @@ export class GuidedDiagnostics {
                         evidence: 'reporter-statement',
                         privacyClass: 'diagnostic',
                         contentType: 'application/json',
-                        content: `${JSON.stringify({ version: 1, affectedDevices: session.affectedDevices })}\n`,
+                        content: `${JSON.stringify({ version: 2, affectedDevices: countedAffectedDevices(session.affectedDevices) })}\n`,
                         /**
-                         * What the reporter answered, not what the plugin observed. A serial identifies one household's
-                         * hardware, so the record is classified above the environment it sits beside and stays inside
-                         * the archive.
+                         * What the reporter answered, not what the plugin observed. A serial is a device identity and no
+                         * evidence class carries one, so the answer travels as its scope: every device, or how many were
+                         * named. Which ones is the reporter's to say in their own words.
                          */
                         fields: [
                             { field: 'version', privacyClass: 'operational' },
-                            { field: 'affectedDevices', privacyClass: 'pseudonymous' },
+                            { field: 'affectedDevices', privacyClass: 'operational' },
+                        ],
+                    },
+                ]),
+            ...(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' },
                         ],
                     },
                 ]),
@@ -651,18 +790,22 @@ export class GuidedDiagnostics {
                 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' }] : []),
                 ],
             },
         ];
@@ -713,7 +856,11 @@ export class GuidedDiagnostics {
                 ...(carried.retainedFrom === undefined ? {} : { retainedFrom: carried.retainedFrom }),
                 fields: [...new Set(carried.records.flatMap((record) => Object.keys(record)))].sort().map((field) => ({
                     field,
-                    privacyClass: field === 'accessoryAliases' ? 'pseudonymous' : field === 'timestamp' ? 'operational' : 'diagnostic',
+                    privacyClass: PSEUDONYMOUS_FIELDS.has(field)
+                        ? 'pseudonymous'
+                        : field === 'timestamp'
+                            ? 'operational'
+                            : 'diagnostic',
                 })),
             });
         }
@@ -1280,6 +1427,18 @@ function sanitizeSdkLiveStartTrace(value) {
 function opaquePullHandle(value) {
     return typeof value === 'string' && /^(?:pull|station)-\d{1,6}(?::\d{1,3})?$/.test(value) ? value : undefined;
 }
+/**
+ * One support-case accessory alias, or nothing where the value is not one.
+ *
+ * Matched against the shape an alias has rather than against what a serial looks like, on the same rule as
+ * {@link opaquePullHandle}: a record carries an alias or it carries no accessory at all.
+ */
+function opaqueAccessoryAlias(value) {
+    return typeof value === 'string' &&
+        /^accessory-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value)
+        ? value
+        : undefined;
+}
 /**
  * Adapts SDK protocol detail to bounded debug output without preserving supplied values.
  *
@@ -1321,9 +1480,7 @@ export function createSdkLogger(target) {
         const subsystem = SDK_SUBSYSTEMS.has(requestedSubsystem ?? '') ? requestedSubsystem : (aliasedSubsystem ?? 'sdk');
         const details = args.slice(0, MAX_SDK_DETAILS).map((value) => {
             if (value instanceof Error) {
-                const errorType = ['Error', 'RangeError', 'SessionExpiredError', 'TypeError'].includes(value.name)
-                    ? value.name
-                    : 'Error';
+                const errorType = SDK_ERROR_TYPES.includes(value.name) ? value.name : 'Error';
                 return { errorType };
             }
             if (typeof value === 'string') {
@@ -1742,12 +1899,7 @@ function sanitizeStructuredEvent(message) {
             if (!detail || typeof detail !== 'object' || Array.isArray(detail))
                 continue;
             const candidate = detail;
-            const errorType = allowlistedLabel(candidate.errorType, [
-                'Error',
-                'RangeError',
-                'SessionExpiredError',
-                'TypeError',
-            ]);
+            const errorType = allowlistedLabel(candidate.errorType, SDK_ERROR_TYPES);
             if (errorType) {
                 details.push({ errorType });
                 continue;
@@ -1813,6 +1965,7 @@ function sanitizeStructuredEvent(message) {
             !HOMEKIT_OBSERVATIONS.has(value.observation)) {
             return undefined;
         }
+        const alias = opaqueAccessoryAlias(value.accessory);
         return {
             scope: 'homekit',
             level: 'debug',
@@ -1822,6 +1975,7 @@ function sanitizeStructuredEvent(message) {
             ...(typeof value.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(value.announcedBy)
                 ? { announcedBy: value.announcedBy }
                 : {}),
+            ...(alias === undefined ? {} : { accessory: alias }),
         };
     }
     if (value.scope === 'runtime') {
@@ -1938,17 +2092,25 @@ export function reportInvalidSnapshotCache(target) {
     target[level](`[${code}] ${localize(target, messageKey)}`);
     target.debug?.(JSON.stringify({ scope: 'media-notice', level, code, messageKey }));
 }
-/** Emits one allowlisted HomeKit event trace only when host debug output is available. */
-export function reportHomeKitEvent(target, trace) {
+/**
+ * Emits one allowlisted HomeKit event trace only when host debug output is available.
+ *
+ * `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.
+ */
+export function reportHomeKitEvent(target, trace, aliasFor) {
+    const alias = typeof trace.serial === 'string' ? aliasFor?.(trace.serial) : undefined;
+    const offered = { ...trace, accessory: alias };
+    const accessory = alias === undefined ? {} : { accessory: alias };
     if (trace.event === 'live-video-selected') {
-        const selection = sanitizeLiveVideoSelection(trace);
+        const selection = sanitizeLiveVideoSelection(offered);
         if (target.debug && selection) {
             target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...selection }));
         }
         return;
     }
     if (HOMEKIT_LIVE_REQUEST_EVENTS.has(trace.event)) {
-        const lifecycle = sanitizeLiveSessionTrace(trace);
+        const lifecycle = sanitizeLiveSessionTrace(offered);
         if (target.debug && lifecycle) {
             target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...lifecycle }));
         }
@@ -1970,6 +2132,7 @@ export function reportHomeKitEvent(target, trace) {
         ...(typeof trace.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(trace.announcedBy)
             ? { announcedBy: trace.announcedBy }
             : {}),
+        ...accessory,
     }));
 }
 /**
@@ -2091,17 +2254,23 @@ function sanitizeLiveSessionTrace(value) {
     if (value.adapter !== 'camera.streaming') {
         return undefined;
     }
-    if (value.event === 'live-session-released' || value.event === 'live-session-streaming') {
-        return { adapter: value.adapter, event: value.event };
+    const alias = opaqueAccessoryAlias(value.accessory);
+    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 (value.event === 'live-session-streaming') {
+        return { adapter: value.adapter, event: value.event, ...accessory };
     }
     if (value.event === 'live-request-refused') {
         return typeof value.reason === 'string' && REFUSAL_REASONS.has(value.reason)
-            ? { adapter: value.adapter, event: value.event, reason: value.reason }
+            ? { adapter: value.adapter, event: value.event, reason: value.reason, ...accessory }
             : undefined;
     }
     if (value.event === 'live-request-unaccounted') {
         return typeof value.afterMs === 'number' && Number.isFinite(value.afterMs)
-            ? { adapter: value.adapter, event: value.event, afterMs: Math.round(value.afterMs) }
+            ? { adapter: value.adapter, event: value.event, afterMs: Math.round(value.afterMs), ...accessory }
             : undefined;
     }
     if (value.event !== 'live-session-failed' ||
@@ -2118,6 +2287,7 @@ function sanitizeLiveSessionTrace(value) {
         outcome: value.outcome,
         reason: value.reason,
         stage: value.stage,
+        ...accessory,
     };
 }
 function sanitizeLiveVideoSelection(value) {
@@ -2143,6 +2313,7 @@ function sanitizeLiveVideoSelection(value) {
         !HOMEKIT_LIVE_ADDRESS_VERSIONS.has(addressVersion)) {
         return undefined;
     }
+    const alias = opaqueAccessoryAlias(value.accessory);
     return {
         adapter: 'camera.streaming',
         event: 'live-video-selected',
@@ -2154,6 +2325,7 @@ function sanitizeLiveVideoSelection(value) {
         fps,
         mtu,
         addressVersion,
+        ...(alias === undefined ? {} : { accessory: alias }),
     };
 }
 /** Emits bounded normal-output condition transitions without stable device or account identity. */
@@ -2212,7 +2384,7 @@ export class DiagnosticConditions {
         }
         const uniqueDeviceIds = condition.active ? [...new Set(affectedDeviceIds)].sort() : [];
         const accessoryAliases = uniqueDeviceIds
-            .map((identity) => this.accessoryAlias(identity))
+            .map((identity) => this.aliasFor(identity))
             .filter((alias) => alias !== undefined)
             .sort();
         this.write(condition.code, condition.active, condition.reason, definition[0], definition[1], condition.active ? 'warn' : 'info', {
@@ -2229,7 +2401,13 @@ export class DiagnosticConditions {
         })
             .filter((named) => named !== undefined));
     }
-    accessoryAlias(identity) {
+    /**
+     * The support-case alias for one device identity, minted on first use.
+     *
+     * The one place an alias is decided, so every record about a device — a condition, a media trace — carries
+     * the same one, and the owner's console line is what resolves it to a name.
+     */
+    aliasFor(identity) {
         let alias = this.aliases.get(identity);
         if (!alias && this.aliases.size < MAX_ACCESSORY_ALIASES) {
             alias = `accessory-${randomUUID()}`;