@mega-yfue/eufy-sdk 0.6.0-beta.15 → 0.6.0-beta.16

package/dist/transport/p2p/audio-frame.d.ts

@@ -12,3 +12,16 @@ export declare const AUDIO_TYPE_OFFSET = 5;
  * itself when a stream produces no audio at all, to feed its decoder silence.
  */
 export declare const AUDIO_CODECS: Readonly<Record<number, AudioCodec>>;
+/**
+ * Whether an audio frame is sealed: after its header, a 16-byte GCM tag and a 12-byte nonce precede the
+ * `u32@0` bytes its header declares, where a frame in the clear carries those bytes straight after the header.
+ * A stream whose keyframes wrap their media key in an ECIES envelope seals its audio this way, measured on
+ * HomeBase recordings and on HomeBase 3 live streams answering a P-256 start.
+ */
+export declare function isSealedAudio(frame: Buffer): boolean;
+/**
+ * The payload of a sealed audio frame ({@link isSealedAudio}), opened with AES-256-GCM under `mediaKey`, the
+ * media key of the keyframe before it, with the video frames' AAD. Answers `undefined` for a frame that is not
+ * sealed or does not authenticate under that key.
+ */
+export declare function openSealedAudio(frame: Buffer, mediaKey: Buffer): Buffer | undefined;

package/dist/transport/p2p/live-stream.d.ts

@@ -7,9 +7,11 @@
  *  - **Plaintext** (`signCode 0`, e.g. HomeBase-attached cameras): a fixed 22-byte frame header
  *    (`parseVideoFrameHeader`) followed directly by Annex-B NAL units — verified live (960×540,
  *    keyframe = header flag bit0). We strip the 22-byte header.
- *  - **Encrypted** (E2E cameras): the body is AES-256-GCM under a per-stream media key wrapped in a
- *    keyframe ECIES envelope. If an `eccPrivateKey` is supplied we run `VideoFrameDecoder`; otherwise
- *    those frames are skipped (no key → no video).
+ *  - **Encrypted keyframes**: either the AES-256-GCM body under a media key wrapped in an ECIES envelope
+ *    for an offered P-256 key ({@link VideoFrameDecoder}), or an AES-ECB head under a media key wrapped for
+ *    the session's RSA key ({@link P2PSession.decodeVideoFrame}). An attached camera's start on a station
+ *    with a {@link P2PSession.mediaEccPrivateKey} offers that P-256 key first, so its stream decodes with
+ *    that pair unless `eccPrivateKey` names another.
  *
  * Emits: `video` ({@link LiveVideoFrame} — Annex-B), `audio` ({@link LiveAudioFrame}), `start`, `stop`,
  * `error`.
