@homebridge-plugins/homebridge-eufy-security 4.7.2 → 5.0.0-beta.0

package/dist/diagnostics.js

@@ -0,0 +1,2218 @@
+import { constants, createCipheriv, createHash, publicEncrypt, randomBytes, randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFile, chmod, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { gunzip as gunzipCallback, gzip as gzipCallback } from 'node:zlib';
+import { LIVE_TRACE_MESSAGE } from '@mega-yfue/eufy-sdk';
+/**
+ * The SDK properties whose unconfirmed write this plugin can name, and what it calls them.
+ *
+ * A write is acknowledged when the transport carried it, and the SDK reports separately where the device
+ * never applied it. Only a member this plugin actually writes is translated: anything else is a property
+ * some other consumer of the same account asked for, and claiming it would report a condition against an
+ * accessory this plugin never touched.
+ */
+const UNCONFIRMED_WRITE_MEMBERS = {
+    enabled: { capability: 'camera', member: 'enabled' },
+    statusLed: { capability: 'camera', member: 'statusLed' },
+    nightVision: { capability: 'camera', member: 'nightVision' },
+};
+/**
+ * The condition an unconfirmed write is reported under, or nothing where this plugin did not write it.
+ *
+ * It shares the code a failed control operation already uses, because the user's situation is the same one —
+ * a control that did not take — and differs only in how it was learnt: no error was raised, the device simply
+ * never reported the value. The reason names that distinction so a support case can tell the two apart.
+ */
+export function unconfirmedWriteCondition(property) {
+    const named = Object.hasOwn(UNCONFIRMED_WRITE_MEMBERS, property) ? UNCONFIRMED_WRITE_MEMBERS[property] : undefined;
+    return named === undefined
+        ? undefined
+        : { code: 'camera-control-operation-failed', ...named, active: true, reason: 'not-confirmed' };
+}
+/** The bounded reasons a stream request is refused before it reaches the source. */
+const REFUSAL_REASONS = new Set(['disabled', 'at-capacity', 'cancelled', 'prepare-failed']);
+/**
+ * The live request and session events {@link sanitizeLiveSessionTrace} reconstructs a record from.
+ *
+ * Read by both halves of the path: {@link reportHomeKitEvent} builds the record and the file sink rebuilds it.
+ */
+const HOMEKIT_LIVE_REQUEST_EVENTS = new Set([
+    'live-request-refused',
+    'live-request-unaccounted',
+    'live-session-failed',
+    'live-session-released',
+    'live-session-streaming',
+]);
+const MAX_SDK_DETAILS = 16;
+const MAX_LOG_RECORD_BYTES = 64 * 1024;
+const MAX_CURRENT_LOG_BYTES = 50 * 1024 * 1024;
+const MAX_QUEUED_LOG_BYTES = 1024 * 1024;
+/**
+ * How much of one evidence class a support archive carries, applied to each class on its own.
+ *
+ * Per class rather than as one shared pool. The classes a fault is diagnosed from are small and the SDK's is
+ * not, so one pool let the noisiest class decide how far back any of them reached — and because the read fills
+ * newest-first, a long session lost the diagnostic classes at their oldest end while SDK records stayed. Only
+ * the SDK's class reaches this bound in practice.
+ */
+const MAX_SUPPORT_ARCHIVE_LOG_BYTES = 16 * 1024 * 1024;
+const MAX_SUPPORT_ARCHIVE_MARKER_BYTES = 1024 * 1024;
+const MAX_UI_EVENTS_BYTES = 64 * 1024;
+const MAX_PENDING_UI_EVENTS = 8;
+const SUPPORT_ARCHIVE_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const LOG_ROTATIONS = 3;
+const LOG_DIRECTORY = 'logs';
+const LOG_FILE = 'homebridge-eufy.jsonl';
+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';
+/** 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;
+/**
+ * The version declared by the nearest `package.json` above a resolved file, or `unknown` if none states one.
+ *
+ * The nearest manifest above a module is the one that owns it, which is the same rule Node itself applies, so
+ * this reports the build that is actually loaded rather than a version written down a second time. It walks
+ * rather than joining a fixed number of segments because the plugin's own module is a directory deeper once
+ * built, and an SDK resolved through a link answers from wherever the link points.
+ */
+function loadedVersion(from) {
+    if (from === undefined) {
+        return 'unknown';
+    }
+    for (let directory = dirname(from); directory !== dirname(directory); directory = dirname(directory)) {
+        try {
+            const declared = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'))
+                .version;
+            return typeof declared === 'string' ? declared : 'unknown';
+        }
+        catch {
+            continue;
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Where the SDK the plugin loaded resides, or `undefined` when nothing answers the specifier.
+ *
+ * Resolution fails on its own terms and separately from reading: an installation that has not installed its
+ * dependencies resolves nothing, and a version label is not worth refusing to load diagnostics over.
+ */
+function loadedSdkEntry() {
+    try {
+        return createRequire(import.meta.url).resolve('@mega-yfue/eufy-sdk');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The plugin build this process loaded, read once at load from the manifest above this module.
+ *
+ * A support archive is read to decide whether a fault is already fixed, and without this an archive cannot
+ * answer that. Failure degrades to `unknown` rather than a guess, because a wrong version sends the reader
+ * further from the fault than an absent one does.
+ *
+ * It states the build in memory rather than the one on disk, which is what lets two processes notice an upgrade
+ * between them: after one lands, the runtime keeps answering with the build it started on until it is replaced.
+ */
+export const PLUGIN_VERSION = loadedVersion(fileURLToPath(import.meta.url));
+const SDK_VERSION = loadedVersion(loadedSdkEntry());
+const gzip = promisify(gzipCallback);
+const gunzip = promisify(gunzipCallback);
+const SDK_SUBSYSTEMS = new Set(['device', 'mega', 'mqtt', 'p2p', 'push', 'webrtc', 'sdk']);
+/**
+ * The events an SDK-scoped record may name, being the ones {@link createSdkLogger} classifies a message as.
+ *
+ * Disjoint from {@link HOMEKIT_LIVE_REQUEST_EVENTS}, which this plugin's own adapters report under `homekit`.
+ */
+const SDK_EVENT_KEYS = new Set([
+    'client-warning',
+    'connection-closed',
+    'connection-opened',
+    'connection-retrying',
+    'live-start-trace',
+    'media-error',
+    'media-warning',
+    'operation-failed',
+    'observation-invalid',
+    'protocol-command',
+    'protocol-unhandled',
+    'session-connecting',
+    'session-idle',
+    'session-resumed',
+    'session-restored',
+    'snapshot-cache-warning',
+    'transport-error',
+]);
+const EN_MESSAGES = JSON.parse(readFileSync(new URL('../i18n/runtime/en.json', import.meta.url), 'utf8'));
+/** The bounded UI events a support session may record, and the only vocabulary the sink accepts. */
+const DIAGNOSTICS_UI_EVENTS = [
+    'background-started',
+    'dashboard-opened',
+    'authentication-opened',
+    'request-failed',
+];
+const SUPPORT_ARCHIVE_KEY = {
+    keyId: 'support-2026-08-01',
+    sha256: 'e01d8a1c6c2b800772495b3f656b10899364ece0e82d846f7d33f61cdffbd451',
+    publicKey: `-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEArho8/7NwaYsZ3r27Lzek
+mJXOdSOtjuxKLWHxS40Hf6MFskF/dSwY8om0NZ22Qa/cygStAiP4eAmL1fEuNqlS
+JnoFgCtg6myFQVfeep9FWAJruR7EGp4WgiXopq8pvxSkJixZaYin2cch7CwUA5g9
+b2AcErlfAmZM6F0Sd9v5Q7rHF68x3MINi3BTDKsz/3KqkoJoxyosKjMNDNATEn/T
+y/yAF1/kELg7SJgnheWRoFK6130DEPzbym+TTxSZZOHeAtw27ALXoYGmnv09uq0K
+Bks4wOrvW8gWQpbMOfpbc3XeWsP7bOuIXr/fs3kXgHIZoJSiLW7JlsivL9z5NDl6
+UBxRyR0KOnK07Cx2xvl5pXfAOxQnc8F1JtjclzCHG6Q5sfq7isoMcpPuxDlEepgm
+FNkJi71G4+lWgTotQr/fTVeZ46IxXrtnq89pb0fE20WYMaHnXkz0FMCIjMjuQWEP
+R0zjeaRO8wZ3sqMgWSy2TldFsh709GqVUiS0YRUoVT1oExc27P47EFUNh57qI7bI
+tcEIHVhBqyawK+WrIC+vgBgAPg6w5klxVhUaWGltubIFSm86BxNDTGx7C6rllcRU
+pirqSQAW3PgOCg6d3lfkGLHVRsC+j6xsv1xC6clR6MKzklp7qz6uuOmf9GIdu+qE
+9U0RwKqGYSp/N8TF5n3p3s0CAwEAAQ==
+-----END PUBLIC KEY-----`,
+};
+const SUPPORT_ARCHIVE_EXCLUDED_CLASSES = [
+    'credentials-and-authentication',
+    'tokens-cookies-and-authorization',
+    'session-and-push-stores',
+    'private-and-symmetric-keys',
+    'unconstrained-sdk-objects',
+    'camera-images-talkback-and-raw-media',
+];
+const DIAGNOSTICS_PROFILES = {
+    'startup-authentication': ['plugin-log', 'sdk-log'],
+    'device-representation': ['plugin-log', 'sdk-log', 'homekit-log'],
+    'control-state': ['plugin-log', 'sdk-log', 'homekit-log'],
+    'live-media': ['plugin-log', 'sdk-log', 'homekit-log', 'ffmpeg-log'],
+    'hksv-recording': ['plugin-log', 'sdk-log', 'ffmpeg-log'],
+    'dashboard-ui': ['plugin-log', 'ui-log'],
+    other: ['plugin-log', 'sdk-log', 'homekit-log'],
+};
+/** Narrows external profile input against the diagnostics-owned profile registry. */
+export function isDiagnosticsProfile(value) {
+    return typeof value === 'string' && Object.hasOwn(DIAGNOSTICS_PROFILES, value);
+}
+/** Narrows external reproduction-mode input to the diagnostics-owned modes. */
+export function isDiagnosticsReproductionMode(value) {
+    return value === 'now' || value === 'intermittent';
+}
+/** Narrows external event input to the diagnostics-owned UI vocabulary. */
+export function isDiagnosticsUiEvent(value) {
+    return DIAGNOSTICS_UI_EVENTS.includes(value);
+}
+function diagnosticsSessionPath(storageRoot) {
+    return join(storageRoot, DIAGNOSTICS_DIRECTORY, GUIDED_SESSION_FILE);
+}
+/**
+ * Whether a value has the shape a support case identifier is issued in, which is the only shape one is
+ * accepted in from anywhere.
+ *
+ * A support case identifier names one authorized evidence window. It is randomly generated and carries no
+ * account, device, or host fact, which is why it may cross a process boundary.
+ */
+export function isSupportCaseId(value) {
+    return typeof value === 'string' && /^support-[0-9a-f-]{36}$/.test(value);
+}
+function readDiagnosticsSession(storageRoot) {
+    try {
+        const candidate = JSON.parse(readFileSync(diagnosticsSessionPath(storageRoot), 'utf8'));
+        const reproductionMode = candidate.reproductionMode ?? 'now';
+        if (candidate.version !== 1 ||
+            !isSupportCaseId(candidate.supportCaseId) ||
+            typeof candidate.profile !== 'string' ||
+            !isDiagnosticsProfile(candidate.profile) ||
+            !isDiagnosticsReproductionMode(reproductionMode) ||
+            typeof candidate.authorizedAt !== 'string' ||
+            typeof candidate.expiresAt !== 'string') {
+            return undefined;
+        }
+        return { ...candidate, reproductionMode };
+    }
+    catch {
+        return undefined;
+    }
+}
+function activeDiagnosticsSession(storageRoot, now) {
+    const session = readDiagnosticsSession(storageRoot);
+    return session && Date.parse(session.expiresAt) > now ? session : undefined;
+}
+/**
+ * Collapses one supplied string to bounded printable text, or nothing where none of it survives.
+ *
+ * Every value this module accepts from outside itself passes through here first, so that a field arriving as
+ * a novel, with control characters in it, or with a terminal escape sequence cannot become a record whatever
+ * the allowlist beyond it decides.
+ */
+function boundedText(value, maximumLength) {
+    const printable = value
+        .replace(/[^\x20-\x7e]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maximumLength)
+        .trim();
+    return printable === '' ? undefined : printable;
+}
+function ffmpegEnvironmentPath(storageRoot) {
+    return join(storageRoot, DIAGNOSTICS_DIRECTORY, FFMPEG_ENVIRONMENT_FILE);
+}
+/**
+ * Records which FFmpeg this run resolved, so a support archive states the build a failure came from.
+ *
+ * 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.
+ */
+export function recordFfmpegEnvironment(storageRoot, ffmpeg) {
+    try {
+        const path = ffmpegEnvironmentPath(storageRoot);
+        mkdirSync(dirname(path), { mode: 0o700, recursive: true });
+        writeFileSync(path, `${JSON.stringify({ version: 1, ffmpeg })}\n`, { mode: 0o600 });
+    }
+    catch { }
+}
+/**
+ * Reads the recorded adaptation binary, refusing a record whose 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 readFfmpegEnvironment(storageRoot) {
+    try {
+        const candidate = JSON.parse(readFileSync(ffmpegEnvironmentPath(storageRoot), 'utf8'));
+        const ffmpeg = candidate.ffmpeg;
+        if (candidate.version !== 1 || !ffmpeg || typeof ffmpeg !== 'object' || Array.isArray(ffmpeg)) {
+            return undefined;
+        }
+        const recorded = ffmpeg;
+        if (typeof recorded.path !== 'string' || (recorded.source !== 'bundled' && recorded.source !== 'configured')) {
+            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 }) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The one log evidence class a retained record belongs to.
+ *
+ * The four classes partition the records: each verbose scope owns its own and everything else is the plugin's,
+ * so a record counts against exactly one class's budget.
+ */
+function evidenceClassOf(record) {
+    const scope = String(record.scope);
+    if (scope === 'sdk')
+        return 'sdk-log';
+    if (scope === 'homekit')
+        return 'homekit-log';
+    if (scope === 'ffmpeg')
+        return 'ffmpeg-log';
+    return 'plugin-log';
+}
+/**
+ * The classes a profile selected that a collection of that session's evidence carries no content for.
+ *
+ * The status a session reports and the manifest an archive carries name the same classes because both ask
+ * here, against the same collection.
+ */
+function missingEvidenceClasses(selected, collected) {
+    return selected.filter((evidence) => !collected.some((candidate) => candidate.evidence === evidence));
+}
+/** The scopes whose records are only kept while a support profile that declares them is authorized. */
+const VERBOSE_SCOPES = new Set(['sdk', 'homekit', 'ffmpeg']);
+/** Owns persisted, user-authorized diagnostic evidence windows and identity-free reproduction markers. */
+export class GuidedDiagnostics {
+    storageRoot;
+    now;
+    supportArchiveKey;
+    pendingSupportArchive;
+    uiEventWrites = Promise.resolve();
+    pendingUiEvents = 0;
+    uiEventsClosing = false;
+    constructor(storageRoot, now = Date.now, supportArchiveKey = SUPPORT_ARCHIVE_KEY) {
+        this.storageRoot = storageRoot;
+        this.now = now;
+        this.supportArchiveKey = supportArchiveKey;
+    }
+    async authorize(profile, reproductionMode) {
+        if (!isDiagnosticsProfile(profile)) {
+            throw new Error('Unknown diagnostics profile');
+        }
+        if (!isDiagnosticsReproductionMode(reproductionMode)) {
+            throw new Error('Unknown diagnostics reproduction mode');
+        }
+        this.uiEventsClosing = true;
+        try {
+            await this.uiEventWrites;
+            const authorizedAt = this.now();
+            const session = {
+                version: 1,
+                supportCaseId: `support-${randomUUID()}`,
+                profile,
+                reproductionMode,
+                authorizedAt: new Date(authorizedAt).toISOString(),
+                expiresAt: new Date(authorizedAt + DEBUG_AUTHORIZATION_MS).toISOString(),
+            };
+            await this.writeSession(session);
+            this.pendingSupportArchive = undefined;
+            return await this.project(session);
+        }
+        finally {
+            this.uiEventsClosing = false;
+        }
+    }
+    async status() {
+        return this.project(readDiagnosticsSession(this.storageRoot));
+    }
+    async startReproduction() {
+        const session = this.requireAuthorized();
+        if (!session.reproductionStartedAt || session.reproductionEndedAt) {
+            if (session.reproductionEndedAt) {
+                session.supportCaseId = `support-${randomUUID()}`;
+                this.pendingSupportArchive = undefined;
+            }
+            if (session.profile === 'dashboard-ui') {
+                await this.uiEventWrites;
+                this.uiEventsClosing = false;
+            }
+            session.reproductionStartedAt = new Date(this.now()).toISOString();
+            delete session.reproductionEndedAt;
+            await this.writeSession(session);
+        }
+        await this.ensureMarker(session, 'reproduction-started', session.reproductionStartedAt);
+        return this.project(session);
+    }
+    async endReproduction() {
+        let session = this.requireAuthorized();
+        if (!session.reproductionStartedAt) {
+            throw new Error('Reproduction has not started');
+        }
+        const closesUiEvents = session.profile === 'dashboard-ui';
+        if (closesUiEvents) {
+            this.uiEventsClosing = true;
+        }
+        try {
+            if (closesUiEvents) {
+                await this.uiEventWrites;
+                session = this.requireAuthorized();
+            }
+            if (!session.reproductionEndedAt) {
+                session.reproductionEndedAt = new Date(this.now()).toISOString();
+                await this.writeSession(session);
+            }
+            await this.ensureMarker(session, 'reproduction-ended', session.reproductionEndedAt);
+            return await this.project(session);
+        }
+        catch (error) {
+            if (closesUiEvents)
+                this.uiEventsClosing = false;
+            throw error;
+        }
+    }
+    async recordUiEvent(event) {
+        if (!isDiagnosticsUiEvent(event)) {
+            throw new Error('Unknown diagnostics UI event');
+        }
+        if (this.uiEventsClosing) {
+            throw new Error('Diagnostics UI events are closing');
+        }
+        if (this.pendingUiEvents >= MAX_PENDING_UI_EVENTS) {
+            throw new Error('Diagnostics UI event queue is full');
+        }
+        this.pendingUiEvents += 1;
+        const write = this.uiEventWrites.then(async () => {
+            const session = this.requireAuthorized();
+            if (session.profile !== 'dashboard-ui' || !session.reproductionStartedAt || session.reproductionEndedAt) {
+                throw new Error('An active dashboard reproduction is required');
+            }
+            const directory = join(this.storageRoot, DIAGNOSTICS_DIRECTORY);
+            const path = join(directory, UI_EVENTS_FILE);
+            await mkdir(directory, { mode: 0o700, recursive: true });
+            await chmod(directory, 0o700);
+            const record = `${JSON.stringify({
+                version: 1,
+                supportCaseId: session.supportCaseId,
+                timestamp: new Date(this.now()).toISOString(),
+                event,
+            })}\n`;
+            let currentBytes = 0;
+            try {
+                currentBytes = (await stat(path)).size;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            if (currentBytes + Buffer.byteLength(record) > MAX_UI_EVENTS_BYTES) {
+                const retained = await this.readFileTail(path, MAX_UI_EVENTS_BYTES - Buffer.byteLength(record));
+                await writeFile(path, `${retained}${record}`, { encoding: 'utf8', mode: 0o600 });
+            }
+            else {
+                await appendFile(path, record, { encoding: 'utf8', mode: 0o600 });
+            }
+            await chmod(path, 0o600);
+        });
+        this.uiEventWrites = write
+            .catch(() => undefined)
+            .finally(() => {
+            this.pendingUiEvents -= 1;
+        });
+        return write;
+    }
+    /** Prepares the exact manifest and evidence snapshot that one subsequent export may encrypt. */
+    async reviewSupportArchive() {
+        await this.uiEventWrites;
+        const session = readDiagnosticsSession(this.storageRoot);
+        if (!session?.reproductionStartedAt || !session.reproductionEndedAt) {
+            throw new Error('A completed reproduction is required before archive review');
+        }
+        const collected = await this.collectSupportEvidence(session);
+        const reproductionStartedAt = Date.parse(session.reproductionStartedAt);
+        const selected = DIAGNOSTICS_PROFILES[session.profile];
+        const createdAt = this.now();
+        const manifest = {
+            version: 2,
+            archiveFormat: 'homebridge-eufy-support-archive',
+            keyId: this.supportArchiveKey.keyId,
+            supportCaseId: session.supportCaseId,
+            profile: session.profile,
+            reproductionMode: session.reproductionMode,
+            createdAt: new Date(createdAt).toISOString(),
+            archiveExpiresAt: new Date(createdAt + SUPPORT_ARCHIVE_RETENTION_MS).toISOString(),
+            reproductionStartedAt: session.reproductionStartedAt,
+            reproductionEndedAt: session.reproductionEndedAt,
+            evidence: [
+                ...collected.map(({ evidence, privacyClass, contentType, content, truncated, retainedFrom, fields }) => ({
+                    evidence,
+                    privacyClass,
+                    status: 'included',
+                    contentType,
+                    bytes: Buffer.byteLength(content),
+                    fields,
+                    ...(truncated ? { truncated: true } : {}),
+                    ...(retainedFrom === undefined ? {} : { retainedFrom }),
+                    ...(retainedFrom !== undefined && Date.parse(retainedFrom) > reproductionStartedAt
+                        ? { coversReproduction: false }
+                        : {}),
+                })),
+                ...missingEvidenceClasses(selected, collected).map((evidence) => ({
+                    evidence,
+                    privacyClass: 'diagnostic',
+                    status: 'missing',
+                    missingReason: 'no-allowlisted-record-observed',
+                })),
+            ],
+            excludedClasses: SUPPORT_ARCHIVE_EXCLUDED_CLASSES,
+        };
+        const reviewId = randomUUID();
+        this.pendingSupportArchive = { reviewId, manifest, evidence: collected };
+        return { reviewId, manifest };
+    }
+    /** Consumes one reviewed snapshot and returns an encrypted envelope without writing plaintext or an archive to disk. */
+    async exportSupportArchive(reviewId) {
+        const pending = this.pendingSupportArchive;
+        if (!pending || pending.reviewId !== reviewId) {
+            throw new Error('Support archive manifest review is missing or stale');
+        }
+        this.pendingSupportArchive = undefined;
+        if (Date.parse(pending.manifest.archiveExpiresAt) <= this.now()) {
+            throw new Error('Support archive manifest review is missing or stale');
+        }
+        const keyFingerprint = createHash('sha256').update(this.supportArchiveKey.publicKey.trim()).digest('hex');
+        if (keyFingerprint !== this.supportArchiveKey.sha256) {
+            throw new Error('Support archive key integrity check failed');
+        }
+        const compressed = await gzip(Buffer.from(JSON.stringify({
+            manifest: pending.manifest,
+            // Coverage is manifest metadata; the payload row is the content it describes.
+            evidence: pending.evidence.map(({ retainedFrom: _retainedFrom, ...row }) => row),
+        }), 'utf8'));
+        const contentKey = randomBytes(32);
+        try {
+            const iv = randomBytes(12);
+            const cipher = createCipheriv('aes-256-gcm', contentKey, iv);
+            const metadata = {
+                format: 'homebridge-eufy-support-archive',
+                version: 1,
+                keyId: this.supportArchiveKey.keyId,
+                keyWrapAlgorithm: 'RSA-OAEP-SHA256',
+                contentAlgorithm: 'AES-256-GCM',
+                contentEncoding: 'gzip+json',
+            };
+            const authenticatedMetadata = Buffer.from(JSON.stringify(metadata), 'utf8');
+            cipher.setAAD(authenticatedMetadata);
+            const ciphertext = Buffer.concat([cipher.update(compressed), cipher.final()]);
+            const wrappedKey = publicEncrypt({
+                key: this.supportArchiveKey.publicKey,
+                oaepHash: 'sha256',
+                padding: constants.RSA_PKCS1_OAEP_PADDING,
+            }, contentKey);
+            const envelope = {
+                ...metadata,
+                wrappedKey: wrappedKey.toString('base64'),
+                iv: iv.toString('base64'),
+                authTag: cipher.getAuthTag().toString('base64'),
+                ciphertext: ciphertext.toString('base64'),
+            };
+            return {
+                filename: `homebridge-eufy-${pending.manifest.supportCaseId}.eufysupport.gz`,
+                mediaType: 'application/gzip',
+                archive: await gzip(Buffer.from(`${JSON.stringify(envelope)}\n`, 'utf8')),
+            };
+        }
+        finally {
+            contentKey.fill(0);
+        }
+    }
+    async collectSupportEvidence(session) {
+        const ffmpeg = readFfmpegEnvironment(this.storageRoot);
+        const evidence = [
+            {
+                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`,
+                /**
+                 * 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.
+                 */
+                fields: [
+                    ...['version', 'plugin', 'sdk', 'node', 'platform', 'arch'].map((field) => ({
+                        field,
+                        privacyClass: 'operational',
+                    })),
+                    ...(ffmpeg ? [{ field: 'ffmpeg', privacyClass: 'diagnostic' }] : []),
+                ],
+            },
+        ];
+        const markers = await this.readReproductionMarkers(session.supportCaseId);
+        if (markers) {
+            evidence.push({
+                evidence: 'reproduction-markers',
+                privacyClass: 'operational',
+                contentType: 'application/x-ndjson',
+                content: markers,
+                fields: [
+                    { field: 'version', privacyClass: 'operational' },
+                    { field: 'supportCaseId', privacyClass: 'pseudonymous' },
+                    { field: 'event', privacyClass: 'operational' },
+                    { field: 'timestamp', privacyClass: 'operational' },
+                ],
+            });
+        }
+        const uiEvents = await this.readUiEvents(session);
+        if (uiEvents) {
+            evidence.push({
+                evidence: 'ui-log',
+                privacyClass: 'diagnostic',
+                contentType: 'application/x-ndjson',
+                content: uiEvents,
+                fields: [
+                    { field: 'version', privacyClass: 'operational' },
+                    { field: 'supportCaseId', privacyClass: 'pseudonymous' },
+                    { field: 'timestamp', privacyClass: 'operational' },
+                    { field: 'event', privacyClass: 'diagnostic' },
+                ],
+            });
+        }
+        const log = await this.readReproductionLog(session.reproductionStartedAt, session.reproductionEndedAt);
+        for (const selected of DIAGNOSTICS_PROFILES[session.profile]) {
+            const carried = log.get(selected);
+            if (!carried)
+                continue;
+            const content = carried.records.map((record) => JSON.stringify(record)).join('\n');
+            if (!content)
+                continue;
+            evidence.push({
+                evidence: selected,
+                privacyClass: 'diagnostic',
+                contentType: 'application/x-ndjson',
+                content: `${content}\n`,
+                ...(carried.truncated ? { truncated: true } : {}),
+                ...(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',
+                })),
+            });
+        }
+        return evidence;
+    }
+    async readUiEvents(session) {
+        try {
+            const path = join(this.storageRoot, DIAGNOSTICS_DIRECTORY, UI_EVENTS_FILE);
+            const startedAt = Date.parse(session.reproductionStartedAt);
+            const endedAt = Date.parse(session.reproductionEndedAt);
+            const records = (await this.readFileTail(path, MAX_UI_EVENTS_BYTES))
+                .trim()
+                .split('\n')
+                .flatMap((line) => {
+                try {
+                    const candidate = JSON.parse(line);
+                    const timestamp = typeof candidate.timestamp === 'string' ? Date.parse(candidate.timestamp) : Number.NaN;
+                    if (Object.keys(candidate).sort().join(',') !== 'event,supportCaseId,timestamp,version' ||
+                        candidate.version !== 1 ||
+                        candidate.supportCaseId !== session.supportCaseId ||
+                        !isDiagnosticsUiEvent(candidate.event) ||
+                        !Number.isFinite(timestamp) ||
+                        timestamp < startedAt ||
+                        timestamp > endedAt) {
+                        return [];
+                    }
+                    return [
+                        JSON.stringify({
+                            version: 1,
+                            supportCaseId: candidate.supportCaseId,
+                            timestamp: new Date(timestamp).toISOString(),
+                            event: candidate.event,
+                        }),
+                    ];
+                }
+                catch {
+                    return [];
+                }
+            });
+            return records.length ? `${records.join('\n')}\n` : '';
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+    }
+    async readReproductionMarkers(supportCaseId) {
+        try {
+            const path = join(this.storageRoot, DIAGNOSTICS_DIRECTORY, REPRODUCTION_MARKERS_FILE);
+            const lines = (await this.readFileTail(path, MAX_SUPPORT_ARCHIVE_MARKER_BYTES))
+                .trim()
+                .split('\n')
+                .filter((line) => {
+                try {
+                    return JSON.parse(line).supportCaseId === supportCaseId;
+                }
+                catch {
+                    return false;
+                }
+            });
+            return lines.length ? `${lines.join('\n')}\n` : '';
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+    }
+    /**
+     * The records of each log evidence class inside the reproduction interval, budgeted per class.
+     *
+     * Fills newest-first, so a class that exhausts its budget loses its oldest end and `retainedFrom` states
+     * where it then begins. Each class is budgeted alone, so the noisiest one cannot decide how far back another
+     * reaches.
+     */
+    async readReproductionLog(startedAt, endedAt) {
+        const directory = join(this.storageRoot, LOG_DIRECTORY);
+        const paths = [
+            join(directory, LOG_FILE),
+            ...Array.from({ length: LOG_ROTATIONS }, (_, index) => join(directory, `${LOG_FILE}.${index + 1}.gz`)),
+        ];
+        const started = Date.parse(startedAt);
+        const ended = Date.parse(endedAt);
+        const carried = new Map(['plugin-log', 'sdk-log', 'homekit-log', 'ffmpeg-log'].map((evidence) => [
+            evidence,
+            { records: [], bytes: 0, truncated: false },
+        ]));
+        for (const path of paths) {
+            if ([...carried.values()].every(({ truncated }) => truncated))
+                break;
+            try {
+                const file = await stat(path);
+                if (file.size > MAX_CURRENT_LOG_BYTES) {
+                    for (const state of carried.values())
+                        state.truncated = true;
+                    continue;
+                }
+                const content = path.endsWith('.gz')
+                    ? (await gunzip(await readFile(path), {
+                        maxOutputLength: MAX_CURRENT_LOG_BYTES + MAX_LOG_RECORD_BYTES,
+                    })).toString('utf8')
+                    : await readFile(path, 'utf8');
+                const lines = content.trim().split('\n');
+                for (let index = lines.length - 1; index >= 0; index -= 1) {
+                    const line = lines[index];
+                    let record;
+                    try {
+                        record = JSON.parse(line);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const timestamp = typeof record.timestamp === 'string' ? Date.parse(record.timestamp) : Number.NaN;
+                    if (timestamp < started || timestamp > ended)
+                        continue;
+                    const state = carried.get(evidenceClassOf(record));
+                    if (state.truncated)
+                        continue;
+                    const bytes = Buffer.byteLength(line) + 1;
+                    if (state.bytes + bytes > MAX_SUPPORT_ARCHIVE_LOG_BYTES) {
+                        state.truncated = true;
+                        continue;
+                    }
+                    state.bytes += bytes;
+                    state.records.push(record);
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return new Map([...carried].map(([evidence, { records, truncated }]) => {
+            const ordered = records.reverse();
+            const oldest = ordered.find(({ timestamp }) => typeof timestamp === 'string')?.timestamp;
+            return [
+                evidence,
+                { records: ordered, truncated, ...(truncated && typeof oldest === 'string' ? { retainedFrom: oldest } : {}) },
+            ];
+        }));
+    }
+    async readFileTail(path, maximumBytes) {
+        const file = await open(path, 'r');
+        try {
+            const size = (await file.stat()).size;
+            const bytes = Math.min(size, maximumBytes);
+            const buffer = Buffer.alloc(bytes);
+            await file.read(buffer, 0, bytes, size - bytes);
+            const content = buffer.toString('utf8');
+            return size > maximumBytes ? content.slice(content.indexOf('\n') + 1) : content;
+        }
+        finally {
+            await file.close();
+        }
+    }
+    requireAuthorized() {
+        const session = activeDiagnosticsSession(this.storageRoot, this.now());
+        if (!session)
+            throw new Error('Diagnostics authorization is inactive or expired');
+        return session;
+    }
+    async project(session) {
+        if (!session) {
+            return { status: 'inactive', selectedEvidence: [], missingEvidence: [], partialExportAvailable: false };
+        }
+        const selectedEvidence = DIAGNOSTICS_PROFILES[session.profile];
+        const collected = session.reproductionStartedAt && session.reproductionEndedAt
+            ? await this.collectSupportEvidence(session)
+            : undefined;
+        const missingEvidence = collected ? missingEvidenceClasses(selectedEvidence, collected) : [];
+        const expired = Date.parse(session.expiresAt) <= this.now();
+        const status = expired
+            ? 'expired'
+            : session.reproductionEndedAt
+                ? 'complete'
+                : session.reproductionStartedAt
+                    ? 'reproducing'
+                    : 'authorized';
+        const issueBody = [
+            `Support case: ${session.supportCaseId}`,
+            `Profile: ${session.profile}`,
+            `Reproduction mode: ${session.reproductionMode}`,
+            `Missing evidence: ${missingEvidence.length ? missingEvidence.join(', ') : 'none'}`,
+        ].join('\n');
+        return {
+            status,
+            supportCaseId: session.supportCaseId,
+            profile: session.profile,
+            reproductionMode: session.reproductionMode,
+            selectedEvidence,
+            missingEvidence,
+            authorizedAt: session.authorizedAt,
+            expiresAt: session.expiresAt,
+            ...(session.reproductionStartedAt ? { reproductionStartedAt: session.reproductionStartedAt } : {}),
+            ...(session.reproductionEndedAt ? { reproductionEndedAt: session.reproductionEndedAt } : {}),
+            partialExportAvailable: Boolean(session.reproductionEndedAt),
+            issueUrl: `https://github.com/homebridge-plugins/homebridge-eufy/issues/new?body=${encodeURIComponent(issueBody)}`,
+        };
+    }
+    /**
+     * Replaces the persisted session, and drops the `diagnostics/evidence` tree with it.
+     *
+     * Nothing reads that tree: a session's completeness is one read of the evidence an archive would carry, so
+     * the only diagnostics state that outlives a session is the rotating log and the persisted session itself.
+     */
+    async writeSession(session) {
+        const directory = join(this.storageRoot, DIAGNOSTICS_DIRECTORY);
+        await mkdir(directory, { mode: 0o700, recursive: true });
+        await chmod(directory, 0o700);
+        await rm(join(directory, 'evidence'), { force: true, recursive: true });
+        await this.replaceOwnedFile(diagnosticsSessionPath(this.storageRoot), `${JSON.stringify(session)}\n`);
+    }
+    /** Replaces one file this module owns in a single step, readable only by the account Homebridge runs as. */
+    async replaceOwnedFile(path, content) {
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        await writeFile(temporary, content, { mode: 0o600 });
+        await chmod(temporary, 0o600);
+        await rename(temporary, path);
+    }
+    /**
+     * Records one bounded reproduction edge, keeping the markers file to the current support case.
+     *
+     * The interval a maintainer receives is the one being reproduced now, so an earlier case's markers are
+     * dropped here rather than accumulating one durable record per support session for the life of the install.
+     * Recording the same edge twice is a no-op, which is what lets a restart re-record an interval it already had.
+     */
+    async ensureMarker(session, event, timestamp) {
+        const directory = join(this.storageRoot, DIAGNOSTICS_DIRECTORY);
+        await mkdir(directory, { mode: 0o700, recursive: true });
+        const retained = await this.readReproductionMarkers(session.supportCaseId);
+        const marker = `${JSON.stringify({ version: 1, supportCaseId: session.supportCaseId, event, timestamp })}\n`;
+        if (retained.includes(marker)) {
+            return;
+        }
+        await this.replaceOwnedFile(join(directory, REPRODUCTION_MARKERS_FILE), `${retained}${marker}`);
+    }
+}
+function formatMessage(catalog, key, parameters = {}) {
+    const template = catalog[key] ?? EN_MESSAGES[key] ?? key;
+    return template
+        .replace(/\{([a-zA-Z0-9]+)\}/g, (placeholder, name) => parameters[name] === undefined ? placeholder : String(parameters[name]))
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function localize(target, key, parameters = {}) {
+    const translator = target.localize;
+    return translator?.(key, parameters) ?? formatMessage(EN_MESSAGES, key, parameters);
+}
+class JsonLineLog {
+    onError;
+    now;
+    directory;
+    path;
+    pending = Promise.resolve();
+    queuedBytes = 0;
+    droppedRecords = 0;
+    droppedAt;
+    constructor(storageRoot, onError, now) {
+        this.onError = onError;
+        this.now = now;
+        this.directory = join(storageRoot, LOG_DIRECTORY);
+        this.path = join(this.directory, LOG_FILE);
+    }
+    write(message) {
+        const payload = sanitizeStructuredEvent(message);
+        if (!payload) {
+            return;
+        }
+        const record = this.serialize(payload);
+        const bytes = Buffer.byteLength(record);
+        if (bytes > MAX_LOG_RECORD_BYTES || this.queuedBytes + bytes > MAX_QUEUED_LOG_BYTES) {
+            this.droppedAt ??= new Date().toISOString();
+            this.droppedRecords += 1;
+            return;
+        }
+        const droppedRecords = this.droppedRecords;
+        const droppedAt = this.droppedAt;
+        this.droppedRecords = 0;
+        this.droppedAt = undefined;
+        this.queuedBytes += bytes;
+        this.pending = this.pending
+            .then(async () => {
+            if (droppedRecords > 0) {
+                await this.append(this.serialize({
+                    scope: 'diagnostics',
+                    level: 'warn',
+                    event: 'records-dropped',
+                    droppedRecords,
+                }, droppedAt));
+            }
+            await this.append(record);
+        })
+            .catch(() => this.onError())
+            .finally(() => {
+            this.queuedBytes -= bytes;
+        });
+    }
+    flush() {
+        const droppedRecords = this.droppedRecords;
+        const droppedAt = this.droppedAt;
+        this.droppedRecords = 0;
+        this.droppedAt = undefined;
+        if (droppedRecords > 0) {
+            this.pending = this.pending
+                .then(() => this.append(this.serialize({
+                scope: 'diagnostics',
+                level: 'warn',
+                event: 'records-dropped',
+                droppedRecords,
+            }, droppedAt)))
+                .catch(() => this.onError());
+        }
+        return this.pending;
+    }
+    serialize(payload, timestamp = new Date(this.now()).toISOString()) {
+        return `${JSON.stringify({ ...payload, timestamp })}\n`;
+    }
+    async append(record) {
+        await mkdir(this.directory, { mode: 0o700, recursive: true });
+        await chmod(this.directory, 0o700);
+        const bytes = Buffer.byteLength(record);
+        await this.prepare(bytes);
+        try {
+            await chmod(this.path, 0o600);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        await appendFile(this.path, record, { encoding: 'utf8', flag: 'a', mode: 0o600 });
+        await chmod(this.path, 0o600);
+    }
+    async prepare(recordBytes) {
+        try {
+            const current = await stat(this.path);
+            const today = new Date().toISOString().slice(0, 10);
+            const currentDay = current.mtime.toISOString().slice(0, 10);
+            if (currentDay !== today || current.size + recordBytes > MAX_CURRENT_LOG_BYTES) {
+                await this.rotate();
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    async rotate() {
+        await rm(`${this.path}.${LOG_ROTATIONS}.gz`, { force: true });
+        for (let index = LOG_ROTATIONS - 1; index >= 1; index -= 1) {
+            try {
+                const target = `${this.path}.${index + 1}.gz`;
+                await rename(`${this.path}.${index}.gz`, target);
+                await chmod(target, 0o600);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+        }
+        const compressed = await gzip(await readFile(this.path));
+        await writeFile(`${this.path}.1.gz`, compressed, { flag: 'w', mode: 0o600 });
+        await chmod(`${this.path}.1.gz`, 0o600);
+        await rm(this.path, { force: true });
+    }
+}
+/**
+ * Routes human messages to Homebridge and structured events to the plugin JSONL log.
+ * File writes preserve accepted order; records beyond the bounded pending queue are counted and reported.
+ */
+export function createDiagnosticLogger(target, storageRoot, catalog = EN_MESSAGES, now = Date.now) {
+    let fileFailureReported = false;
+    const reportFileFailure = () => {
+        if (!fileFailureReported) {
+            fileFailureReported = true;
+            target.warn(`[diagnostic-log-write-failed] ${formatMessage(catalog, 'log.diagnosticFileFailed')}`);
+        }
+    };
+    const file = storageRoot ? new JsonLineLog(storageRoot, reportFileFailure, now) : undefined;
+    const debug = file
+        ? (message) => {
+            const event = sanitizeStructuredEvent(message);
+            if (!event)
+                return;
+            const session = activeDiagnosticsSession(storageRoot, now());
+            const verbose = VERBOSE_SCOPES.has(String(event.scope));
+            if (verbose && (!session || !DIAGNOSTICS_PROFILES[session.profile].includes(evidenceClassOf(event)))) {
+                return;
+            }
+            file.write(JSON.stringify(event));
+        }
+        : undefined;
+    return {
+        ...(debug ? { debug } : {}),
+        error: (message) => target.error(message),
+        flush: () => file?.flush() ?? Promise.resolve(),
+        info: (message) => target.info(message),
+        localize: (key, parameters) => formatMessage(catalog, key, parameters),
+        warn: (message) => target.warn(message),
+    };
+}
+/** The class an SDK message belongs to, or nothing when its text matches none of them. */
+function classifySdkEvent(message) {
+    const normalized = message.toLowerCase();
+    if (normalized.includes('restored persisted session'))
+        return 'session-restored';
+    if (normalized.includes('retrying') || normalized.includes('reconnecting'))
+        return 'connection-retrying';
+    if (normalized.includes('close') || normalized.includes('disconnect'))
+        return 'connection-closed';
+    if (normalized.includes('in use again') || normalized.includes('idle-detach cancelled'))
+        return 'session-resumed';
+    if (normalized.includes('connecting'))
+        return 'session-connecting';
+    if (normalized.includes('connected') || normalized.includes('logged in'))
+        return 'connection-opened';
+    if (normalized.includes('idle'))
+        return 'session-idle';
+    if (normalized.includes('candidate failed'))
+        return 'snapshot-cache-warning';
+    if (normalized.includes('wire value is not numeric') ||
+        normalized.includes('unknown codec') ||
+        normalized.includes('malformed')) {
+        return 'observation-invalid';
+    }
+    if (normalized.includes('unhandled payload'))
+        return 'protocol-unhandled';
+    if (normalized.includes('sendsetpayload') ||
+        normalized.includes('requestimage') ||
+        normalized.includes('querydatabase')) {
+        return 'protocol-command';
+    }
+    if ((normalized.includes('talkback') || normalized.includes('live media') || normalized.includes('live stream')) &&
+        (normalized.includes('failed') || normalized.includes('error'))) {
+        return 'media-error';
+    }
+    if (normalized.includes('upstream error') ||
+        normalized.includes('send err') ||
+        normalized.includes('connection error')) {
+        return 'transport-error';
+    }
+    if (normalized.includes('failed') || normalized.includes('error'))
+        return 'operation-failed';
+    if (normalized.includes('talkback') ||
+        normalized.includes('live media') ||
+        normalized.includes('startlivemedia') ||
+        normalized.includes('stoplivemedia')) {
+        return 'media-warning';
+    }
+    if (normalized.includes('[eufy]'))
+        return 'client-warning';
+    return undefined;
+}
+/** A non-negative integer, or nothing — a byte count, a duration, a tally of accessories. */
+function nonNegativeInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : undefined;
+}
+/**
+ * A whole number within an inclusive range, or nothing — a data-type id, a sign code, an exit status, or a
+ * negotiated geometry or frame rate a controller chose.
+ */
+function boundedInteger(value, max, min = 0) {
+    const integer = nonNegativeInteger(value);
+    return integer !== undefined && integer <= max && integer >= min ? integer : undefined;
+}
+/**
+ * One of a fixed set of labels, or nothing.
+ *
+ * The only string form any value crossing this boundary is retained in: a label that is not on the list is
+ * dropped rather than truncated or escaped, so no supplied text is ever carried through.
+ */
+function allowlistedLabel(value, allowed) {
+    return allowed.includes(String(value)) ? String(value) : undefined;
+}
+/**
+ * The widest startup window a retained duration may state.
+ *
+ * A minute bounds every window the SDK actually uses — a level-2 grace, a warm-up deadline, a retry interval —
+ * and a duration beyond it is a value this plugin did not expect rather than a measurement, so it is dropped
+ * like any other field that fails its shape.
+ */
+const MAX_STARTUP_WINDOW_MS = 60_000;
+/** 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. */
+const retainedInteger = (field, max) => (candidate) => {
+    const value = boundedInteger(candidate[field], max);
+    return value === undefined ? undefined : { [field]: value };
+};
+/**
+ * What each phase of the SDK's live trace vocabulary retains, keyed by the phase itself.
+ *
+ * Typed against the published `LiveTrace` union, so a phase this table does not name fails to compile rather
+ * than being dropped to a content-free record at runtime.
+ *
+ * Each entry validates the fields its own phase declares, by name, and returns nothing when they are not the
+ * shape claimed, because this reads a value that crossed a process boundary. A field is retained only as a
+ * fixed label, a boolean, or a bounded integer; the SDK states that its traces carry no serial, address or
+ * key material, and validating rather than copying is what keeps that true here whatever it sends.
+ *
+ * The field NAMES are not checked against the union, only the phases are — so a field the SDK renames within
+ * an existing phase is dropped silently, and that phase keeps only what it still recognises.
+ */
+const LIVE_TRACE_PHASES = {
+    'media-command': (c) => {
+        const topology = allowlistedLabel(c.topology, ['attached', 'own']);
+        const action = allowlistedLabel(c.action, ['keepalive', 'start']);
+        return topology && action && typeof c.level2 === 'boolean' ? { topology, action, level2: c.level2 } : undefined;
+    },
+    'media-command-ack': retainedStart,
+    'media-command-retry': retainedStart,
+    'media-command-unacknowledged': retainedStart,
+    'first-video-command': (c) => {
+        const signCode = boundedInteger(c.signCode, 255);
+        return signCode !== undefined && typeof c.accepted === 'boolean' ? { signCode, accepted: c.accepted } : undefined;
+    },
+    'first-video-unit': (c) => (typeof c.keyframe === 'boolean' ? { keyframe: c.keyframe } : undefined),
+    'first-keyframe': () => ({}),
+    'first-foreign-media-command': (c) => {
+        const media = allowlistedLabel(c.media, ['audio', 'video']);
+        return media ? { media } : undefined;
+    },
+    'video-decode-empty': retainedInteger('signCode', 255),
+    'datagram-gap': retainedInteger('dataType', 3),
+    '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),
+    /**
+     * How long a connection's path has answered nothing, which is the station stating the path is gone.
+     *
+     * A duration, so it is retained as a bounded tally. Its bound is the warm-up window a start is given: a
+     * silence longer than that belongs to a session nothing is waiting on.
+     */
+    'path-stale': retainedInteger('silentMs', MAX_STARTUP_WINDOW_MS),
+    'media-command-unsent': (c) => {
+        const reason = allowlistedLabel(c.reason, ['level2-key', 'address']);
+        return reason ? { reason } : undefined;
+    },
+    warming: (c) => {
+        const retryMs = boundedInteger(c.retryMs, MAX_STARTUP_WINDOW_MS);
+        const deadlineMs = boundedInteger(c.deadlineMs, MAX_STARTUP_WINDOW_MS);
+        return retryMs === undefined || deadlineMs === undefined ? undefined : { retryMs, deadlineMs };
+    },
+};
+function sanitizeSdkLiveStartTrace(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const candidate = value;
+    const phase = String(candidate.phase);
+    if (!Object.hasOwn(LIVE_TRACE_PHASES, phase))
+        return undefined;
+    const fields = LIVE_TRACE_PHASES[phase](candidate);
+    if (!fields)
+        return undefined;
+    const source = opaquePullHandle(candidate.source);
+    return { phase, ...(source === undefined ? {} : { source }), ...fields };
+}
+/**
+ * The SDK's per-process handle for a pull, or nothing where the value is not one.
+ *
+ * Matched against the shape a handle has rather than searched for what a serial looks like: this record is
+ * what a support archive keeps, and a redaction that depends on recognising a secret fails on the first
+ * message shape nobody predicted. `pull-3` and `station-1:2` pass; anything else, a serial included, does not.
+ */
+function opaquePullHandle(value) {
+    return typeof value === 'string' && /^(?:pull|station)-\d{1,6}(?::\d{1,3})?$/.test(value) ? value : undefined;
+}
+/**
+ * Adapts SDK protocol detail to bounded debug output without preserving supplied values.
+ *
+ * The SDK runs FFmpeg of its own for snapshot decoding and WebRTC containers and forwards that process's
+ * stderr under an `[ffmpeg]` prefix. That is the same class of evidence as this plugin's own adaptation
+ * output, so it is recorded as such, redacted line by line, rather than dropped as SDK chatter: a snapshot
+ * that never decodes has no other account anywhere of why.
+ *
+ * Any other message is recorded only when {@link classifySdkEvent} names a class for it, because the class is
+ * all a record carries.
+ */
+export function createSdkLogger(target) {
+    if (!target?.debug) {
+        return undefined;
+    }
+    const format = (message, args) => {
+        if (message === LIVE_TRACE_MESSAGE) {
+            const trace = sanitizeSdkLiveStartTrace(args[0]);
+            if (trace)
+                return { scope: 'sdk', subsystem: 'p2p', event: 'live-start-trace', ...trace };
+        }
+        const requestedSubsystem = /^\[([a-z0-9-]+)(?:\s+[^\]]+)?\]/i.exec(message)?.[1]?.toLowerCase();
+        if (requestedSubsystem === 'ffmpeg') {
+            const stderr = message.slice(message.indexOf(']') + 1).split(/\r?\n/);
+            return sanitizeAdaptationNotice({ role: 'sdk', event: 'output', stderr }, 'debug');
+        }
+        const event = classifySdkEvent(message);
+        if (!event)
+            return undefined;
+        const subsystemAliases = {
+            eufy: 'mega',
+            fcm: 'push',
+            live: 'p2p',
+            session: 'p2p',
+            smqtt: 'mqtt',
+            'stored-snapshot-cache': 'device',
+        };
+        const aliasedSubsystem = requestedSubsystem ? subsystemAliases[requestedSubsystem] : undefined;
+        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';
+                return { errorType };
+            }
+            if (typeof value === 'string') {
+                return { type: 'string', length: value.length };
+            }
+            if (value && typeof value === 'object') {
+                return { type: 'object' };
+            }
+            return { type: typeof value };
+        });
+        return {
+            scope: 'sdk',
+            subsystem,
+            event,
+            ...(details.length ? { details } : {}),
+            ...(args.length > MAX_SDK_DETAILS ? { detailsTruncated: true } : {}),
+        };
+    };
+    const write = (level, message, args) => {
+        const event = format(message, args);
+        if (event) {
+            target.debug(JSON.stringify({ ...event, level }));
+        }
+    };
+    return {
+        debug: (message, ...args) => write('debug', message, args),
+        info: (message, ...args) => write('info', message, args),
+        warn: (message, ...args) => write('warn', message, args),
+        error: (message, ...args) => write('error', message, args),
+    };
+}
+const RUNTIME_STATES = [
+    'stopped',
+    'acquiring-ownership',
+    'starting',
+    'ready',
+    'degraded',
+    'authentication-required',
+    'owner-conflict',
+    'failed',
+    'stopping',
+];
+const CAPABILITIES = new Set([
+    'arming',
+    'audio',
+    'battery',
+    'camera',
+    'contact',
+    'light',
+    'lock',
+    'siren',
+    'smart_light',
+]);
+const MEMBERS = new Set([
+    'active',
+    'alarm',
+    'batteryAlert',
+    'brightness',
+    'charging',
+    'color',
+    'enabled',
+    'level',
+    'isOn',
+    'live',
+    'microphone',
+    'mode',
+    'nightVision',
+    'open',
+    'power',
+    'recordFragments',
+    'snapshot',
+    'snapshotLive',
+    'snapshotStored',
+    'speaker',
+    'state',
+    'statusLed',
+    'stop',
+    'talkback',
+    'target',
+    'test',
+    'volume',
+]);
+const REASONS = new Set([
+    'adaptation-exited-before-output',
+    'adaptation-exited-while-streaming',
+    'adaptation-failed',
+    'adaptation-spawn-failed',
+    'adapter-missing',
+    'at-capacity',
+    'capability-not-supported',
+    'disabled',
+    'disabled-mid-session',
+    'disabled-no-video',
+    'expired',
+    'hot',
+    'live-at-capacity',
+    'live-decoder-unavailable',
+    'live-failed',
+    'live-no-keyframe',
+    'live-source-failed',
+    'live-unavailable',
+    'live-undecodable-burst',
+    'malformed',
+    'missing',
+    'missing-evidence',
+    'missing-trigger',
+    'no-acquisition',
+    'no-output-within-backstop',
+    'no-primary-purpose-member',
+    'no-retained-image',
+    'not-confirmed',
+    'no-video-within-backstop',
+    'operation-failure',
+    'primary-adapter-unavailable',
+    'recovered',
+    'rtcp-timeout',
+    'sdk-fault',
+    'source-acquisition-timeout',
+    'source-audio-only',
+    'source-error',
+    'source-input-unstable',
+    'source-stopped',
+    'source-unavailable',
+    'stored-download-failed',
+    'stored-failed',
+    'stored-invalid-image',
+    'stored-not-observed',
+    'stored-pending',
+    'stored-unavailable',
+    'timeout',
+    'unsupported',
+    'unsupported-selection',
+    'device-audio-failed',
+]);
+/** Every runtime state, plus the withdrawal a recovered condition reports. */
+const RUNTIME_CONDITION_REASONS = new Set([...RUNTIME_STATES, 'recovered']);
+const MAX_ACCESSORY_ALIASES = 32;
+const HOMEKIT_EVENT_ROUTES = {
+    'battery.status': new Set(['battery-alert', 'battery-level']),
+    'contact.sensor': new Set(['contact-state']),
+    'doorbell.press': new Set(['doorbell-press']),
+    'lock.mechanism': new Set(['lock-state']),
+    'motion.sensor': new Set(['motion-detection']),
+    'arming.security-system': new Set(['arming-mode-changed', 'security-system-alarm']),
+    'smart-light.lightbulb': new Set(['smart-light-state']),
+    'camera.streaming': new Set(['camera-enabled-changed']),
+    'camera.controls': new Set(['camera-enabled-changed']),
+};
+const HOMEKIT_OBSERVATIONS = new Set(['malformed', 'missing', 'valid']);
+/**
+ * What announced a change, for an adapter that follows more than one announcement for the same state.
+ *
+ * Read by both halves of the write path: the reporter builds the record and the file sink rebuilds it. The
+ * field is omitted where an adapter states no announcement and refused where it states one absent from here.
+ */
+const HOMEKIT_ANNOUNCEMENTS = new Set(['write', 'poll']);
+const HOMEKIT_LIVE_VIDEO_OPERATIONS = new Set(['start', 'reconfigure']);
+const HOMEKIT_LIVE_VIDEO_PROFILES = new Set(['baseline', 'main', 'high']);
+const HOMEKIT_LIVE_VIDEO_LEVELS = new Set(['3.1', '3.2', '4.0']);
+/**
+ * The inclusive bounds a controller-selected live geometry and frame rate are retained within.
+ *
+ * Bounds rather than an enumeration, because a controller may select a geometry the advertised matrix does not
+ * offer and the plugin honours it. The ceiling exceeds what the recorded H.264 level codes, so a selection its
+ * own level cannot carry is retained.
+ */
+const MIN_LIVE_VIDEO_DIMENSION = 120;
+const MAX_LIVE_VIDEO_DIMENSION = 4096;
+const MIN_LIVE_VIDEO_FRAME_RATE = 1;
+const MAX_LIVE_VIDEO_FRAME_RATE = 120;
+/**
+ * The datagram size a controller negotiated, bounded to what the field on the wire can carry.
+ *
+ * HomeKit transports the maximum MTU as an unsigned 16-bit integer, so every value a controller can ask for
+ * is inside these bounds and none is refused for being larger than this host would choose. A packet size the
+ * path cannot carry is the observation, not a reason to drop the record carrying it.
+ */
+const MIN_LIVE_VIDEO_MTU = 0;
+const MAX_LIVE_VIDEO_MTU = 65_535;
+/** The two address families HomeKit negotiates a destination in. */
+const HOMEKIT_LIVE_ADDRESS_VERSIONS = new Set(['ipv4', 'ipv6']);
+const HOMEKIT_LIVE_SESSION_STAGES = new Set([
+    'sdk-source-acquisition',
+    'first-source-keyframe',
+    'first-adapted-output',
+    'controller-rtcp',
+]);
+/**
+ * Which adaptation process an FFmpeg record came from.
+ *
+ * A superset of what the media domain can report, because the SDK runs FFmpeg of its own for snapshot
+ * decoding and WebRTC containers and forwards its output here under the same evidence class.
+ */
+const ADAPTATION_ROLES = new Set(['live-video', 'live-audio', 'return-audio', 'recording', 'sdk']);
+/** What that process did. `output` is a process reported for what it wrote rather than for how it ended. */
+const ADAPTATION_EVENTS = new Set([
+    'started',
+    'spawn-failed',
+    'input-failed',
+    'exited-before-output',
+    'exited-while-streaming',
+    'output',
+]);
+/**
+ * Which of those events is a failure, and so the ones a record is levelled `warn` for.
+ *
+ * The others are a stream working: `started` is a process beginning, and `output` is a process reported for
+ * what it wrote on the way to a stop it was asked to make — the exit code of a killed FFmpeg among it. Neither
+ * is something a reader must act on, and levelling the class rather than the record put four warnings in the
+ * log for every session that succeeded.
+ */
+const ADAPTATION_FAILURE_EVENTS = new Set([
+    'spawn-failed',
+    'input-failed',
+    'exited-before-output',
+    'exited-while-streaming',
+]);
+/**
+ * The signals a terminated adaptation is reported under.
+ *
+ * A signal this build cannot name is dropped rather than passed through, because the field is written from
+ * an operating-system string and an allowlist is the only thing that keeps it one.
+ */
+const ADAPTATION_SIGNALS = new Set([
+    'SIGABRT',
+    'SIGBUS',
+    'SIGFPE',
+    'SIGILL',
+    'SIGINT',
+    'SIGKILL',
+    'SIGPIPE',
+    'SIGSEGV',
+    'SIGTERM',
+]);
+/**
+ * How many stderr lines one record keeps.
+ *
+ * A producer bounds its own retention too, and this bound is applied again rather than trusted, because a
+ * record's size is this module's to answer for however many lines it was offered.
+ */
+const MAX_ADAPTATION_STDERR_LINES = 8;
+const MAX_ADAPTATION_STDERR_LINE_LENGTH = 200;
+/**
+ * The media notices this module retains, read by both halves of the path.
+ *
+ * Operational rather than verbose, so each is `plugin-log` evidence that every profile declares.
+ */
+const MEDIA_NOTICES = {
+    'camera-snapshot-cache-invalid': {
+        level: 'warn',
+        messageKey: 'log.snapshotCacheInvalid',
+    },
+};
+const RUNTIME_NOTICES = {
+    'status-publication-failed': {
+        level: 'warn',
+        messageKey: 'log.notice.statusPublicationFailed',
+    },
+    'ownership-release-not-finalized': {
+        level: 'error',
+        messageKey: 'log.notice.ownershipReleaseNotFinalized',
+    },
+    'ownership-release-failed': {
+        level: 'error',
+        messageKey: 'log.notice.ownershipReleaseFailed',
+    },
+    'shutdown-failed': {
+        level: 'error',
+        messageKey: 'log.notice.shutdownFailed',
+    },
+    'shutdown-timeout': {
+        level: 'warn',
+        messageKey: 'log.notice.shutdownTimeout',
+        durationMessageKey: 'log.notice.shutdownTimeoutWithDuration',
+    },
+    'ownership-acquisition-failed': {
+        level: 'error',
+        messageKey: 'log.notice.ownershipAcquisitionFailed',
+    },
+    'ownership-release-incomplete': {
+        level: 'warn',
+        messageKey: 'log.notice.ownershipReleaseIncomplete',
+    },
+    'registry-subscriber-failed': {
+        level: 'warn',
+        messageKey: 'log.notice.registrySubscriberFailed',
+    },
+    'event-subscriber-failed': {
+        level: 'warn',
+        messageKey: 'log.notice.eventSubscriberFailed',
+    },
+    'state-subscriber-failed': {
+        level: 'warn',
+        messageKey: 'log.notice.stateSubscriberFailed',
+    },
+    'channel-serve-failed': {
+        level: 'warn',
+        messageKey: 'log.notice.channelServeFailed',
+    },
+    'diagnostics-authorization-armed': {
+        level: 'info',
+        messageKey: 'log.notice.diagnosticsAuthorizationArmed',
+    },
+    'stand-down-not-rearmed': {
+        level: 'warn',
+        messageKey: 'log.notice.standDownNotRearmed',
+    },
+    'stand-down-account-replaced': {
+        level: 'warn',
+        messageKey: 'log.notice.standDownAccountReplaced',
+    },
+};
+const RUNTIME_CONDITIONS = {
+    degraded: {
+        code: 'runtime-transport-degraded',
+        summaryKey: 'log.runtime.transportDegraded',
+        actionKey: 'log.action.checkNetwork',
+        level: 'warn',
+    },
+    'authentication-required': {
+        code: 'runtime-authentication-required',
+        summaryKey: 'log.runtime.authenticationRequired',
+        actionKey: 'log.action.reauthenticate',
+        level: 'warn',
+    },
+    'owner-conflict': {
+        code: 'runtime-owner-conflict',
+        summaryKey: 'log.runtime.ownerConflict',
+        actionKey: 'log.action.stopOtherOwner',
+        level: 'error',
+    },
+    failed: {
+        code: 'runtime-failed',
+        summaryKey: 'log.runtime.failed',
+        actionKey: 'log.action.reviewRuntime',
+        level: 'error',
+    },
+};
+const HOMEKIT_CONDITIONS = {
+    'recognized-device-not-represented': ['log.homekit.recognizedNotRepresented', 'log.action.openDashboard'],
+    'battery-capability-unavailable': ['log.homekit.batteryCapabilityUnavailable', 'log.action.waitBattery'],
+    'invalid-battery-observation': ['log.homekit.invalidBatteryObservation', 'log.action.waitBatteryObservation'],
+    'battery-temperature-alert': ['log.homekit.batteryTemperatureAlert', 'log.action.allowBatteryCooling'],
+    'contact-capability-unavailable': ['log.homekit.contactCapabilityUnavailable', 'log.action.waitContact'],
+    'invalid-contact-observation': ['log.homekit.invalidContactObservation', 'log.action.waitContactObservation'],
+    'siren-capability-unavailable': ['log.homekit.sirenCapabilityUnavailable', 'log.action.waitSiren'],
+    'invalid-siren-active-observation': ['log.homekit.invalidSirenObservation', 'log.action.waitSirenObservation'],
+    'smart-light-capability-unavailable': ['log.homekit.lightCapabilityUnavailable', 'log.action.waitLight'],
+    'invalid-smart-light-observation': ['log.homekit.invalidLightObservation', 'log.action.waitLightObservation'],
+    'smart-light-operation-failed': ['log.homekit.lightOperationFailed', 'log.action.retryLight'],
+    'smart-light-reconciliation-expired': ['log.homekit.lightReconciliationExpired', 'log.action.checkPhysicalLight'],
+    'arming-capability-unavailable': ['log.homekit.armingCapabilityUnavailable', 'log.action.waitArming'],
+    'unsupported-arming-mode': ['log.homekit.unsupportedArmingMode', 'log.action.selectSupportedArmingMode'],
+    'arming-operation-failed': ['log.homekit.armingOperationFailed', 'log.action.retryArming'],
+    'arming-reconciliation-expired': ['log.homekit.armingReconciliationExpired', 'log.action.checkPhysicalArmingMode'],
+    'lock-capability-unavailable': ['log.homekit.lockCapabilityUnavailable', 'log.action.waitLock'],
+    'lock-operation-failed': ['log.homekit.lockOperationFailed', 'log.action.retryLock'],
+    'lock-reconciliation-expired': ['log.homekit.lockReconciliationExpired', 'log.action.checkPhysicalLock'],
+    'unusable-lock-announcement': ['log.homekit.unusableLockAnnouncement', 'log.action.checkPhysicalLock'],
+    'camera-live-session-failed': ['log.homekit.cameraLiveSessionFailed', 'log.action.retryLiveView'],
+    'camera-live-session-refused': ['log.homekit.cameraLiveSessionRefused', 'log.action.enableCamera'],
+    'camera-media-at-capacity': ['log.homekit.cameraMediaAtCapacity', 'log.action.reduceConcurrentMedia'],
+    'camera-recording-unavailable': ['log.homekit.cameraRecordingUnavailable', 'log.action.checkCameraRecording'],
+    'camera-recording-failed': ['log.homekit.cameraRecordingFailed', 'log.action.retryRecording'],
+    'camera-recording-refused': ['log.homekit.cameraRecordingRefused', 'log.action.enableCamera'],
+    'camera-controls-capability-unavailable': [
+        'log.homekit.cameraControlsCapabilityUnavailable',
+        'log.action.waitCameraControl',
+    ],
+    'camera-control-operation-failed': ['log.homekit.cameraControlOperationFailed', 'log.action.retryCameraControl'],
+    'invalid-camera-control-observation': [
+        'log.homekit.invalidCameraControlObservation',
+        'log.action.checkCameraControl',
+    ],
+    'camera-snapshot-unavailable': ['log.homekit.cameraSnapshotUnavailable', 'log.action.checkCameraSnapshot'],
+    'camera-snapshot-capability-unavailable': [
+        'log.homekit.cameraSnapshotCapabilityUnavailable',
+        'log.action.waitCameraSnapshot',
+    ],
+    'camera-streaming-capability-unavailable': [
+        'log.homekit.cameraStreamingCapabilityUnavailable',
+        'log.action.waitCameraLive',
+    ],
+    'camera-talkback-failed': ['log.homekit.cameraTalkbackFailed', 'log.action.retryTalkback'],
+    'camera-talkback-capability-unavailable': ['log.homekit.cameraTalkbackUnavailable', 'log.action.waitTalkback'],
+};
+function sanitizeStructuredEvent(message) {
+    let value;
+    try {
+        const parsed = JSON.parse(message);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        value = parsed;
+    }
+    catch {
+        return undefined;
+    }
+    const level = allowlistedLabel(value.level, ['debug', 'info', 'warn', 'error']);
+    if (!level || typeof value.scope !== 'string')
+        return undefined;
+    if (value.scope === 'sdk') {
+        if (typeof value.subsystem !== 'string' ||
+            !SDK_SUBSYSTEMS.has(value.subsystem) ||
+            typeof value.event !== 'string' ||
+            !SDK_EVENT_KEYS.has(value.event)) {
+            return undefined;
+        }
+        if (value.event === 'live-start-trace') {
+            if (level !== 'debug')
+                return undefined;
+            const trace = sanitizeSdkLiveStartTrace(value);
+            return trace ? { scope: 'sdk', level, subsystem: 'p2p', event: 'live-start-trace', ...trace } : undefined;
+        }
+        const details = [];
+        for (const detail of Array.isArray(value.details) ? value.details.slice(0, MAX_SDK_DETAILS) : []) {
+            if (!detail || typeof detail !== 'object' || Array.isArray(detail))
+                continue;
+            const candidate = detail;
+            const errorType = allowlistedLabel(candidate.errorType, [
+                'Error',
+                'RangeError',
+                'SessionExpiredError',
+                'TypeError',
+            ]);
+            if (errorType) {
+                details.push({ errorType });
+                continue;
+            }
+            const type = allowlistedLabel(candidate.type, ['boolean', 'number', 'object', 'string', 'undefined']);
+            if (!type)
+                continue;
+            const length = nonNegativeInteger(candidate.length);
+            details.push({ type, ...(length === undefined ? {} : { length }) });
+        }
+        return {
+            scope: 'sdk',
+            level,
+            subsystem: value.subsystem,
+            event: value.event,
+            ...(details.length ? { details } : {}),
+            ...(value.detailsTruncated === true ? { detailsTruncated: true } : {}),
+        };
+    }
+    if (value.scope === 'runtime-notice') {
+        if (typeof value.code !== 'string' || !Object.hasOwn(RUNTIME_NOTICES, value.code))
+            return undefined;
+        const notice = RUNTIME_NOTICES[value.code];
+        const durationMs = nonNegativeInteger(value.durationMs);
+        const messageKey = durationMs !== undefined && 'durationMessageKey' in notice ? notice.durationMessageKey : notice.messageKey;
+        return {
+            scope: 'runtime-notice',
+            level: notice.level,
+            code: value.code,
+            messageKey,
+            ...(durationMs === undefined ? {} : { durationMs }),
+        };
+    }
+    if (value.scope === 'configuration-notice') {
+        if (value.code !== 'discarded-v4-settings-unacknowledged')
+            return undefined;
+        return {
+            scope: 'configuration-notice',
+            level: 'warn',
+            code: value.code,
+            messageKey: 'log.discardedSettings',
+        };
+    }
+    if (value.scope === 'media-notice') {
+        if (typeof value.code !== 'string' || !Object.hasOwn(MEDIA_NOTICES, value.code))
+            return undefined;
+        const notice = MEDIA_NOTICES[value.code];
+        return { scope: 'media-notice', level: notice.level, code: value.code, messageKey: notice.messageKey };
+    }
+    if (value.scope === 'homekit') {
+        if (value.adapter === 'camera.streaming' && value.event === 'live-video-selected') {
+            const selection = sanitizeLiveVideoSelection(value);
+            return selection ? { scope: 'homekit', level: 'debug', ...selection } : undefined;
+        }
+        if (value.adapter === 'camera.streaming' && HOMEKIT_LIVE_REQUEST_EVENTS.has(String(value.event))) {
+            const lifecycle = sanitizeLiveSessionTrace(value);
+            return lifecycle ? { scope: 'homekit', level: 'debug', ...lifecycle } : undefined;
+        }
+        if (typeof value.adapter !== 'string' ||
+            typeof value.event !== 'string' ||
+            !HOMEKIT_EVENT_ROUTES[value.adapter]?.has(value.event) ||
+            typeof value.observation !== 'string' ||
+            !HOMEKIT_OBSERVATIONS.has(value.observation)) {
+            return undefined;
+        }
+        return {
+            scope: 'homekit',
+            level: 'debug',
+            adapter: value.adapter,
+            event: value.event,
+            observation: value.observation,
+            ...(typeof value.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(value.announcedBy)
+                ? { announcedBy: value.announcedBy }
+                : {}),
+        };
+    }
+    if (value.scope === 'runtime') {
+        const event = allowlistedLabel(value.event, ['ready', 'stopped']);
+        if (!event)
+            return undefined;
+        return { scope: 'runtime', level: 'info', event, messageKey: 'log.runtime.state' };
+    }
+    if (value.scope === 'ffmpeg') {
+        return sanitizeAdaptationNotice(value, level);
+    }
+    if (value.scope === 'diagnostic-condition') {
+        const homeKitDefinition = typeof value.code === 'string' && Object.hasOwn(HOMEKIT_CONDITIONS, value.code)
+            ? HOMEKIT_CONDITIONS[value.code]
+            : undefined;
+        const runtimeDefinition = Object.values(RUNTIME_CONDITIONS).find(({ code }) => code === value.code);
+        if (typeof value.code !== 'string' || (!homeKitDefinition && !runtimeDefinition))
+            return undefined;
+        if (typeof value.active !== 'boolean' || typeof value.reason !== 'string')
+            return undefined;
+        if (runtimeDefinition) {
+            if (!RUNTIME_CONDITION_REASONS.has(value.reason))
+                return undefined;
+            if (value.capability !== undefined ||
+                value.member !== undefined ||
+                value.affectedAccessoryCount !== undefined ||
+                value.accessoryAliases !== undefined ||
+                value.aliasesTruncated !== undefined) {
+                return undefined;
+            }
+            return {
+                scope: 'diagnostic-condition',
+                level: value.active ? runtimeDefinition.level : 'info',
+                code: value.code,
+                active: value.active,
+                reason: value.reason,
+                summaryKey: runtimeDefinition.summaryKey,
+                actionKey: runtimeDefinition.actionKey,
+            };
+        }
+        if (!REASONS.has(value.reason))
+            return undefined;
+        const affectedAccessoryCount = nonNegativeInteger(value.affectedAccessoryCount);
+        const accessoryAliases = Array.isArray(value.accessoryAliases)
+            ? value.accessoryAliases
+                .filter((alias) => typeof alias === 'string' && /^accessory-[0-9a-f-]{36}$/.test(alias))
+                .slice(0, MAX_ACCESSORY_ALIASES)
+            : [];
+        return {
+            scope: 'diagnostic-condition',
+            level: value.active ? 'warn' : 'info',
+            code: value.code,
+            active: value.active,
+            reason: value.reason,
+            summaryKey: homeKitDefinition[0],
+            actionKey: homeKitDefinition[1],
+            ...(typeof value.capability === 'string' && CAPABILITIES.has(value.capability)
+                ? { capability: value.capability }
+                : {}),
+            ...(typeof value.member === 'string' && MEMBERS.has(value.member) ? { member: value.member } : {}),
+            ...(affectedAccessoryCount === undefined ? {} : { affectedAccessoryCount }),
+            ...(accessoryAliases.length ? { accessoryAliases } : {}),
+            ...(value.aliasesTruncated === true ? { aliasesTruncated: true } : {}),
+        };
+    }
+    return undefined;
+}
+/** Emits one fixed-shape operational notice selected by its allowlisted runtime code. */
+export function reportRuntimeNotice(target, code, fields = {}) {
+    const notice = RUNTIME_NOTICES[code];
+    const durationMs = fields.durationMs === undefined ? undefined : Math.max(0, Math.trunc(fields.durationMs));
+    const messageKey = durationMs !== undefined && 'durationMessageKey' in notice ? notice.durationMessageKey : notice.messageKey;
+    target[notice.level]?.(`[${code}] ${localize(target, messageKey, { durationMs: durationMs ?? 0 })}`);
+    target.debug?.(JSON.stringify({
+        scope: 'runtime-notice',
+        level: notice.level,
+        code,
+        messageKey,
+        ...(durationMs === undefined ? {} : { durationMs }),
+    }));
+}
+/**
+ * Picks up an authorization the persisted session file confirms, reporting whether it did.
+ *
+ * The file is the authority: the supplied identifier only names which window the caller believes was opened,
+ * and a session the file does not hold as active changes nothing and reports nothing. A confirmed pickup emits
+ * one operational record, which is the evidence that this process began retaining the window's scopes, taken
+ * at the moment it did rather than whenever a later record arrives.
+ */
+export function armDiagnosticsAuthorization(target, storageRoot, supportCaseId, now = Date.now) {
+    if (!isSupportCaseId(supportCaseId) ||
+        activeDiagnosticsSession(storageRoot, now())?.supportCaseId !== supportCaseId) {
+        return false;
+    }
+    reportRuntimeNotice(target, 'diagnostics-authorization-armed');
+    return true;
+}
+/** Emits the startup notice for discarded settings awaiting acknowledgement. */
+export function reportDiscardedV4Settings(target) {
+    const code = 'discarded-v4-settings-unacknowledged';
+    const messageKey = 'log.discardedSettings';
+    target.warn(`[${code}] ${localize(target, messageKey)}`);
+    target.debug?.(JSON.stringify({
+        scope: 'configuration-notice',
+        level: 'warn',
+        code,
+        messageKey,
+    }));
+}
+/** Emits one identity-free warning after an invalid retained camera image is discarded. */
+export function reportInvalidSnapshotCache(target) {
+    const code = 'camera-snapshot-cache-invalid';
+    const { level, messageKey } = MEDIA_NOTICES[code];
+    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) {
+    if (trace.event === 'live-video-selected') {
+        const selection = sanitizeLiveVideoSelection(trace);
+        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);
+        if (target.debug && lifecycle) {
+            target.debug(JSON.stringify({ scope: 'homekit', level: 'debug', ...lifecycle }));
+        }
+        return;
+    }
+    if (!target.debug ||
+        !('observation' in trace) ||
+        !HOMEKIT_EVENT_ROUTES[trace.adapter]?.has(trace.event) ||
+        typeof trace.observation !== 'string' ||
+        !HOMEKIT_OBSERVATIONS.has(trace.observation)) {
+        return;
+    }
+    target.debug(JSON.stringify({
+        scope: 'homekit',
+        level: 'debug',
+        adapter: trace.adapter,
+        event: trace.event,
+        observation: trace.observation,
+        ...(typeof trace.announcedBy === 'string' && HOMEKIT_ANNOUNCEMENTS.has(trace.announcedBy)
+            ? { announcedBy: trace.announcedBy }
+            : {}),
+    }));
+}
+/**
+ * Records one FFmpeg adaptation fact as the `ffmpeg-log` evidence the media support profiles declare.
+ *
+ * Nothing is written to the human console: an adaptation failure already reaches the user as the bounded
+ * HomeKit condition its camera reports, and repeating each process's own exit there would say the same thing
+ * a second time in a vocabulary only a maintainer can read.
+ */
+export function reportAdaptationNotice(target, trace) {
+    if (!target.debug) {
+        return;
+    }
+    const level = ADAPTATION_FAILURE_EVENTS.has(trace.event) ? 'warn' : 'debug';
+    const notice = sanitizeAdaptationNotice({ ...trace, level }, level);
+    if (notice) {
+        target.debug(JSON.stringify(notice));
+    }
+}
+/**
+ * Reduces one FFmpeg stderr line to what a support case may keep, or nothing where nothing is left of it.
+ *
+ * The line is the only place an encoder-level cause is stated outright, and it is also the only place this
+ * plugin's own argument list can be echoed back: the output URL carries base64 SRTP key material, the
+ * controller address sits beside it, and an SDK snapshot filename carries a device serial. Each of those is
+ * replaced by what it is rather than searched for afterwards, because a redaction that depends on
+ * recognising a secret fails on the first message shape nobody predicted.
+ *
+ * The key material is replaced before the path rules run, and not after. Base64 includes `/`, so a path rule
+ * applied first splits a key into sub-runs too short for any length threshold to catch — measured on random
+ * 30-byte keys, roughly one line in twenty then kept an eight-character fragment verbatim. The cost of this
+ * order is that a long path made only of letters and separators is labelled as redacted rather than as a
+ * path, which loses a label and never a secret.
+ */
+function redactAdaptationStderr(line) {
+    const printable = boundedText(line, MAX_ADAPTATION_STDERR_LINE_LENGTH);
+    if (printable === undefined || printable.startsWith('progress=')) {
+        return undefined;
+    }
+    return redactSensitiveText(printable);
+}
+/**
+ * Replaces one run of colon-separated hexadecimal groups with `<address>`, and returns an FFmpeg clock or
+ * timecode unchanged.
+ *
+ * A run carrying a `::`, or three or more groups, is an address, unless it is exactly three or four all-decimal
+ * groups: that is the shape FFmpeg states an elapsed time and an SMPTE timecode in, and no uncompressed address
+ * form is that short, including the six groups that precede an embedded IPv4 quad. Two groups are neither, and
+ * are kept, which leaves a stream index intact.
+ */
+function redactColonSeparatedRun(run) {
+    const groups = run.split(':');
+    if ((groups.length === 3 || groups.length === 4) && groups.every((group) => /^\d{1,4}$/.test(group))) {
+        return run;
+    }
+    return run.includes('::') || groups.length > 2 ? '<address>' : run;
+}
+/**
+ * Removes from one line everything a support case may not keep, leaving the sentence and its numbers.
+ *
+ * One rule set for every line this plugin retains, whether it came from an adaptation's stderr or from the
+ * SDK's own diagnostics, because what counts as a secret does not depend on which process said it — and two
+ * lists would drift until one of them missed a shape.
+ *
+ * Each kind is replaced by what it is rather than searched for afterwards, since a redaction that depends on
+ * recognising a secret fails on the first message shape nobody predicted.
+ *
+ * Key material is replaced BEFORE the path rules, not after. Base64 includes `/`, so a path rule applied
+ * first splits a key into sub-runs too short for any length threshold to catch — measured on random 30-byte
+ * keys, roughly one line in twenty then kept an eight-character fragment verbatim. The cost of this order is
+ * that a long path made only of letters and separators is labelled as redacted rather than as a path, which
+ * loses a label and never a secret.
+ *
+ * The P2P device id is grouped with key material rather than with identifiers: it is an input to the station's
+ * encryption, so it is a credential.
+ */
+function redactSensitiveText(line) {
+    const redacted = line
+        .replace(/[a-z][a-z0-9+.-]*:\/\/\S*/gi, '<url>')
+        .replace(/\[[0-9a-f:]{2,}\]/gi, '<address>')
+        .replace(/\b[A-Z0-9]{7}-[0-9]{6}-[A-Z0-9]{5}\b/g, '<redacted>')
+        .replace(/[A-Za-z0-9+/]{20,}={0,2}/g, '<redacted>')
+        .replace(/[A-Za-z]:\\[^\s]*/g, '<path>')
+        .replace(/(?:\/[\w.@-]+){2,}\/?/g, '<path>')
+        .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<address>')
+        .replace(/\b[0-9a-f]{1,4}(?:(?::{1,2}[0-9a-f]{1,4})+(?:::)?|::)|(?<![\w:])::[0-9a-f]{1,4}(?::[0-9a-f]{1,4})*/gi, redactColonSeparatedRun)
+        .replace(/\bT\d[0-9A-Z]{9,}\b/g, '<serial>')
+        .trim();
+    return redacted === '' ? undefined : redacted;
+}
+/** Narrows one offered FFmpeg record against the adaptation allowlists, dropping it whole where it fails. */
+function sanitizeAdaptationNotice(value, level) {
+    if (typeof value.role !== 'string' || !ADAPTATION_ROLES.has(value.role)) {
+        return undefined;
+    }
+    if (typeof value.event !== 'string' || !ADAPTATION_EVENTS.has(value.event)) {
+        return undefined;
+    }
+    const code = boundedInteger(value.code, 255);
+    const signal = typeof value.signal === 'string' && ADAPTATION_SIGNALS.has(value.signal) ? value.signal : undefined;
+    const stderr = (Array.isArray(value.stderr) ? value.stderr : [])
+        .filter((line) => typeof line === 'string')
+        .map(redactAdaptationStderr)
+        .filter((line) => line !== undefined)
+        .slice(-MAX_ADAPTATION_STDERR_LINES);
+    const sourceFragments = nonNegativeInteger(value.sourceFragments);
+    return {
+        scope: 'ffmpeg',
+        level,
+        role: value.role,
+        event: value.event,
+        ...(code === undefined ? {} : { code }),
+        ...(signal === undefined ? {} : { signal }),
+        ...(sourceFragments === undefined ? {} : { sourceFragments }),
+        ...(stderr.length ? { stderr } : {}),
+    };
+}
+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 };
+    }
+    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 }
+            : 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) }
+            : undefined;
+    }
+    if (value.event !== 'live-session-failed' ||
+        value.outcome !== 'failed' ||
+        typeof value.reason !== 'string' ||
+        !REASONS.has(value.reason) ||
+        typeof value.stage !== 'string' ||
+        !HOMEKIT_LIVE_SESSION_STAGES.has(value.stage)) {
+        return undefined;
+    }
+    return {
+        adapter: value.adapter,
+        event: value.event,
+        outcome: value.outcome,
+        reason: value.reason,
+        stage: value.stage,
+    };
+}
+function sanitizeLiveVideoSelection(value) {
+    const operation = typeof value.operation === 'string' ? value.operation : undefined;
+    const profile = typeof value.profile === 'string' ? value.profile : undefined;
+    const codecLevel = typeof value.levelName === 'string' ? value.levelName : typeof value.level === 'string' ? value.level : undefined;
+    const width = boundedInteger(value.width, MAX_LIVE_VIDEO_DIMENSION, MIN_LIVE_VIDEO_DIMENSION);
+    const height = boundedInteger(value.height, MAX_LIVE_VIDEO_DIMENSION, MIN_LIVE_VIDEO_DIMENSION);
+    const fps = boundedInteger(value.fps, MAX_LIVE_VIDEO_FRAME_RATE, MIN_LIVE_VIDEO_FRAME_RATE);
+    const mtu = boundedInteger(value.mtu, MAX_LIVE_VIDEO_MTU, MIN_LIVE_VIDEO_MTU);
+    const addressVersion = typeof value.addressVersion === 'string' ? value.addressVersion : undefined;
+    if (!operation ||
+        !HOMEKIT_LIVE_VIDEO_OPERATIONS.has(operation) ||
+        !profile ||
+        !HOMEKIT_LIVE_VIDEO_PROFILES.has(profile) ||
+        !codecLevel ||
+        !HOMEKIT_LIVE_VIDEO_LEVELS.has(codecLevel) ||
+        width === undefined ||
+        height === undefined ||
+        fps === undefined ||
+        mtu === undefined ||
+        !addressVersion ||
+        !HOMEKIT_LIVE_ADDRESS_VERSIONS.has(addressVersion)) {
+        return undefined;
+    }
+    return {
+        adapter: 'camera.streaming',
+        event: 'live-video-selected',
+        operation,
+        profile,
+        levelName: codecLevel,
+        width,
+        height,
+        fps,
+        mtu,
+        addressVersion,
+    };
+}
+/** Emits bounded normal-output condition transitions without stable device or account identity. */
+export class DiagnosticConditions {
+    log;
+    nameFor;
+    active = new Map();
+    aliases = new Map();
+    runtimeState;
+    /**
+     * @param nameFor Resolves a device serial to the label the owner sees, for the CONSOLE line only.
+     *   The console line goes to the owner's own log, where Homebridge prints accessory names on every other
+     *   line, and a count is not something an owner can act on. The retained record keeps carrying no identity.
+     *   A device with no accessory has no display name, so a caller resolving one for a condition about an
+     *   unrepresented device supplies its snapshot label instead.
+     */
+    constructor(log, nameFor) {
+        this.log = log;
+        this.nameFor = nameFor;
+    }
+    reportRuntimeState(state) {
+        if (state === this.runtimeState) {
+            return;
+        }
+        this.runtimeState = state;
+        const current = RUNTIME_CONDITIONS[state];
+        for (const condition of Object.values(RUNTIME_CONDITIONS)) {
+            if (condition !== current) {
+                this.write(condition.code, false, state === 'ready' ? 'recovered' : state, condition.summaryKey, condition.actionKey, 'info');
+            }
+        }
+        if (current) {
+            this.write(current.code, true, state, current.summaryKey, current.actionKey, current.level);
+        }
+        else if (state === 'ready' || state === 'stopped') {
+            const messageKey = 'log.runtime.state';
+            this.log.info(`[runtime-${state}] ${localize(this.log, messageKey, { state })}`);
+            this.log.debug?.(JSON.stringify({ scope: 'runtime', level: 'info', event: state, messageKey }));
+        }
+    }
+    /**
+     * Records one HomeKit condition against the accessories it affects.
+     *
+     * The retained record carries aliases and no identity. The owner's own console line carries each name paired
+     * with its alias, which is what makes an alias in a support case resolvable by the owner and by nobody else.
+     */
+    reportHomeKit(condition, affectedDeviceIds) {
+        const definition = Object.hasOwn(HOMEKIT_CONDITIONS, condition.code)
+            ? HOMEKIT_CONDITIONS[condition.code]
+            : undefined;
+        if (definition === undefined ||
+            !REASONS.has(condition.reason) ||
+            (condition.capability !== undefined && !CAPABILITIES.has(condition.capability)) ||
+            (condition.member !== undefined && !MEMBERS.has(condition.member))) {
+            return;
+        }
+        const uniqueDeviceIds = condition.active ? [...new Set(affectedDeviceIds)].sort() : [];
+        const accessoryAliases = uniqueDeviceIds
+            .map((identity) => this.accessoryAlias(identity))
+            .filter((alias) => alias !== undefined)
+            .sort();
+        this.write(condition.code, condition.active, condition.reason, definition[0], definition[1], condition.active ? 'warn' : 'info', {
+            ...(condition.capability === undefined ? {} : { capability: condition.capability }),
+            ...(condition.member === undefined ? {} : { member: condition.member }),
+            affectedAccessoryCount: uniqueDeviceIds.length,
+            ...(accessoryAliases.length === 0 ? {} : { accessoryAliases }),
+            ...(accessoryAliases.length === uniqueDeviceIds.length ? {} : { aliasesTruncated: true }),
+        }, `${condition.code}:${condition.capability ?? ''}:${condition.member ?? ''}`, uniqueDeviceIds
+            .map((serial) => {
+            const name = this.nameFor?.(serial);
+            const alias = this.aliases.get(serial);
+            return name === undefined ? undefined : alias === undefined ? name : `${name} (${alias})`;
+        })
+            .filter((named) => named !== undefined));
+    }
+    accessoryAlias(identity) {
+        let alias = this.aliases.get(identity);
+        if (!alias && this.aliases.size < MAX_ACCESSORY_ALIASES) {
+            alias = `accessory-${randomUUID()}`;
+            this.aliases.set(identity, alias);
+        }
+        return alias;
+    }
+    write(code, active, reason, summaryKey, actionKey, level, fields = {}, conditionKey = code, 
+    /** Accessory names for the console line only — never retained, see {@link DiagnosticConditions}. */
+    names) {
+        const fingerprint = JSON.stringify({ active, reason, ...fields });
+        if (active) {
+            if (this.active.get(conditionKey) === fingerprint) {
+                return;
+            }
+            this.active.set(conditionKey, fingerprint);
+        }
+        else if (!this.active.delete(conditionKey)) {
+            return;
+        }
+        const affectedAccessoryCount = typeof fields.affectedAccessoryCount === 'number' ? fields.affectedAccessoryCount : undefined;
+        const summary = localize(this.log, summaryKey);
+        const action = localize(this.log, actionKey);
+        const affected = names?.length
+            ? localize(this.log, 'log.condition.affectedNamed', { names: names.join(', ') })
+            : affectedAccessoryCount
+                ? localize(this.log, affectedAccessoryCount === 1 ? 'log.condition.affectedOne' : 'log.condition.affectedMany', { count: affectedAccessoryCount })
+                : '';
+        const message = localize(this.log, active ? 'log.condition.active' : 'log.condition.recovered', {
+            action,
+            affected,
+            summary,
+        });
+        this.log[level](`[${code}] ${message}`);
+        this.log.debug?.(JSON.stringify({
+            scope: 'diagnostic-condition',
+            level,
+            code,
+            active,
+            reason,
+            summaryKey,
+            actionKey,
+            ...fields,
+        }));
+    }
+}
+//# sourceMappingURL=diagnostics.js.map