@mega-yfue/eufy-sdk 0.4.0-beta.15 → 0.4.0-beta.17

package/dist/index.js

@@ -1147,6 +1147,14 @@ var DeviceChannelUnresolvedError = class extends Error {
     this.name = "DeviceChannelUnresolvedError";
   }
 };
+var RecordingDownloadError = class extends Error {
+  reason;
+  constructor(reason, message, options) {
+    super(message, options);
+    this.reason = reason;
+    this.name = "RecordingDownloadError";
+  }
+};
 var LiveStreamStartError = class extends Error {
   reason;
   stage;
@@ -5702,6 +5710,7 @@ var CAMERA_MEMBERS = {
     refuseWhenDisabled(ctx, read);
     return m.recordFragments({ powered: poweredOf(ctx), ...opts });
   }), "Continuous fragmented-MP4 (CMAF) recording."),
+  downloadRecording: provided("media", (m) => m.downloadRecording && ((opts) => m.downloadRecording(opts)), "Download a recording the station holds \u2192 H.264 and AAC elementary streams."),
   /**
    * Push audio from the host to this camera's speaker. Gated on the **speaker** param specifically —
    * not the `audio` capability, which resolves on a microphone alone and would advertise a speaker the
@@ -14342,6 +14351,7 @@ __export(codec_exports, {
   buildLookupWithKeyPayload2: () => buildLookupWithKeyPayload2,
   buildRawCommandPayload: () => buildRawCommandPayload,
   buildStringCommandPayload: () => buildStringCommandPayload,
+  buildStringPairCommandPayload: () => buildStringPairCommandPayload,
   buildVoidCommandPayload: () => buildVoidCommandPayload,
   decodeP2PCloudIPs: () => decodeP2PCloudIPs,
   decryptP2PData: () => decryptP2PData,
@@ -14594,6 +14604,12 @@ function buildIntStringCommandPayload(value, valueSub, strValue, channel = 0, ke
     data
   ]);
 }
+function buildStringPairCommandPayload(strValue, strValueSub, channel = 0, key, encType = 1) {
+  const encrypted = !!key && key.length === 16;
+  const body = Buffer.concat([Buffer.alloc(5), stringWithLength(strValue), stringWithLength(strValueSub)]);
+  const data = encrypted ? encryptP2PData(paddingP2PData(body), key) : body;
+  return buildRawCommandPayload(data, channel, encrypted ? encType : 0);
+}
 function buildRawCommandPayload(data, channel = 0, signCode = 0, magic = [1, 0], streamId = 0) {
   const header = Buffer.allocUnsafe(2);
   header.writeUInt16LE(data.length, 0);
@@ -15250,6 +15266,49 @@ function paramReport(payload) {
   return Object.keys(out).length ? out : void 0;
 }
 var traceSequence = 0;
+var DB_TABLE_TIMEOUT_MS = 15e3;
+function firstTableRows(text2) {
+  const decoded = Buffer.from(text2, "latin1").toString("utf8");
+  for (let start = decoded.indexOf("{"); start >= 0; start = decoded.indexOf("{", start + 1)) {
+    const end = closingBrace(decoded, start);
+    if (end < 0)
+      return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(decoded.slice(start, end + 1));
+    } catch {
+      continue;
+    }
+    const data = parsed?.data;
+    if (Array.isArray(data))
+      return data;
+  }
+  return void 0;
+}
+function closingBrace(text2, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text2.length; i++) {
+    const c = text2[i];
+    if (inString) {
+      if (escaped)
+        escaped = false;
+      else if (c === "\\")
+        escaped = true;
+      else if (c === '"')
+        inString = false;
+      continue;
+    }
+    if (c === '"')
+      inString = true;
+    else if (c === "{")
+      depth++;
+    else if (c === "}" && --depth === 0)
+      return i;
+  }
+  return -1;
+}
 var P2PSession = class _P2PSession extends EventEmitter2 {
   cfg;
   socket;
@@ -16066,6 +16125,17 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
     this.seqNumber = this.seqNumber + 1 & 65535;
     this.send(this.connectAddress, RequestMessageType.DATA, data);
   }
+  /** Send a level-1 {@link buildStringPairCommandPayload} command on `channel`. */
+  sendStringPairCommand(commandType, strValue, strValueSub, channel) {
+    if (!this.connectAddress)
+      throw new Error(`P2P session ${this.cfg.stationSn} is not connected`);
+    const data = Buffer.concat([
+      buildCommandHeader(this.seqNumber, commandType),
+      buildStringPairCommandPayload(strValue, strValueSub, channel, this.level1Key, 1)
+    ]);
+    this.seqNumber = this.seqNumber + 1 & 65535;
+    this.send(this.connectAddress, RequestMessageType.DATA, data);
+  }
   /**
    * Send a **level-2 (AES-256-GCM, signCode 8) control payload** to a HomeBase-attached device. The
    * target camera is selected by `channel` (= device_channel) + the `mChannel` envelope — the same
@@ -16468,8 +16538,14 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * The HomeBase streams back `CMD_DATABASE` (1306) frames `{cmd:10000,count,data:[…]}`,
    * level-1-encrypted — decoded and emitted as `dbChunk` (decrypted text) per frame.
    * Tables: `familiar_faces`, `person_basic_info`, `event_person_list`, `history_record_info`.
+   *
+   * Throws while a {@link readDatabase} is accumulating: every table answers `{data:[…]}` and the
+   * frames tie no chunk to its request, so a second query's reply would be assembled into the first
+   * one's buffer and answered as its rows.
    */
   queryDatabase(table, opts = {}) {
+    if (this.dbReadInFlight)
+      throw new Error(`queryDatabase: ${this.cfg.stationSn} is already reading a table`);
     if (!this.connectAddress)
       throw new Error("not connected");
     const channel = opts.channel ?? STATION_CHANNEL3;
@@ -16532,6 +16608,49 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
       query: this.fullTableQuery()
     });
   }