@@ -54,7 +56,10 @@ export interface LiveStreamOptions {
      * however long the station keeps serving that sibling instead of this one.
      */
     channel?: number;
-    /** Camera ECC private key (32B) for E2E/encrypted cameras; omit for plaintext cameras. */
+    /**
+     * P-256 private key (32B) whose public point the camera wraps each keyframe's media key for. Defaults, on an
+     * attached camera, to the session's `P2PSession.mediaEccPrivateKey`, the pair its start offers.
+     */
     eccPrivateKey?: Buffer;
     /** Admin account id — required for the level-2 (`signCode 8`) media-start payload selecting a camera. */
     accountId?: string;
@@ -112,6 +117,8 @@ export declare class LiveStream extends EventEmitter {
     private tracedFirstVideoUnit;
     private tracedFirstKeyframe;
     private tracedDecodeFailures;
+    /** How the frame that opened the latest access unit was read; see {@link settleStartKey}. */
+    private unitOpenedBy;
     private tracedFirstForeignFrame;
     private stallTimer?;
     /**
@@ -198,11 +205,30 @@ export declare class LiveStream extends EventEmitter {
      */
     private acceptsMedia;
     /**
-     * The Annex-B payload of a frame that starts an access unit. The session decodes it when it can (it
-     * holds the RSA private key, and handles the plaintext form); the legacy header-strip and the ECIES
-     * {@link VideoFrameDecoder} are the fallbacks for an E2E camera.
+     * The Annex-B payload of a frame that starts an access unit. The authenticated ECIES/GCM
+     * {@link VideoFrameDecoder} goes first: its HMAC and GCM checks fail closed on a frame not sealed for its
+     * key. The session's RSA path cannot: on Node ≥ 24.5, PKCS#1 v1.5 decryption of a key not wrapped for it
+     * returns pseudo-random bytes instead of throwing (implicit rejection), which would decode an ECC
+     * keyframe into noise. The session's decode, which also passes plaintext frames, and the header strip
+     * follow. A payload that opens an access unit records how it was read: by the ECIES path, or otherwise by
+     * its sign code, sealed (`"rsa"`) or in the clear (`"plain"`).
      */
     private annexbOf;
+    /**
+     * Tell the session how this keyframe was opened, which answers the attached starts on this channel
+     * ({@link P2PSession.settleAttachedKey}), and re-issue the start when the session asks for one: a plaintext
+     * keyframe answering the session's P-256 offer, from a camera that did not use the point, which the next
+     * start asks with RSA. Only a delivered keyframe answers: a frame no key opens, or a continuation without the
+     * frame that opened its unit, delivers nothing.
+     */
+    private settleStartKey;
+    /**
+     * The payload of an audio frame. On a stream with an ECIES decoder, a sealed frame ({@link isSealedAudio}) is
+     * opened under the media key of the latest keyframe, and answers `undefined` when it does not open or arrives
+     * before any keyframe gave a media key, since its bytes are ciphertext. Every other frame is the bytes after
+     * its header.
+     */
+    private audioPayload;
     /**
      * Report an access unit the transport could not complete.
      *

package/dist/transport/p2p/live-trace.d.ts

@@ -23,6 +23,8 @@ export type LiveTrace =
     topology: "attached" | "own";
     action: "start" | "keepalive";
     level2: boolean;
+    /** The media-key type an attached start offered. */
+    key?: "ecc" | "rsa";
 }
 /** The device acknowledged a retained start, or that start was repeated / abandoned unacknowledged. */
  | {

package/dist/transport/p2p/p2p-session.d.ts

@@ -180,6 +180,13 @@ export declare class P2PSession extends EventEmitter {
     private level2Seq;
     private rsaPrivateKey?;
     private rsaModulusHex?;
+    /** The P-256 pair an attached camera's media start offers; see {@link mediaEccPrivateKey}. */
+    private mediaEcc?;
+    /**
+     * Per attached channel, the media-key type its latest start offered on this connection, or that last answered,
+     * and whether a keyframe has answered it. See {@link attachedStartKey} and {@link settleAttachedKey}.
+     */
+    private readonly attachedStartKeys;
     /**
      * Whether a level-2 key negotiation kicked off by a GATEWAYINFO reply is in flight. Cleared when it
      * settles, so a later reply — the answer to {@link repromptLevel2Key} — negotiates again.
@@ -333,7 +340,15 @@ export declare class P2PSession extends EventEmitter {
      * inside the bind callback, where a refusal is thrown out of reach of this session and ends the process.
      */
     private requestReceiveBuffer;
-    /** Open the socket and start the lookup → hole-punch handshake. */
+    /**
+     * Open the socket and start the lookup → hole-punch handshake.
+     *
+     * A socket closed or failing while binding never invokes its bind callback, so the bind wait also
+     * settles on the socket's `close` and `error`. On `close`, a connect whose session was closed meanwhile
+     * returns without starting the handshake, so it never sends a lookup or arms a timer on a closed
+     * session. On `error`, connect closes the session and rejects with {@link StationUnreachableError}
+     * carrying the bind error as its `cause`.
+     */
     connect(): Promise<void>;
     /** Cached across every `P2PSession` in this process — the local outbound IPv4 doesn't vary by
      * station, so there's no reason to re-probe it per session (e.g. once per station in a fleet). Only
@@ -618,6 +633,10 @@ export declare class P2PSession extends EventEmitter {
      * Send a CMD_SET_PAYLOAD(1350) wrapping `{account_id, cmd:<subCmd>, mChannel, mValue3:<subCmd>,
      * payload}`, encrypted level-2 (AES-256-GCM, signCode 8) — the app's media-control path. The
      * camera is selected by `mChannel` (= the device's `device_channel`) AND the frame-header channel.
+     * A start (HomeBase-controlled camera path, the V6 app's media-start envelope) also carries an
+     * `accountId` inside its payload and the media key `key` offers (see {@link attachedStartKey}). A start
+     * offering the P-256 point labels itself `ClientOS: "IOS"`, as every simple attached start in the app
+     * captures that carry that key form does; the RSA start keeps `"Android"`.
      */
     private sendMediaPayloadLevel2;
     /**
@@ -638,6 +657,41 @@ export declare class P2PSession extends EventEmitter {
      * (T8171 2560×1440, T8210 640×480). Returns `undefined` on failure (frame is skipped).
      */
     private rsaUnwrapKey;
+    /**
+     * The media-key type the next attached start sent on `channel` offers, recorded as offered: ECC, the current
+     * app's form, for the first start this connection sends there; RSA for every start after one that no keyframe
+     * answered before it was re-issued; and, once a keyframe has answered, the type that opened it, until
+     * {@link settleAttachedKey} records another. Only an opened keyframe answers: frames no key opens, and deltas,
+     * do not. A re-issue is a full restart on an attached camera, so a camera that cannot read the point is asked
+     * with RSA, the start every station answers, and is not asked with the point again while that goes unanswered.
+     * A stream decoding with the session's pair reads either answer. A station without {@link mediaEccPrivateKey}
+     * is offered RSA only. A start that cannot be sent offers nothing and records nothing.
+     */
+    private attachedStartKey;
+    /**
+     * Record how a keyframe of `channel` was opened, which answers the starts there. A keyframe opened under a
+     * key type is an answer of that type, whichever type the latest start offered: a station can serve the
+     * P-256 start after the RSA re-issue went out. A plaintext keyframe
+     * answering an unanswered P-256 offer is a camera that did not use the point, and the next start there offers
+     * RSA; once a P-256 answer has been opened it changes nothing, and answering RSA, it settles RSA. Answers
+     * whether a new start is needed. A channel no attached start has offered a key on is left as it is.
+     */
+    settleAttachedKey(channel: number, opened: "ecc" | "rsa" | "plain"): boolean;
+    /**
+     * The 32-byte P-256 private scalar paired with the point an attached camera's media start offers as `key`.
+     * A camera answering that start wraps each keyframe's AES-256-GCM media key in an ECIES envelope for this
+     * key ({@link VideoFrameDecoder}). Generated once per session, like the RSA pair.
+     *
+     * `undefined` unless the station is a HomeBase 3 (`T8030`): the app's P-256 start and the device runs
+     * that answered it were both observed on that station only.
+     */
+    get mediaEccPrivateKey(): Buffer | undefined;
+    /**
+     * The session's P-256 pair: the private scalar as 32 bytes, and the public point as 128 hex characters,
+     * `x ‖ y` without the uncompressed-point prefix, the form the current app's attached-camera start carries in
+     * `key`. `ECDH.getPrivateKey()` drops a scalar's leading zero bytes, so the scalar is padded back to 32.
+     */
+    private mediaEccPair;
     /**
      * The RSA-1024 public-key modulus (128-byte hex) the station uses to wrap the per-stream media
      * key. Lazily generates a keypair; `rsaPrivateKey` decrypts the media key the station returns.

package/dist/transport/p2p/recording-download.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Download of a recording held on a HomeBase 2 (T8010), over the station's P2P session.
+ *
+ * The request is `CMD_DOWNLOAD_VIDEO` (1024) in the string-pair shape
+ * ({@link buildStringPairCommandPayload}) on the camera's channel. The station answers on
+ * {@link RECORDING_DATA_TYPE}, tagged with that channel, with the recording's `CMD_VIDEO_FRAME` (1300) and
+ * `CMD_AUDIO_FRAME` (1301) frames, faster than real time, then `CMD_DOWNLOAD_FINISH` (1304) on the control
+ * data type, tagged with channel 0 whatever the camera's channel.
+ *
+ * Frame layouts:
+ *
+ * ```
+ * video, keyframe: the live E2E layout ({@link VideoFrameDecoder}), length = 179 + len exactly
+ * video, other frames: the same 22B header (u32@0 = len · u16@6 = frame number · u48@0x0e = stamp in ms),
+ *   then len bytes of plaintext H.264
+ * audio: 16B header (u32@0 = len · u8@5 = codec, 0 = AAC-LC), then 16B GCM tag, 12B GCM nonce and len
+ *   bytes of AES-256-GCM AAC under the media key of the preceding keyframe, AAD as live video; the
+ *   plaintext is a whole ADTS frame, header included
+ * ```
+ *
+ * @module p2p/recording-download
+ */
 import { type RecordingDownload } from "../../core/contracts.js";
 import type { P2PSession } from "./p2p-session.js";
 /** Data type a station sends a recording's frames on: the binary channel (`0xd1 0x03`), not live video's. */

package/dist/transport/p2p/video.d.ts

@@ -153,3 +153,5 @@ export declare class AccessUnitAssembler {
     /** Forget an incomplete unit, counting and reporting it. */
     discard(): void;
 }
+/** Whether a decoded payload OPENS an access unit — a continuation begins mid-NAL, with no start code. */
+export declare function beginsAccessUnit(body: Buffer): boolean;

package/dist/transport/rtc/session.d.ts

@@ -15,8 +15,10 @@
  *
  * The command data channel is the session: `close` fires once, when the channel closes, the peer fails,
  * the signalling socket drops or {@link RtcSession.close} is called, even while the peer connection is
- * nominally up. A peer that cannot be built when the hub grants the relay ends the session there: the
- * failure is emitted as `error` and `close` fires carrying it.
+ * nominally up. A dropped signalling socket closes the peer with it: a hub that still sees the peer
+ * answers every later `scall` with 486 until that peer's ICE gives up. A peer that cannot be built when
+ * the hub grants the relay ends the session there: the failure is emitted as `error` and `close` fires
+ * carrying it.
  *
  * A session whose peer is a {@link RtcPeerOptions.mediaTrack} peer has no command channel: `close` fires
  * when the peer fails or closes, and the video track's packets are emitted as `rtp`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.6.0-beta.15",
+  "version": "0.6.0-beta.16",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",