@mega-yfue/eufy-sdk 0.5.0-beta.9 → 0.5.0-beta.90

package/dist/transport/http/mega-client.d.ts

@@ -209,6 +209,8 @@ export interface SignedRetry {
 export declare class MegaHttpClient {
     private readonly cfg;
     private region;
+    /** The host `estimate_domain` answered, persisted with the session. */
+    private estimatedDomain;
     private bootstrapDomain?;
     private sessionKey?;
     /** Per-host ECDH session keys for non-mega gateways (e.g. eufylife) keyed by host. */
@@ -228,6 +230,8 @@ export declare class MegaHttpClient {
     /** True while a 2FA code is outstanding: `auth_` holds only the limited pre-verify token, so the
      *  restored-session short-circuit must NOT treat it as a usable session. Cleared on Ok/reset. */
     private pending2fa;
+    /** An autonomous re-login answered captcha/2FA; see {@link canReauthenticate}. */
+    private reloginChallenged;
     private tokenExpiresAt;
     /**
      * Stable per-install device id: `openudid` as configured, as restored from the session store, or as
@@ -259,10 +263,12 @@ export declare class MegaHttpClient {
     constructor(cfg: MegaClientConfig);
     /**
      * Install the session the store holds, if it holds a usable one: the token + its bound ECDH key, skipping
-     * estimate/key-exchange/login/2FA entirely. Answers the token adopted, or `undefined`.
+     * estimate/key-exchange/login/2FA entirely. Answers the token adopted, or `undefined`. A session logged in
+     * with a country other than the configured one is not usable: its shard is the other country's.
      *
      * Read at construction, and again when a rejection is being recovered from — a store SHARED with another
      * client may already hold the session that client obtained, which is cheaper to adopt than to compete with.
+     * An adopted session is a complete one, so it ends any 2FA or challenged re-login this client was left with.
      *
      * Note: the device identity (openudid + phone model + media UA) is NOT restored here — it is resolved once
      * in the constructor, where an explicit config wins over the stored value, and must not be re-derived from a
@@ -275,6 +281,21 @@ export declare class MegaHttpClient {
     } | undefined;
     /** The active region shard (e.g. `"eu-pr"`, `"us-pr"`), set after {@link login} or a region override. */
     get regionShard(): RegionShard;
+    /**
+     * The shard the RTC signalling signs on: the regional prefix of the estimated domain
+     * (`…-ie-…`/`…-ie.` → `ie-pr`), else {@link regionShard}. The eu/us classification cannot name shards
+     * like `ie-pr`, whose accounts need the IE sign host and cluster.
+     */
+    get rtcShard(): string;
+    /**
+     * The credentials the RTC signalling needs; `undefined` while logged out. The sign is refused
+     * ("gtoken not equal userid") unless its gtoken is the one every authed HTTP call carries.
+     */
+    rtcIdentity(): {
+        authToken: string;
+        userId: string;
+        gtoken: string;
+    } | undefined;
     /**
      * The name commands attribute themselves to — {@link MegaClientConfig.accountName} when the config
      * pins one (trimmed; blank counts as unset), otherwise the logged-in account's display name, which
@@ -367,6 +388,15 @@ export declare class MegaHttpClient {
      * params instead, which also carry `{param_type, param_value, update_time}` and are not owner-gated.
      */
     getDeviceParamList<T = unknown>(deviceSn: string): Promise<T>;
+    /**
+     * Fetch the account's devices as the `devicerelation` service lists them, `{attribute: 7, house_id: ""}`.
+     *
+     * Each entry is `{device: {device_sn, dps, …}}`, and `dps` is the cloud's last-known value of every
+     * data point that device has reported, keyed by DP number. Answered for an account a device is shared
+     * with as well as for its owner. Sent with `category: eufy_home`, without which the service answers
+     * `10000`.
+     */
+    getDeviceRelationList<T = unknown>(): Promise<T>;
     /**
      * Fetch one page of a device's **cleaning history** from the mega `clean` service.
      *
@@ -422,6 +452,15 @@ export declare class MegaHttpClient {
     downloadImage(url: string, p2pDid?: string): Promise<Buffer>;
     /** The security-app data host for this region (face recognition, media, etc.). */
     private securityAppHost;
+    /**
+     * The device's long-lived P-256 public key, as the cloud publishes it for key-wrapped commands
+     * (`type=2`): 64 bytes hex with no `04` prefix. A plain authed GET on the security-app host — the
+     * one read here that is neither signed nor body-encrypted, matching how the app fetches it.
+     * Cached per serial for the client's lifetime; the key does not rotate in normal operation.
+     */
+    getDevicePublicKey(deviceSn: string): Promise<string>;
+    /** Per-serial cache for {@link getDevicePublicKey}. */
+    private readonly devicePublicKeys;
     /**
      * Signed+encrypted POST to the security-app data host (face recognition, etc.).
      * Despite the different host, these endpoints use the SAME algo_ecdh pipeline as
@@ -563,7 +602,9 @@ export declare class MegaHttpClient {
      * Structural rather than a list of paths: a login round trip is itself an authenticated call while a limited
      * token is held, so re-logging in from inside one would recurse — and a path list would have to be
      * maintained alongside every request the login flow makes. A 2FA code already outstanding is a login a human
-     * is part-way through, and restarting it silently would discard it. No credentials means nothing to try,
+     * is part-way through, and restarting it silently would discard it. A re-login that already came back needing
+     * a captcha or a 2FA code would need the same again, and each attempt sends the account another code, so
+     * none is tried until a login completes or a stored session is adopted. No credentials means nothing to try,
      * so the rejection surfaces instead.
      */
     private canReauthenticate;

package/dist/transport/mqtt/broker-discovery.d.ts

@@ -8,8 +8,9 @@ export interface BrokerCredentials {
 }
 export interface ProbeResult {
     ip: string;
-    /** True iff SUBSCRIBE to the target topic was granted (qos 0/1/2, not the 0x80 deny code). */
+    /** True iff SUBSCRIBE to the target topic was granted (qos 0/1/2). */
     granted: boolean;
+    /** The SUBACK return code for the topic, the 0x80 deny code included. */
     grantedQos?: number;
     error?: string;
     ms: number;

package/dist/transport/mqtt/command-router.d.ts

@@ -136,8 +136,9 @@ export declare class MqttCommandRouter {
      * One exception is known: a single garage unit whose own-cert SUBSCRIBE was denied on every candidate
      * while a phone-extracted cert granted on the same one, with a sibling of the same model on the same
      * account granting fine. That is a per-device authorization gap on the vendor's backend, not a
-     * broker-instance problem and not something this SDK works around — such a device reports as offline
-     * (the throw below) until the backend grants the account's own credentials.
+     * broker-instance problem and not something this SDK works around — the throw below names each
+     * candidate's outcome (its SUBACK deny code, a timeout or a connection error) until the backend grants
+     * the account's own credentials.
      *
      * One fresh, explicitly non-reconnecting (`reconnectPeriod: 0`) connection per call — it repays the
      * full mTLS handshake every command and tears the socket down right after (see

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

@@ -0,0 +1,14 @@
+import type { AudioCodec } from "../../core/contracts.js";
+export declare const CMD_AUDIO_FRAME = 1301;
+/** Length of the audio frame header before the payload. */
+export declare const AUDIO_HEADER_LEN = 16;
+/** Byte offset of the codec id between the frame-size and frame-number fields. */
+export declare const AUDIO_TYPE_OFFSET = 5;
+/**
+ * Codec ids the station puts at {@link AUDIO_TYPE_OFFSET}, as the v6 app maps them
+ * (`AudioReader.AAC_LC = 0`, `G711A = 2`, `AAC_ELD = 7`).
+ *
+ * The app's `PCM_SILENCE = -1` is absent on purpose: it is not a wire value. The app injects it
+ * itself when a stream produces no audio at all, to feed its decoder silence.
+ */
+export declare const AUDIO_CODECS: Readonly<Record<number, AudioCodec>>;

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

@@ -100,6 +100,22 @@ export interface EciesUnwrapOptions {
  * decrypted bytes, or `undefined` on any parse / HMAC / cipher failure (fails closed, never throws).
  */
 export declare function eciesUnwrap(envelope: Buffer, eccPrivateKeyHex: string, options?: EciesUnwrapOptions): Buffer | undefined;
+/** The two random inputs of {@link eciesWrap}, injectable so a spec can pin an envelope's bytes. */
+export interface EciesWrapOptions {
+    /** The ephemeral P-256 private key for the exchange (32 bytes); generated fresh when absent. */
+    ephemeralPrivateKey?: Buffer;
+    /** The AES-128-CBC IV, which the envelope carries (16 bytes); random when absent. */
+    iv?: Buffer;
+}
+/**
+ * The sealing counterpart of {@link eciesUnwrap} with `verifyHmac` and `pkcs7` both set.
+ *
+ * Seals `plaintext` for `peerPublicKey` (a P-256 point, compressed or uncompressed) as
+ * `ephemeralPub(33, compressed) ‖ iv(16) ‖ ct ‖ HMAC(32)`: `S = ECDH_X(ephemeral, peer)` →
+ * `kdf = eufyKDF(S)` → `ct = AES-128-CBC(kdf[0:16], iv, PKCS7(plaintext))`, tagged
+ * `HMAC-SHA256(kdf[16:48], iv ‖ ct)`.
+ */
+export declare function eciesWrap(plaintext: Buffer, peerPublicKey: Buffer, options?: EciesWrapOptions): Buffer;
 /**
  * Derive the P2P **level-2** (signCode 2/8) AES-256-GCM session key from a *decrypted*
  * `CMD_GATEWAYINFO` (1100) payload and the station's ECC private key (from `get_ciphers`).
@@ -111,6 +127,22 @@ export declare function eciesUnwrap(envelope: Buffer, eccPrivateKeyHex: string,
  * Returns the 32-byte key, or undefined if the inputs don't parse.
  */
 export declare function deriveLevel2KeyFromGatewayInfo(gwPayload: Buffer, eccPrivateKeyHex: string): Buffer | undefined;
+/**
+ * Derive the P2P **level-2** AES-128-ECB session key from a *decrypted* `CMD_GATEWAYINFO` (1100)
+ * payload and the RSA private key of a cipher whose `get_ciphers` answer carries no ECC key.
+ *
+ * Layout of the decrypted payload: `cipher_id(2 LE) ‖ 0000 ‖ RSA ciphertext ‖ …`, the ciphertext as
+ * long as the key's modulus. It is the 16-byte session key under PKCS#1 v1.5 encryption padding
+ * (`00 02 ‖ ≥8 non-zero bytes ‖ 00 ‖ key`). The padding is checked here over the raw RSA result so a wrong
+ * key fails closed: under OpenSSL's implicit rejection, `RSA_PKCS1_PADDING` answers random bytes for it
+ * instead of throwing, and those can be 16 bytes long.
+ *
+ * `rsaPrivateKey` is the `get_ciphers` `private_key`: base64 PKCS#8 DER.
+ *
+ * Returns the 16-byte key, or `undefined` when the key does not parse, the payload is short, or the
+ * padding or key length is wrong (fails closed, never throws).
+ */
+export declare function deriveLevel2KeyFromRsaGatewayInfo(gwPayload: Buffer, rsaPrivateKey: string): Buffer | undefined;
 /** Local-lookup payload: two zero bytes. */
 export declare function buildLocalLookupPayload(): Buffer;
 /** Cloud-lookup payload (variant 2): `[p2pDid:20][dskKey][0x00000000]`. */

package/dist/transport/p2p/command-router.d.ts

@@ -1,14 +1,3 @@
-/**
- * P2P command router — the transport-side owner of the ThroughTek PPCS sessions and every wire
- * operation over them: opening sessions, resolving a serial to its session + routing params,
- * mapping a transport-neutral {@link Command} to a concrete frame (encryption level, wire shape),
- * the fire-and-forget control senders, request/reply queries, and the media provider.
- *
- * Layering: this module knows P2P bytes; it does NOT know capabilities. Frame → semantic-event
- * decoding is a model concern, so raw frames are handed back to the client via {@link P2PRouterDeps.onFrame}
- * (the client gates them on device capabilities and emits typed events). This keeps transport free of
- * any `model/` import — the capability↔transport decorrelation invariant.
- */
 import type { MegaHttpClient } from "../http/mega-client.js";
 import type { EufyDevice } from "../../core/types.js";
 import type { Command, AutoLockSnapshot, MediaProvider, SharedSourceHints, AbortableCall } from "../../core/contracts.js";
@@ -119,10 +108,21 @@ export declare class P2PCommandRouter {
      * shared — see {@link P2PCommandRouter.openTalkback}.
      */
     private readonly talkbacks;
-    /** cipher_id → ECC private key (one eufylife get_ciphers call per cipher), shared across (re)opens. */
+    /** cipher_id → its ECC and RSA private keys (one eufylife get_ciphers call per cipher), shared across (re)opens. */
     private readonly cipherKeyCache;
     /** The recording download in flight per station; a station serves one at a time. */
     private readonly recordingDownloads;
+    /**
+     * The `seq_num` last sent to each device over the keyed-payload wire. The device holds a mark for the life
+     * of a P2P connection: the first keyed command on a new connection is accepted at whatever number it
+     * carries and becomes the mark, and after that a number not above the mark is refused with the mark
+     * published ({@link keyedPayloadSeqMark}). Each accepted command moves this to its number, a refusal
+     * moves it to the published mark + 1, and a device absent here has not been sent one in this process and
+     * seeds from a small random number — which a new connection takes as sent.
+     */
+    private readonly keyedSequences;
+    /** The keyed-payload command in flight per device, which the next one for that device waits on. */
+    private readonly keyedQueue;
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
@@ -224,7 +224,7 @@ export declare class P2PCommandRouter {
      * Build + wire a {@link P2PSession} for a station (NOT yet connected — the caller awaits `connect()`).
      *
      * `resolveCipherKey` auto-negotiates the level-2 session key from `CMD_GATEWAYINFO` by resolving the
-     * cipher's ECC private key via cloud `get_ciphers`, so signCode 2/8 frames decrypt live; results are
+     * cipher's private keys via cloud `get_ciphers`, so signCode 2/8 frames decrypt live; results are
      * cached on the router instance so a lazy re-open (after idle-detach) reuses the lookup. Only a
      * SUCCESSFUL lookup is cached — caching `undefined` after a transient failure would permanently
      * disable level-2 for the session's life.
@@ -240,11 +240,12 @@ export declare class P2PCommandRouter {
      */
     private makeSession;
     /**
-     * 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.
+     * The ECC and RSA private keys of `cipherId` (`ecc_private_key`, `private_key`), from the router's cache
+     * or one `get_ciphers` call. When the cloud answers with another cipher that carries an ECC key and the
+     * asked one does not, that one is used and traced on `session`. Only a successful lookup — one that
+     * yields either key — is cached.
      */
-    private cipherKeyFor;
+    private cipherKeysFor;
     /**
      * 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.
@@ -272,7 +273,7 @@ export declare class P2PCommandRouter {
      * A {@link MediaProvider} bound to one serial — resolves the session then calls `p2p/media`.
      *
      * Every live egress here is a consumer of the SAME shared pull, so N `live()` calls collapse to one
-     * PPCS session and a live snapshot against a warm, keyframe-primed source costs no extra pull at all; a
+     * PPCS session and a live snapshot against a warm shared source costs no extra pull at all; a
      * cold source warms one and waits for a clean keyframe. Each shared egress passes its complete options
      * through because any of them may create the source, whose power and retention hints are fixed for
      * everyone who joins later. The bounded {@link MediaProvider.record} clip is the exception: it opens its
@@ -311,6 +312,11 @@ export declare class P2PCommandRouter {
      * stream costs nothing extra and a talkback on an otherwise idle camera opens the session it needs
      * instead of playing into silence.
      *
+     * **On a model in {@link ELD_TALKBACK_MODELS}, the speaker plays the codec the camera sends.** So the first
+     * audio frame of the media session this talkback holds decides its codec ({@link speakerCodec}), within
+     * {@link TALKBACK_CODEC_WAIT_MS} of the session's first frame, and the claim is re-checked after that wait as
+     * after the warm-up. Every other model opens `aac-lc` at once.
+     *
      * The level-2 key is waited for softly: only the HomeBase-attached path requires it, and
      * {@link Talkback.start} reports that failure precisely, so a hard wait here would reject an
      * own-session camera that legitimately never negotiates one.
@@ -456,15 +462,6 @@ export declare class P2PCommandRouter {
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
      * unaffected.
      */
-    /**
-     * Attach a consumer, unless the caller has already abandoned the call.
-     *
-     * The acquisition it just waited through can outlast the caller's interest, and a consumer attached for
-     * somebody who has gone keeps the pull warm for nobody. Detaching immediately gives the pull back, which
-     * lets it linger and fall away if this was the only thing holding it, and leaves it untouched if it was
-     * not.
-     */
-    private attachUnlessAborted;
     /**
      * Dispose one cached live source and forget it, so the next acquisition builds a fresh one. Its claim
      * on a session goes with it, and a media session opened for this source alone is closed: nothing else
@@ -524,11 +521,11 @@ export declare class P2PCommandRouter {
      */
     private onLiveStartFailed;
     /**
-     * Replace the session under a warming source whose media start nothing acknowledged, and warm again on it.
+     * Replace the session under a warming source it is not serving, and warm again on it.
      *
      * Only a STANDALONE device's session is replaced, for the reason {@link onLiveStartFailed} gives: an attached
      * camera shares its HomeBase session with every other camera on it, and closing that to recover one would
-     * drop the rest. Such a source keeps the re-issue it always had.
+     * drop the rest. Such a source keeps the re-issue it always had, which the answer (false) tells it.
      *
      * The source is left warming throughout, holding the deadline it started, so this either produces a stream
      * within that window or fails exactly as it would have. A replacement that cannot be opened leaves the
@@ -562,6 +559,7 @@ export declare class P2PCommandRouter {
      */
     p2pQuery(sn: string, subCmd: number, opts?: {
         timeoutMs?: number;
+        payload?: Record<string, unknown>;
     }): Promise<Record<string, unknown>>;
     /**
      * **Generic control-payload request/reply query.** Sends a `CONTROL_PAYLOAD` (1700) `{commandType,
@@ -690,7 +688,7 @@ export declare class P2PCommandRouter {
      * **`set-json-raw` intent** — bare JSON, no envelope: outer P2P cmd = `outerCmd` itself, plaintext
      * exactly `{account_id,...data}` (`session.sendRawLevel2` with no wrapper). Reversed from a live
      * capture of the app's own SET_SNOOZE_TIME (1271) frame — see `param-dictionary.ts`'s `1271` entry
-     * (`snoozeTime`); the alarm-delay config (1255, `arming.ts`'s `ARMING_CMD.ALARM_DELAY_CONFIG`) reuses
+     * (`snoozeTime`); the alarm-delay config (1255, `arming.ts`'s `ARMING_CMD.SET_ALL_ACTION`) reuses
      * the same bare-JSON shape.
      */
     private sendJsonRaw;
@@ -705,7 +703,9 @@ export declare class P2PCommandRouter {
      * HomeBase-attached device takes the GCM signCode-8 form, a standalone one the level-1 form. A
      * standalone camera never negotiates a level-2 key, so pinning this to level 2 makes the envelope
      * unreachable on exactly the devices that serve their own RTSP stream. Verified live: a standalone
-     * camera accepts the level-1 form. With no `form` (default) it stays level-2 only.
+     * camera accepts the level-1 form. With no `form` (default) it stays level-2 only and waits for the
+     * key every level-2 sender uses; `level2Sender: "set-payload"` also takes an RSA cipher's AES-128-ECB
+     * key (see {@link P2PSession.sendControlLevel2}). A `resolved` session keeps the wait its caller gave it.
      *
      * Both seals REPLAY the frame {@link DIRECT_CMD_SENDS}× at 200ms, as every other fire-and-forget
      * control on this router does: these are unacknowledged datagrams, and a level-1 device is the one
@@ -715,6 +715,68 @@ export declare class P2PCommandRouter {
      * boolean, so the first pass carries the failure and the rest are repeats.
      */
     private sendSetPayloadEnvelope;
+    /**
+     * **`keyed-payload-actuate` intent** — the classic Wi-Fi lock's actuation: the sealed fields from
+     * {@link buildKeyedActuatePayload}, sent as a keyed envelope through {@link P2PSession.sendSetPayload}
+     * on the lock's device channel. No session key is waited for — the envelope seals its own per-command
+     * key for the device's public key (fetched from the cloud, cached per serial), so it goes as soon as
+     * the session is up. The device shows the acting member by display name, which lives on the device
+     * record's `member` rather than in the intent, so it is read here and falls back to the account name
+     * the intent carries.
+     *
+     * The device answers, so the outcome is read rather than assumed: {@link awaitKeyedReply} settles each
+     * send on the replies, and resolves a {@link KEYED_PAYLOAD_SEQ_ERROR} refusal with the mark the device
+     * publishes in the refusal's `CMD_DOORLOCK_P2P_SEQ` (1916) twin. On that mark the command resends once,
+     * at mark + 1; a second refusal, or a refusal that published no mark, throws. Commands run one at a time
+     * per device: the replies carry no correlation id, so one command's answer must never be read as
+     * another's.
+     */
+    private sendKeyedPayloadActuate;
+    /** Run `work` once every keyed-payload command already queued for `sn` has settled. */
+    private serializeKeyed;
+    /**
+     * Send one keyed command at the device's next sequence and, on a sequence refusal, resend once at the
+     * mark the refusal published.
+     *
+     * A device's first number in a process is a small random seed — the scale the vendor app's own counters
+     * run at — and every later one is the previous plus one. The device takes the first number on a new
+     * connection as sent, and from then on refuses one not above the mark it holds, stating the mark in the
+     * refusal's `CMD_DOORLOCK_P2P_SEQ` (1916) twin ({@link awaitKeyedReply} resolves the refusal with it).
+     * So a refusal is resolved to that mark and the command resent once at mark + 1, the number the device
+     * accepts after a refusal; a second refusal, or a refusal that carried no mark, throws. The accepted
+     * number is recorded, so the next command starts just above it.
+     *
+     * @param engage whether the command drives to the engaged (locked) state, which its own report states.
+     * @param send dispatches the envelope at the sequence it is given.
+     */
+    private sendKeyedAtSequence;
+    /**
+     * Send one keyed-payload command and read the device's answer for it from the replies on the command's
+     * channel: the `SET_PAYLOAD` echo (a `commandResult`), at once, carrying the result as an int32 — or,
+     * when the echo was not read and the command changed the device's state, the `NOTIFY_PAYLOAD` about two
+     * seconds later carrying the result again as a `P2P_QUERY_STATUS_IN_LOCK` (1955) document. A report
+     * is tied to the command by its `slState`: only one stating the state this command drives to, by
+     * `engage` ({@link keyedPayloadReportCode}), is read as its answer. A report of the other state is a
+     * previous command's, landing after that command settled on its echo, and is ignored.
+     *
+     * - An accepted result (code `0`) settles the command.
+     * - A sequence refusal is stated twice, both about a tenth of a second after the send: the `-151` echo
+     *   and a `CMD_DOORLOCK_P2P_SEQ` (1916) notify whose `seq_num` is the mark the device holds. The
+     *   resolved value carries that mark, so the caller resends just above it. Collection runs for
+     *   {@link KEYED_REFUSAL_TWIN_MS} after the first of the two, so both land and neither is left on the
+     *   channel for the resend to read as its own answer, and either one alone still resolves the refusal.
+     * - No reply within {@link KEYED_REPLY_MS} is a command that never landed, and rejects.
+     *
+     * Both listeners are armed before the send, and only replies on `channel` are read. The channel names
+     * the device, not the command: every other P2P write a lock takes waits for a level-2 key this device
+     * never negotiates, so nothing else the SDK sends can draw a reply here, and a future intent on this
+     * wrapper has to share {@link serializeKeyed}.
+     */
+    private awaitKeyedReply;
+    /** How long a keyed-payload command waits for any reply before it is taken as never having landed. */
+    private static readonly KEYED_REPLY_MS;
+    /** How long a refusal collects its two statements — the `-151` echo and the mark notify — before resolving. */
+    private static readonly KEYED_REFUSAL_TWIN_MS;
     /**
      * **`ff09-actuate` intent** — build the `ff09` AES-128-CBC frame ({@link buildFf09Frame}, shared with the
      * MQTT transport — see `transport/ff09.ts`) and dispatch it in the `1940` TRANSFER_PAYLOAD envelope

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

@@ -17,9 +17,12 @@ export declare class Fmp4Muxer {
     private baseDecodeTime;
     private fragTicks;
     private samples;
-    private lastVideoTimestampMs?;
+    /** Ticks from the first video sample's start to the newest sample's end, at its provisional duration. */
+    private videoTicks;
     private readonly audioRequested;
     private audioCodec?;
+    /** Decoder config of an AAC-ELD track, taken from its frames; absent for AAC-LC, whose `esds` config is fixed. */
+    private audioConfig?;
     private audioDisabled;
     private audioSamples;
     private audioBaseDecodeTime;
@@ -35,9 +38,16 @@ export declare class Fmp4Muxer {
      * Push one access unit. Returns any completed segments: the `init` on the first keyframe, and/or a
      * media fragment when this frame closed the open one. Returns `undefined` if nothing is emitted yet
      * (e.g. delta frames before the first keyframe).
+     *
+     * A sample lasts until the next frame's `timestampMs`, measured from the first keyframe's, so the video
+     * timeline follows the arrival clock; a frame that shares the previous one's timestamp leaves that
+     * sample one tick long, and the next frame's duration absorbs the difference.
      */
     push(frame: LiveVideoFrame, timestampMs?: number): MediaFragment | undefined;
-    /** Add one station-declared AAC access unit to the audio track. G.711 remains available via `live()`. */
+    /**
+     * Add one station-declared AAC access unit to the audio track: an ADTS frame for AAC-LC, a raw access unit
+     * described by its frame's config for AAC-ELD. G.711 remains available via `live()`.
+     */
     pushAudio(frame: LiveAudioFrame, timestampMs?: number): MediaFragment | undefined;
     /** Permanently omit incompatible audio while allowing the video recording to continue. */
     private disableAudio;

package/dist/transport/p2p/keyed-payload.d.ts

@@ -0,0 +1,112 @@
+import type { Ff09Identity } from "../../core/contracts.js";
+/**
+ * Keyed-payload envelope — the `SET_PAYLOAD` (1350) shape the classic Wi-Fi smart lock takes for its
+ * actuation. There is no session key: every command carries its OWN fresh AES-128 key, sealed for the
+ * device's long-lived P-256 public key (published by the cloud, one per device), and the inner JSON is
+ * AES-128-CBC/PKCS#7 under that key. This module builds the two sealed fields; `P2PSession.sendSetPayload`
+ * wraps them in the ordinary envelope and carries a keyed one in the clear, as the vendor app sends it.
+ *
+ * ## Wire
+ *
+ * ```
+ *   { key: <keyBlobHex>, account_id: <adminUserId>, cmd: <opcode>, mChannel: <ch>, mValue3: 0,
+ *     payload: <base64(AES-128-CBC(aesKey, iv, innerJson))> }
+ * ```
+ * `iv` = ASCII(deviceSn) zero-padded/truncated to 16 bytes. `aesKey` = 16 random bytes, spelled as 32
+ * UPPERCASE hex characters — the hex SPELLING is what the key blob seals, not the raw bytes.
+ *
+ * `key` (hex) is the ECIES envelope {@link eciesWrap} produces for the device's public key over that
+ * spelling: `compressedEphemeralPub(33) ‖ nonce(16) ‖ sealedKey(48) ‖ hmac(32)`.
+ *
+ * Inner JSON for the actuation opcode, `P2P_ON_OFF_LOCK` (1961): `{shortUserId, slOperation: 1|0, userId,
+ * userName, seq_num}`.
+ *
+ * ## Answer
+ *
+ * The device answers every command at once with an int32 result on the `SET_PAYLOAD` echo — `0`
+ * accepted, {@link KEYED_PAYLOAD_SEQ_ERROR} when `seq_num` is not above the mark it holds — and, when the
+ * command changed its state, about two seconds later with a `NOTIFY_PAYLOAD` whose JSON carries
+ * `P2P_QUERY_STATUS_IN_LOCK` (1955) as `cmd`, the result again under `payload.code` and the state reached
+ * under `payload.slState` ({@link keyedPayloadReportCode} reads the code of the report stating the state
+ * a command drives to). A command it was already in the state of draws the echo alone.
+ *
+ * A refusal carries a second `NOTIFY_PAYLOAD`, `CMD_DOORLOCK_P2P_SEQ` (1916), whose `payload.seq_num`
+ * ({@link keyedPayloadSeqMark}) is the mark the device holds — so a refused command hands back the exact
+ * number to resend above, with no searching. The mark lives with the P2P connection: the first keyed
+ * command on a new connection is accepted at whatever number it carries.
+ *
+ * The command ids are {@link CommandType}'s; the inner field names follow a third-party reverse-engineering
+ * project, a name source only.
+ */
+/**
+ * The int32 result the device answers a command with when its `seq_num` is not above the mark it holds for
+ * the connection. The command is dropped untried, so this is a retry signal rather than a failure: resend
+ * above the mark. The refusal publishes that mark in its `CMD_DOORLOCK_P2P_SEQ` (1916) twin
+ * ({@link keyedPayloadSeqMark}), so the resend goes to the next number rather than searching for it.
+ */
+export declare const KEYED_PAYLOAD_SEQ_ERROR = -151;
+/** Knobs a spec injects to make the otherwise random envelope deterministic, plus the sequence it carries. */
+export interface KeyedPayloadRandomness {
+    /** The per-command AES key (16 bytes). */
+    aesKey?: Buffer;
+    /** The CBC nonce sealing that key inside the blob (16 bytes). */
+    nonce?: Buffer;
+    /** The ephemeral P-256 private key for the ECDH exchange (32 bytes). */
+    ephemeralPrivateKey?: Buffer;
+    /** The `seq_num` the inner JSON carries, issued by the sender. */
+    seqNum: number;
+}
+/**
+ * The cipher IV the device derives from its own serial: ASCII bytes, zero-padded to 16. It is the same for
+ * every command to a device, which is sound only because {@link buildKeyedActuatePayload} seals each command
+ * under a key minted for it alone — no two messages ever share a key with this IV.
+ */
+export declare function serialIv(deviceSn: string): Buffer;
+/** Spell 16 key bytes as the 32 uppercase hex characters the wire seals. */
+export declare function spellAesKey(key: Buffer): string;
+/**
+ * Seal a per-command AES key for the device's P-256 public key: the {@link eciesWrap} envelope over the
+ * key's hex spelling, as hex.
+ * @param aesKeyHex the 32-hex-char key spelling (what gets sealed — as ASCII).
+ * @param devicePublicKeyHex the device's uncompressed public key WITHOUT the `04` prefix (64 bytes hex).
+ */
+export declare function buildKeyBlob(aesKeyHex: string, devicePublicKeyHex: string, rnd?: Pick<KeyedPayloadRandomness, "nonce" | "ephemeralPrivateKey">): string;
+/** AES-128-CBC/PKCS#7 the inner JSON under the per-command key, IV from the serial; base64 out. */
+export declare function sealInnerPayload(innerJson: string, aesKeyHex: string, deviceSn: string): string;
+/** The two sealed fields of a keyed envelope; the sender supplies the rest of the `SET_PAYLOAD` value. */
+export interface KeyedActuatePayload {
+    /** The sealed per-command key — the value's `key` field, hex. */
+    key: string;
+    /** The inner JSON sealed under that key — the value's `payload` field, base64. */
+    payload: string;
+}
+/**
+ * Build the sealed fields of the classic Wi-Fi lock's actuation.
+ * @param id the acting identity + direction.
+ * @param devicePublicKeyHex the device's public key from the cloud (no `04` prefix).
+ * @param userName the acting member's display name as the device shows it in its log.
+ */
+export declare function buildKeyedActuatePayload(id: Ff09Identity, devicePublicKeyHex: string, userName: string, rnd: KeyedPayloadRandomness): KeyedActuatePayload;
+/**
+ * The result a `NOTIFY_PAYLOAD` document reports for a keyed command driving to a state. The device sends
+ * one once a keyed command has changed its state, `{cmd, payload: {code, slState, …}}` with `cmd`
+ * `P2P_QUERY_STATUS_IN_LOCK` (1955) in {@link CommandType}, `payload.code` being the command's result and
+ * `payload.slState` the state reached. Answers `payload.code` when it is a number and `payload.slState` is
+ * the state the command drives to: `"4"` engaged (locked) when `engage`, `"3"` released (unlocked) when
+ * not, the values of the lock's state param 6000 as the device spells them. Answers `undefined` for any
+ * other document, a report of the other state included: that one answers some other command.
+ */
+export declare function keyedPayloadReportCode(json: {
+    cmd?: number;
+    payload?: unknown;
+} | undefined, engage: boolean): number | undefined;
+/**
+ * The sequence mark a `NOTIFY_PAYLOAD` document publishes. The one that rides a sequence refusal is
+ * `{cmd, payload: {lock_cmd, seq_num}}` with `cmd` `CMD_DOORLOCK_P2P_SEQ` (1916) in {@link CommandType},
+ * `payload.seq_num` being the mark the device holds on this connection. Answers that number, or
+ * `undefined` for any other document.
+ */
+export declare function keyedPayloadSeqMark(json: {
+    cmd?: number;
+    payload?: unknown;
+} | undefined): number | undefined;

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

@@ -11,6 +11,7 @@
  *
  * @module p2p/live-trace
  */
+import type { LiveStreamStartFailureReason, LiveStreamStartStage } from "../../core/contracts.js";
 import type { Logger } from "../../core/logger.js";
 /** The message every startup trace is logged under. */
 export declare const LIVE_TRACE_MESSAGE = "[live] start trace";
@@ -118,11 +119,19 @@ export type LiveTrace =
     phase: "level2-wait";
     waitMs: number;
 }
-/** The station's level-2 key was negotiated, under the cipher it selected. */
+/** The station's AES-256-GCM level-2 key was negotiated, under the cipher it selected. */
  | {
     phase: "level2-ready";
     cipherId: number;
 }
+/**
+ * The station's cipher negotiated only the AES-128-ECB level-2 key of an RSA cipher, under the cipher it
+ * selected. That key seals a level-2 set-payload and nothing else, so this is not `level2-ready`.
+ */
+ | {
+    phase: "level2-set-payload-only";
+    cipherId: number;
+}
 /**
  * The station's key is not coming, why, and the cipher where a station named one.
  *
@@ -145,7 +154,8 @@ export type LiveTrace =
  * A station's cipher was answered with material for a DIFFERENT cipher, which was used in its place.
  *
  * The one lookup outcome no other phase accounts for: material for the cipher the station named is followed
- * by `level2-ready` or by `level2-unavailable` with `derivation-failed`, an answer holding none by
+ * by `level2-ready`, `level2-set-payload-only` or `level2-unavailable` with `derivation-failed`, an answer
+ * holding none by
  * `no-cipher-key`, and a lookup that threw is reported as an error. Substituted material derives to
  * nothing and otherwise reads as a station fault. `cipherId` is the cipher the station asked for,
  * `answeredCipherId` the one whose material was used.
@@ -236,6 +246,19 @@ export type LiveTrace =
     phase: "channel-silent";
     silentMs: number;
     outcome: "reasserted" | "declined";
+}
+/**
+ * A live start failed, with the facts of the `LiveStreamStartError` it was refused with.
+ *
+ * `errorName` is the upstream error's class name, present for `source-error` only; its message is never
+ * carried, because an upstream message can name a station.
+ */
+ | {
+    phase: "start-failed";
+    reason: LiveStreamStartFailureReason;
+    stage: LiveStreamStartStage;
+    attempts: number;
+    errorName?: string;
 };
 /**
  * Record one startup observation at debug level.

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

@@ -24,11 +24,9 @@ import type { SharedLiveSource } from "./shared-live-source.js";
 export declare function openLiveStream(session: P2PSession, opts?: LiveStreamOptions): Promise<LiveStream>;
 /**
  * **Live snapshot off a SHARED source** (V6) — snapshot as just another consumer of the shared live
- * pull. If the source is already warm and has a cached keyframe (V2 keyframe-prime), the joining
- * consumer receives that IDR immediately and we decode it with **no extra pull** — a snapshot while
- * someone else watches costs nothing on the wire. Otherwise we warm the source and wait for a clean
- * keyframe (the first IDR after a cold start is frequently partial, so skip it by default). Requires
- * `ffmpeg` for the Annex-B → JPEG decode.
+ * pull. A warm source reuses its upstream session; collection starts from live keyframes rather than
+ * a retained picture. A live source captures its next keyframe by default; a cold source skips the
+ * first keyframe because its first IDR is frequently partial. Requires `ffmpeg` for the Annex-B → JPEG decode.
  *
  * The returned dimensions are the ENCODED IMAGE's own, read back out of it — never the frame header's.
  * The header states the stream's geometry when the capture started, and a stream that reconfigures