+  /**
+   * Query one on-station table and answer its rows, once the reply is whole.
+   *
+   * The request half of {@link queryDatabase} with its reply assembled: `CMD_DATABASE` arrives as
+   * several frames whose decrypted text is a fragment of one document, so the fragments are
+   * accumulated here and scanned after each one. Answers that document's `data` rows. Rejects when
+   * `signal` aborts, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no
+   * complete reply.
+   *
+   * One read at a time per session: while one is accumulating, every {@link queryDatabase} on the
+   * session throws, so a second reply cannot land in this buffer.
+   */
+  async readDatabase(table, opts = {}) {
+    if (opts.signal?.aborted)
+      throw new Error("readDatabase: aborted");
+    this.queryDatabase(table, { accountId: opts.accountId, query: this.fullTableQuery() });
+    this.dbReadInFlight = true;
+    try {
+      return await new Promise((resolve, reject) => {
+        let text2 = "";
+        const onChunk = (chunk) => {
+          text2 += chunk.text;
+          const rows = firstTableRows(text2);
+          if (rows)
+            settle(() => resolve(rows));
+        };
+        const timer = setTimeout(() => settle(() => reject(new Error(`readDatabase: ${this.cfg.stationSn} sent no complete ${table}`))), opts.timeoutMs ?? DB_TABLE_TIMEOUT_MS);
+        const onAbort = () => settle(() => reject(new Error("readDatabase: aborted")));
+        const settle = (finish) => {
+          clearTimeout(timer);
+          this.off("dbChunk", onChunk);
+          opts.signal?.removeEventListener("abort", onAbort);
+          finish();
+        };
+        this.on("dbChunk", onChunk);
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    } finally {
+      this.dbReadInFlight = false;
+    }
+  }
+  /** Whether a {@link readDatabase} is accumulating; see {@link queryDatabase} for what it bars. */
+  dbReadInFlight = false;
   /**
    * Request the **face feature rows** over P2P (`face_feature_info`, inner `cmd 10000`). Each row
    * carries `{person_id, face_name, face_id, face_picture_content, face_feature_file_path}` — where
@@ -18244,6 +18363,282 @@ function annexbToJpeg(annexb, spawn2) {
   });
 }
 
+// dist/transport/p2p/recording-download.js
+import { createDecipheriv as createDecipheriv7 } from "node:crypto";
+
+// dist/transport/p2p/adts.js
+var PROFILE_AAC_LC = 1;
+var FREQ_INDEX_16K = 8;
+var CHANNELS_MONO = 1;
+var AAC_SAMPLES_PER_FRAME = 1024;
+var AAC_SAMPLE_RATE = 16e3;
+var AAC_FRAME_MS = AAC_SAMPLES_PER_FRAME * 1e3 / AAC_SAMPLE_RATE;
+var MAX_AUDIO_FRAME_BYTES = 640;
+var HEADER_LEN_NO_CRC = 7;
+function parseAdtsHeader(buf, offset = 0) {
+  if (offset + HEADER_LEN_NO_CRC > buf.length)
+    return void 0;
+  if (buf[offset] !== 255 || (buf[offset + 1] & 240) !== 240)
+    return void 0;
+  const headerLength = buf[offset + 1] & 1 ? 7 : 9;
+  const frameLength = (buf[offset + 3] & 3) << 11 | buf[offset + 4] << 3 | (buf[offset + 5] & 224) >> 5;
+  if (frameLength < headerLength)
+    return void 0;
+  return {
+    frameLength,
+    headerLength,
+    profile: (buf[offset + 2] & 192) >> 6,
+    frequencyIndex: (buf[offset + 2] & 60) >> 2,
+    channels: (buf[offset + 2] & 1) << 2 | (buf[offset + 3] & 192) >> 6
+  };
+}
+function buildAdtsHeader(payloadLength) {
+  const frameLength = payloadLength + HEADER_LEN_NO_CRC;
+  return Buffer.from([
+    255,
+    241,
+    PROFILE_AAC_LC << 6 | FREQ_INDEX_16K << 2 | CHANNELS_MONO >> 2,
+    (CHANNELS_MONO & 3) << 6 | frameLength >> 11 & 3,
+    frameLength >> 3 & 255,
+    (frameLength & 7) << 5 | 31,
+    252
+  ]);
+}
+function isSupportedAdts(h) {
+  return h.profile === PROFILE_AAC_LC && h.frequencyIndex === FREQ_INDEX_16K && h.channels === CHANNELS_MONO;
+}
+function describeAdts(h) {
+  const rate = ADTS_SAMPLE_RATES[h.frequencyIndex] ?? `index ${h.frequencyIndex}`;
+  const profile = h.profile === PROFILE_AAC_LC ? "AAC-LC" : `profile field ${h.profile}`;
+  return `${profile}, ${rate} Hz, ${h.channels} channel(s)`;
+}
+var ADTS_SAMPLE_RATES = [
+  96e3,
+  88200,
+  64e3,
+  48e3,
+  44100,
+  32e3,
+  24e3,
+  22050,
+  16e3,
+  12e3,
+  11025,
+  8e3,
+  7350
+];
+var AdtsFrameReader = class {
+  buffered = Buffer.alloc(0);
+  /**
+   * Append `chunk` and return every complete frame now available, each a standalone buffer that still
+   * carries its own ADTS header (the device expects the header on the wire).
+   */
+  push(chunk) {
+    this.buffered = this.buffered.length ? Buffer.concat([this.buffered, chunk]) : chunk;
+    const frames = [];
+    let at = 0;
+    for (; ; ) {
+      const h = parseAdtsHeader(this.buffered, at);
+      if (!h) {
+        if (at + HEADER_LEN_NO_CRC > this.buffered.length)
+          break;
+        at++;
+        continue;
+      }
+      if (at + h.frameLength > this.buffered.length)
+        break;
+      frames.push(this.buffered.subarray(at, at + h.frameLength));
+      at += h.frameLength;
+    }
+    this.buffered = at ? this.buffered.subarray(at) : this.buffered;
+    return frames;
+  }
+  /** Bytes held back awaiting the rest of their frame — non-zero mid-stream, zero on a clean boundary. */
+  get pending() {
+    return this.buffered.length;
+  }
+};
+
+// dist/transport/p2p/recording-download.js
+var RECORDING_DATA_TYPE = 3;
+var VIDEO_HEADER_LEN2 = 22;
+var AUDIO_HEADER_LEN2 = 16;
+var AUDIO_NONCE_START = 32;
+var AUDIO_BODY_START = 44;
+var AUDIO_CODEC_AAC_LC = 0;
+var FIRST_FRAME_WAIT_MS = 2e4;
+var IDLE_END_MS = 15e3;
+var DEFAULT_TRANSFER_MS = 12e4;
+var MAX_TRANSFER_BYTES = 32 * 1024 * 1024;
+function homeBase2RecordingPath(channel, recording) {
+  if (!/^\d{14}$/.test(recording) || !Number.isInteger(channel) || channel < 0 || channel > 99)
+    return void 0;
+  return `/media/mmcblk0p1/Camera${String(channel).padStart(2, "0")}/${recording}.dat`;
+}
+function receiveRecording(session, request) {
+  let resolveFrames;
+  let rejectFrames;
+  const frames = new Promise((resolve, reject) => {
+    resolveFrames = resolve;
+    rejectFrames = reject;
+  });
+  let resolveDrained;
+  const drained = new Promise((resolve) => resolveDrained = resolve);
+  const limitMs = request.timeoutMs ?? DEFAULT_TRANSFER_MS;
+  let collected = [];
+  const started = Date.now();
+  let lastFrameAt = started;
+  let received = false;
+  let bytes2 = 0;
+  let draining;
+  let delivered = false;
+  let listening = true;
+  const deliver = (error) => {
+    if (delivered)
+      return;
+    delivered = true;
+    request.signal?.removeEventListener("abort", onAbort);
+    if (error)
+      rejectFrames(error);
+    else
+      resolveFrames(collected);
+  };
+  const stop = () => {
+    if (!listening)
+      return;
+    listening = false;
+    clearInterval(tick);
+    session.off("data", onData);
+    resolveDrained();
+  };
+  const incomplete = (why) => deliver(new RecordingDownloadError("incomplete", `the recording transfer ${why} before its finish frame`));
+  const drain = (why) => {
+    draining ??= why;
+    collected = [];
+  };
+  const onData = (frame) => {
+    if (frame.channel !== request.channel)
+      return;
+    if (frame.commandId === CommandType.CMD_DOWNLOAD_FINISH) {
+      if (draining)
+        incomplete(draining);
+      else
+        deliver();
+      return stop();
+    }
+    if (frame.commandId !== CommandType.CMD_VIDEO_FRAME && frame.commandId !== CommandType.CMD_AUDIO_FRAME)
+      return;
+    if (frame.dataType !== RECORDING_DATA_TYPE)
+      return;
+    received = true;
+    lastFrameAt = Date.now();
+    if (draining)
+      return;
+    collected.push({ commandId: frame.commandId, signCode: frame.signCode, raw: Buffer.from(frame.raw) });
+    bytes2 += frame.raw.length;
+    if (bytes2 >= MAX_TRANSFER_BYTES)
+      drain(`reached ${MAX_TRANSFER_BYTES} bytes`);
+  };
+  const onAbort = () => {
+    deliver(request.signal?.reason instanceof Error ? request.signal.reason : new Error("aborted"));
+    drain("was aborted");
+  };
+  const tick = setInterval(() => {
+    const now2 = Date.now();
+    if (!received && now2 - started > FIRST_FRAME_WAIT_MS) {
+      deliver(new RecordingDownloadError("no-data", `the station sent nothing within ${FIRST_FRAME_WAIT_MS} ms`));
+      stop();
+    } else if (received && now2 - lastFrameAt > IDLE_END_MS) {
+      incomplete(draining ?? `went quiet for ${IDLE_END_MS} ms`);
+      stop();
+    } else if (now2 - started > 2 * limitMs && draining) {
+      incomplete(draining);
+      stop();
+    } else if (now2 - started > limitMs) {
+      drain(`ran past ${limitMs} ms`);
+    }
+  }, 250);
+  if (request.signal?.aborted) {
+    onAbort();
+    stop();
+    return { frames, drained };
+  }
+  request.signal?.addEventListener("abort", onAbort, { once: true });
+  session.on("data", onData);
+  try {
+    session.sendStringPairCommand(CommandType.CMD_DOWNLOAD_VIDEO, request.path, request.accountId, request.channel);
+  } catch (error) {
+    deliver(error instanceof Error ? error : new Error(String(error)));
+    stop();
+  }
+  return { frames, drained };
+}
+function openAudio(key, nonce, tag2, body) {
+  try {
+    const decipher = createDecipheriv7("aes-256-gcm", key, nonce);
+    decipher.setAAD(VIDEO_GCM_AAD);
+    decipher.setAuthTag(tag2);
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+  } catch {
+    return void 0;
+  }
+}
+function decodeRecording(frames, eccPrivateKeyHex) {
+  const eccPrivateKey = Buffer.from(eccPrivateKeyHex, "hex");
+  if (eccPrivateKey.length !== 32)
+    throw new RecordingDownloadError("undecodable", "the cipher key is not a P-256 key");
+  const decoder = new VideoFrameDecoder(eccPrivateKey);
+  const video = [];
+  const audio = [];
+  const numbers = /* @__PURE__ */ new Set();
+  let firstStamp;
+  let lastStamp;
+  for (const { commandId, raw } of frames) {
+    if (commandId === CommandType.CMD_VIDEO_FRAME) {
+      const header = parseVideoFrameHeader(raw);
+      if (!header)
+        continue;
+      const h264 = header.keyframe ? decoder.decodeFrame(raw)?.h264 : raw.length >= VIDEO_HEADER_LEN2 + header.payloadLength ? raw.subarray(VIDEO_HEADER_LEN2, VIDEO_HEADER_LEN2 + header.payloadLength) : void 0;
+      if (!h264?.length)
+        continue;
+      video.push(h264);
+      numbers.add(header.sequence);
+      const stamp = raw.readUIntLE(14, 6);
+      firstStamp ??= stamp;
+      lastStamp = stamp;
+    } else if (commandId === CommandType.CMD_AUDIO_FRAME) {
+      const mediaKey = decoder.currentMediaKey;
+      if (!mediaKey || raw.length < AUDIO_BODY_START || raw[5] !== AUDIO_CODEC_AAC_LC)
+        continue;
+      const len = raw.readUInt32LE(0);
+      if (raw.length < AUDIO_BODY_START + len)
+        continue;
+      const aac = openAudio(mediaKey, raw.subarray(AUDIO_NONCE_START, AUDIO_BODY_START), raw.subarray(AUDIO_HEADER_LEN2, AUDIO_NONCE_START), raw.subarray(AUDIO_BODY_START, AUDIO_BODY_START + len));
+      if (aac?.length)
+        audio.push(buildAdtsHeader(aac.length), aac);
+    }
+  }
+  if (!video.length)
+    throw new RecordingDownloadError("undecodable", "no video frame of the recording decoded");
+  const ordered = [...numbers];
+  let missingFrames = 0;
+  for (let i = 1; i < ordered.length; i++) {
+    const step = ordered[i] - ordered[i - 1] & 65535;
+    if (step > 1 && step < 32768)
+      missingFrames += step - 1;
+  }
+  const span = ordered.length > 1 ? ordered[ordered.length - 1] - ordered[0] & 65535 : 0;
+  const durationMs = (lastStamp ?? 0) - (firstStamp ?? 0);
+  return {
+    video: Buffer.concat(video),
+    ...audio.length ? { audio: Buffer.concat(audio) } : {},
+    frames: ordered.length,
+    missingFrames,
+    durationMs,
+    fps: durationMs > 0 && span > 0 ? Math.round(span * 1e5 / durationMs) / 100 : 0
+  };
+}
+
 // dist/transport/p2p/shared-live-source.js
 import { EventEmitter as EventEmitter4 } from "node:events";
 var MAX_TIMER_DELAY_MS = 2147483647;
@@ -19366,89 +19761,6 @@ function openReadableFromConsumer(consumer, opts = {}) {
 // dist/transport/p2p/talkback.js
 import { EventEmitter as EventEmitter5 } from "node:events";
 import { Writable } from "node:stream";
-
-// dist/transport/p2p/adts.js
-var PROFILE_AAC_LC = 1;
-var FREQ_INDEX_16K = 8;
-var CHANNELS_MONO = 1;
-var AAC_SAMPLES_PER_FRAME = 1024;
-var AAC_SAMPLE_RATE = 16e3;
-var AAC_FRAME_MS = AAC_SAMPLES_PER_FRAME * 1e3 / AAC_SAMPLE_RATE;
-var MAX_AUDIO_FRAME_BYTES = 640;
-var HEADER_LEN_NO_CRC = 7;
-function parseAdtsHeader(buf, offset = 0) {
-  if (offset + HEADER_LEN_NO_CRC > buf.length)
-    return void 0;
-  if (buf[offset] !== 255 || (buf[offset + 1] & 240) !== 240)
-    return void 0;
-  const headerLength = buf[offset + 1] & 1 ? 7 : 9;
-  const frameLength = (buf[offset + 3] & 3) << 11 | buf[offset + 4] << 3 | (buf[offset + 5] & 224) >> 5;
-  if (frameLength < headerLength)
-    return void 0;
-  return {
-    frameLength,
-    headerLength,
-    profile: (buf[offset + 2] & 192) >> 6,
-    frequencyIndex: (buf[offset + 2] & 60) >> 2,
-    channels: (buf[offset + 2] & 1) << 2 | (buf[offset + 3] & 192) >> 6
-  };
-}
-function isSupportedAdts(h) {
-  return h.profile === PROFILE_AAC_LC && h.frequencyIndex === FREQ_INDEX_16K && h.channels === CHANNELS_MONO;
-}
-function describeAdts(h) {
-  const rate = ADTS_SAMPLE_RATES[h.frequencyIndex] ?? `index ${h.frequencyIndex}`;
-  const profile = h.profile === PROFILE_AAC_LC ? "AAC-LC" : `profile field ${h.profile}`;
-  return `${profile}, ${rate} Hz, ${h.channels} channel(s)`;
-}
-var ADTS_SAMPLE_RATES = [
-  96e3,
-  88200,
-  64e3,
-  48e3,
-  44100,
-  32e3,
-  24e3,
-  22050,
-  16e3,
-  12e3,
-  11025,
-  8e3,
-  7350
-];
-var AdtsFrameReader = class {
-  buffered = Buffer.alloc(0);
-  /**
-   * Append `chunk` and return every complete frame now available, each a standalone buffer that still
-   * carries its own ADTS header (the device expects the header on the wire).
-   */
-  push(chunk) {
-    this.buffered = this.buffered.length ? Buffer.concat([this.buffered, chunk]) : chunk;
-    const frames = [];
-    let at = 0;
-    for (; ; ) {
-      const h = parseAdtsHeader(this.buffered, at);
-      if (!h) {
-        if (at + HEADER_LEN_NO_CRC > this.buffered.length)
-          break;
-        at++;
-        continue;
-      }
-      if (at + h.frameLength > this.buffered.length)
-        break;
-      frames.push(this.buffered.subarray(at, at + h.frameLength));
-      at += h.frameLength;
-    }
-    this.buffered = at ? this.buffered.subarray(at) : this.buffered;
-    return frames;
-  }
-  /** Bytes held back awaiting the rest of their frame — non-zero mid-stream, zero on a clean boundary. */
-  get pending() {
-    return this.buffered.length;
-  }
-};
-
-// dist/transport/p2p/talkback.js
 var DEFAULT_HIGH_WATER_FRAMES = Math.ceil(2e3 / AAC_FRAME_MS);
 var DEFAULT_IDLE_TIMEOUT_MS = 3e4;
 var Talkback = class extends EventEmitter5 {
@@ -20424,6 +20736,8 @@ var P2PCommandRouter = class _P2PCommandRouter {
   talkbacks = /* @__PURE__ */ new Map();
   /** cipher_id → ECC private key (one eufylife get_ciphers call per cipher), shared across (re)opens. */
   cipherKeyCache = /* @__PURE__ */ new Map();
+  /** The recording download in flight per station; a station serves one at a time. */
+  recordingDownloads = /* @__PURE__ */ new Map();
   constructor(deps) {
     this.deps = deps;
     this.manager = new SessionManager({
@@ -20636,28 +20950,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
       localAddress,
       dskKey,
       noBroadcast: this.deps.noBroadcast,
-      resolveCipherKey: async (cipherId) => {
-        if (this.cipherKeyCache.has(cipherId))
-          return this.cipherKeyCache.get(cipherId);
-        let ecc;
-        try {
-          const ciphers = await this.deps.mega.getCiphers([cipherId], adminUserId, stationSn);
-          ecc = ciphers.find((c) => Number(c.cipher_id) === cipherId)?.ecc_private_key;
-          if (ecc === void 0 && ciphers[0]?.ecc_private_key !== void 0) {
-            ecc = ciphers[0].ecc_private_key;
-            this.traceOnStation(session, {
-              phase: "cipher-fallback",
-              cipherId,
-              answeredCipherId: Number(ciphers[0].cipher_id)
-            });
-          }
-        } catch (e) {
-          this.deps.onError(e instanceof Error ? e : new Error(String(e)));
-        }
-        if (ecc !== void 0)
-          this.cipherKeyCache.set(cipherId, ecc);
-        return ecc;
-      },
+      resolveCipherKey: (cipherId) => this.cipherKeyFor(session, cipherId, adminUserId, stationSn),
       logger: this.deps.logger ?? noopLogger
     });
     session.on("error", (e) => this.reportError(e));
@@ -20681,6 +20974,33 @@ var P2PCommandRouter = class _P2PCommandRouter {
     session.on("data", (f) => this.deps.onFrame(stationSn, f));
     return session;
   }
+  /**
+   * The ECC private key of `cipherId`, from the router's cache or one `get_ciphers` call. When the cloud
+   * answers with another cipher, that one is used and traced on `session`. Only a successful lookup is
+   * cached.
+   */
+  async cipherKeyFor(session, cipherId, userId, stationSn) {
+    if (this.cipherKeyCache.has(cipherId))
+      return this.cipherKeyCache.get(cipherId);
+    let ecc;
+    try {
+      const ciphers = await this.deps.mega.getCiphers([cipherId], userId, stationSn);
+      ecc = ciphers.find((c) => Number(c.cipher_id) === cipherId)?.ecc_private_key;
+      if (ecc === void 0 && ciphers[0]?.ecc_private_key !== void 0) {
+        ecc = ciphers[0].ecc_private_key;
+        this.traceOnStation(session, {
+          phase: "cipher-fallback",
+          cipherId,
+          answeredCipherId: Number(ciphers[0].cipher_id)
+        });
+      }
+    } catch (e) {
+      this.deps.onError(e instanceof Error ? e : new Error(String(e)));
+    }
+    if (ecc !== void 0)
+      this.cipherKeyCache.set(cipherId, ecc);
+    return ecc;
+  }
   /**
    * Open (or reuse) a station's P2P session and await its completed handshake. An optional abort only
    * stops this wait; session ownership remains with {@link SessionManager} and its normal teardown.
@@ -20808,7 +21128,9 @@ var P2PCommandRouter = class _P2PCommandRouter {
    * start has no level-1 form for.
    */
   mediaProviderFor(sn) {
+    const recordings = this.downloadsRecordings(sn) ? { downloadRecording: (opts) => this.downloadRecording(sn, opts) } : {};
     return {
+      ...recordings,
       snapshotLive: async (opts) => {
         const source = await this.sharedLiveSourceFor(sn, opts ?? {});
         return captureSnapshotFromShared(source, {
@@ -20847,6 +21169,63 @@ var P2PCommandRouter = class _P2PCommandRouter {
       }
     };
   }
+  /**
+   * Whether `sn` is a camera attached to a HomeBase 2 (T8010), the one station whose recording path layout
+   * and frame formats are confirmed.
+   */
+  downloadsRecordings(sn) {
+    const dev = this.recordFor(sn);
+    if (!dev)
+      return false;
+    const parentSn = stationOf(dev);
+    return parentSn !== sn && this.recordFor(parentSn)?.model === "T8010";
+  }
+  /**
+   * Download one recording a HomeBase 2 holds for an attached camera, then decode it
+   * ({@link decodeRecording}). Downloads queue per station: the station streams one recording at a time
+   * on the camera's channel, so a download starts only once the previous one has drained
+   * ({@link RecordingTransfer.drained}), even when that one's caller already has its answer. An abort
+   * while waiting rejects without sending anything; an abort mid-transfer rejects at once and the station's
+   * turn is held until the transfer drains.
+   */
+  async downloadRecording(sn, opts) {
+    opts.signal?.throwIfAborted();
+    const parentSn = this.stationKeyOf(sn);
+    const previous = this.recordingDownloads.get(parentSn) ?? Promise.resolve();
+    const started = this.waitTurn(previous, opts.signal).then(() => this.startRecordingDownload(sn, opts));
+    const turn = Promise.allSettled([previous, started.then((t) => t.drained)]).then(() => {
+      if (this.recordingDownloads.get(parentSn) === turn)
+        this.recordingDownloads.delete(parentSn);
+    });
+    this.recordingDownloads.set(parentSn, turn);
+    return started.then((t) => t.recording);
+  }
+  /** Resolve once `previous` settles, or reject as soon as `signal` aborts. */
+  waitTurn(previous, signal) {
+    return abortable(previous.then(() => void 0, () => void 0), signal);
+  }
+  /**
+   * Start one recording download, once the station's previous download has drained: the decoded recording,
+   * and when the station is done sending it.
+   */
+  async startRecordingDownload(sn, opts) {
+    const { session, parentSn, channel, accountId } = await this.resolveSession(sn, { signal: opts.signal });
+    const path = homeBase2RecordingPath(channel, opts.recording);
+    if (!path)
+      throw new RecordingDownloadError("invalid-recording", `no recording named ${opts.recording}`);
+    const eccKey = await this.cipherKeyFor(session, opts.cipherId, accountId, parentSn);
+    if (!eccKey) {
+      throw new RecordingDownloadError("key-unavailable", `cipher ${opts.cipherId} could not be obtained`);
+    }
+    const transfer = receiveRecording(session, {
+      path,
+      accountId,
+      channel,
+      timeoutMs: opts.timeoutMs,
+      signal: opts.signal
+    });
+    return { recording: transfer.frames.then((frames) => decodeRecording(frames, eccKey)), drained: transfer.drained };
+  }
   /**
    * Open a {@link Talkback} on a device's camera channel.
    *
@@ -25093,6 +25472,11 @@ function recordString(raw, key) {
   const v = typeof nested === "string" && nested ? nested : raw[key];
   return typeof v === "string" && v ? v : void 0;
 }
+function adminUserIdFrom(raw) {
+  const member = (raw ?? {}).member;
+  const id = member?.admin_user_id;
+  return typeof id === "string" && id ? id : void 0;
+}
 function tuyaDevIdFrom(raw) {
   for (const field of ["tuya_uuid", "tuya_virtual_id", "tuya_device_id", "virtualId"]) {
     const v = recordString(raw, field);
@@ -25250,13 +25634,7 @@ var EufyMega = class extends EventEmitter9 {
       onError: (e) => this.reportError(e),
       // The `a2` account id an `eufy_life` DP frame embeds — the owning member's `admin_user_id`,
       // falling back to the logged-in account's user id (the confirmed script path does the same).
-      resolveAccountId: (dev) => {
-        const member = (dev.raw ?? {}).member;
-        const adminId = member?.admin_user_id;
-        if (typeof adminId === "string" && adminId)
-          return adminId;
-        return this.mega.auth?.userId ?? "";
-      },
+      resolveAccountId: (dev) => adminUserIdFrom(dev.raw) ?? this.mega.auth?.userId ?? "",
       // Fetch + parse a gallery effect from the HTTP catalogue into the serializable spec. The catalogue
       // lives in the http layer (transport/http/light-catalog); the mqtt router owns the frame bytes.
       resolvePreset: (presetId) => resolveLightEffect(this.mega, presetId),
@@ -26703,6 +27081,37 @@ var EufyMega = class extends EventEmitter9 {
   getP2pSessions() {
     return this.p2p.getSessions();
   }
+  /**
+   * The people enrolled on a station, read from its own `person_basic_info` table over P2P.
+   *
+   * The cloud roster (`api.getFaces()`) answers empty for an account that keeps its faces on the
+   * station, because they were never uploaded — the station holds them.
+   *
+   * Resolves with the rows the station returned. Rejects on a station that cannot be reached, on a
+   * record stating no `admin_user_id`, and on the reply not arriving whole in time. Assembling that
+   * reply is `P2PSession.readDatabase`'s; this resolves which station and which account id.
+   *
+   * `stranger<n>` names are the station's own placeholders for a face nobody has named, and are
+   * returned as they arrive; a caller that wants only named people filters them.
+   */
+  async getStationFaces(stationSn, opts = {}) {
+    if (!this.registry.list().length)
+      await this.getDevices();
+    const station = this.p2p.stationKeyOf(stationSn);
+    const accountId = this.adminUserIdOf(station);
+    if (!accountId)
+      throw new Error(`getStationFaces: no admin_user_id on record for ${station}`);
+    await this.p2p.ensureStation(station, opts.signal);
+    const session = this.p2p.getSessions().get(station);
+    if (!session)
+      throw new Error(`getStationFaces: no P2P session for ${station}`);
+    const rows = await session.readDatabase("person_basic_info", { accountId, ...opts });
+    return rows.filter((row) => typeof row === "object" && row !== null);
+  }
+  /** The station's own `admin_user_id`, which its database refuses the query without. */
+  adminUserIdOf(stationSn) {
+    return adminUserIdFrom(this.registry.list().find((d) => d.sn === stationSn)?.raw);
+  }
   /**
    * The liveness facts for one device — see {@link DeviceState}. Facts, not an `online` verdict: "how
    * long is too long" is a threshold that belongs to the caller, and it differs per device class.
@@ -28197,6 +28606,7 @@ export {
   ROOM_SUCTIONS,
   RTSP_MEMBERS,
   RawDpWriter,
+  RecordingDownloadError,
   RecordingQuality,
   RtspRecordingMode,
   SCENE_INVALID_REASONS,
@@ -28240,6 +28650,7 @@ export {
   VACUUM_DOCK_MEMBERS,
   VACUUM_SCHEDULE_ACTIONS,
   VACUUM_SCHEDULE_WEEKDAYS,
+  VIDEO_GCM_AAD,
   VacuumMapStore,
   VideoFrameDecoder,
   WORKING_MODE_MAPS,