@mega-yfue/eufy-sdk 0.0.4 → 0.1.0-beta.0

package/dist/transport/ff09.d.ts

@@ -0,0 +1,444 @@
+/**
+ * `ff09` frame encoder — the AES-128-CBC framed control protocol shared by every eufy device that
+ * takes a lock-style on/off actuation command (currently: the T8531 video smart lock and the T85D0
+ * garage door; likely other actuators later — see below).
+ *
+ * The command bytes are a self-contained `ff09…` frame, NOT a plain param write, and BOTH transports
+ * carry the exact same frame:
+ *  - **P2P** (`transport/p2p/command-router.ts`, T8531): wrapped in a `SET_PAYLOAD` (1350) envelope
+ *    whose inner `cmd` is `TRANSFER_PAYLOAD` (1940) and `payload` = `{apiCommand:6018,
+ *    lock_payload:"ff09…", seq_num, time}`.
+ *  - **MQTT** (`transport/mqtt/command-router.ts`, standalone/garage families): base64 of the identical
+ *    frame under the `trans` field.
+ *
+ * So cracking the frame solves both — this module builds ONLY the frame, nothing about either
+ * envelope, and sits at the transport root (like `ffmpeg.ts`) specifically so neither transport
+ * imports the other for it. Named after the wire frame, not the capability: the two current callers
+ * both happen to be locks, but nothing here is lock-specific beyond the {@link LOCK_COMMAND_CODE}
+ * opcode value itself — a future actuator (e.g. a curtain) reusing this wire would just be a new
+ * opcode constant, not a new encoder.
+ *
+ * ## Wire (verified byte-exact against captured T8531 lock+unlock frames)
+ *
+ * **Outer frame** (`lockPayload`, hex):
+ * ```
+ *   ff 09 | size(u16 LE) | 03(versionCode) 00(reserved) 02(dataType) | cmdEnc(u16 BE) | ct… | xorHash(1)
+ * ```
+ * `size` = total frame length incl. header + xor. `cmdEnc` = `0x4000 | commandCode` (bit 0x4000 =
+ * "encrypted payload"). `xorHash` = XOR of every preceding byte.
+ *
+ * **Inner plaintext** — an incrementing-separator TLV (`0xA1, 0xA2, …`, each `sep | len | bytes`),
+ * then **zero-padded to a 16-byte boundary** before AES (the app pads the buffer, so the real PKCS#7
+ * block AES adds is a full 0x10 block):
+ * ```
+ *   A1 04 <time u32 LE>            — freshness stamp
+ *   A2 <len> <admin_user_id ASCII> — the lock owner's id (40 hex chars)
+ *   A3 01 <lockByte>               — 0 = lock, 1 = unlock
+ *   A4 <len> <username ASCII>      — the acting user's display name (email local-part)
+ *   A5 <len> <short_user_id bytes> — the acting member's short id (hex→bytes, e.g. "0003")
+ * ```
+ *
+ * **Cipher**: AES-128-CBC + PKCS#7.
+ *  - key = `ASCII(admin_user_id[-12:])` (12 B) ‖ `uint32 BE(time)` (4 B) = 16 B.
+ *  - iv  = `ASCII(deviceSn)` zero-padded to 16 B (a 16-char SN is used verbatim).
+ *  - `time` is the nonce that makes each command's key differ; it is emitted CLEARTEXT in the
+ *    envelope `time` field so the lock can re-derive the key. The app computes it as
+ *    `floor(unixSec) | floor(random*100)` — the low bits are randomized. We reproduce that:
+ *    `keyTime = unixSec | nonce`, and the TLV `A1` stamp carries the un-noised `unixSec`.
+ *
+ * ## Settings GET/SET (T85D0 garage/lock auto-lock, 2026-07-16 capture — same cipher/frame family)
+ *
+ * Two more `apiCommand`/`commandCode` pairs on the SAME outer frame + cipher as above, verified
+ * byte-exact against a live GET query + a live GET response + two live SET writes (off→on) on a
+ * T85D0:
+ *  - **GET** (`LOCK_API_COMMAND.GET_SETTINGS` 6016 / `LOCK_COMMAND_CODE.GET_SETTINGS` 53/0x35,
+ *    {@link buildFf09QueryFrame}): plaintext is JUST `[A1 time][A2 adminUserId]` — no user-attribution
+ *    fields at all (narrower than even `omitUserFields`, which still keeps A3).
+ *  - **SET** (`LOCK_API_COMMAND.SET_SETTINGS` 6015 / `LOCK_COMMAND_CODE.SET_SETTINGS` 52/0x34,
+ *    {@link buildFf09SettingsFrame}): `[A1 time][A2 adminUserId][A3 1B][A4 1B enable][A5 2B LE delay-
+ *    seconds][A6 1B][A7 2B][A8 2B][A9 1B]`. `A3` is the same **setting-type selector** the Rain Mode
+ *    compact write uses (see below) — `0x00` selects auto-lock. `A4`-`A8` are now FULLY CONFIRMED
+ *    against the app's own JS (`smartLockSetParamsDataParse`'s `case 0`, carved from a live `/proc/mem`
+ *    dump, 2026-07-18 — not just a capture-derived guess): `A4`=`isAutoLock`, `A5`=`autoLockTime`
+ *    (seconds, LE u16), `A6`=`isSchedule` (bool), `A7`=`scheduleStartTime`, `A8`=`scheduleEndTime`.
+ *    `A7`/`A8` are each `[hourByte, minuteByte]` (the app encodes them as `hour.toString(16)‖
+ *    minute.toString(16)`, NOT a packed LE u16) — we still treat them as an opaque 2-byte passthrough
+ *    (read from a prior GET, written back unchanged), which stays correct either way since we never
+ *    interpret their contents, only preserve them. **`A9` is UNRESOLVED, not "confirmed reserved" —
+ *    the app's own `case 0` builder writes exactly 5 fields (`A4`-`A8`) and produces no 6th field at
+ *    all.** The original capture this encoder was built from showed a 6th real tagged byte
+ *    (`0xA9`, value `0x00`) after `A8`; two independent copies of the app's JS (including a newer
+ *    15-case build variant) agree there's no `A9` in `case 0`. This is a genuine, unresolved
+ *    discrepancy between the captured wire bytes and the decompiled source — not yet re-verified with
+ *    a fresh capture. Left as-is in the shipped encoder (still sends `A9=0x00`) since changing it
+ *    without a fresh capture risks breaking a live-verified write over an unconfirmed hypothesis; the
+ *    device has never rejected the extra field in any live test.
+ *  - **The device's `/res` reply to a GET** is NOT a normal command ack: no `mChannel`/`mValue3`/
+ *    `apiCommand`/`seq_num`, just `{cmd:1940, payload:{dev_sn, lock_payload, time}}` where `time` is a
+ *    **hex string** (not decimal) that equals the keyTime of the GET that triggered it — matched back
+ *    to the query to survive interleaved traffic. Its `cmdEnc` has an extra flag bit set vs. a request
+ *    (`0x48xx` not `0x40xx`) but decodes with the exact same key/iv derivation. Decrypted plaintext:
+ *    a leading `0x00` status byte, then TLV fields using the same `sep|len|bytes` encoding but the
+ *    response's OWN independent tag numbering (does not line up positionally with the GET/SET request
+ *    TLVs) — our own capture only ever showed `a1..ad` (13 fields, tags `0xa1`-`0xad`), but this is NOT
+ *    the auto-lock write's own reply scoped to auto-lock: **a single `GET_SETTINGS` reply is a FLAT
+ *    DUMP of the device's ENTIRE settings state**, one field per tag, covering every setting in the
+ *    `A3`/setting-type enum below (not just the one being written) — confirmed against
+ *    the app's own `smartLockGetParamsDataParse` (2026-07-18, same JS dump as the case-0 finding
+ *    above), which explicit-tag-reads (not sequentially, `getByteParam(<tag>)`/`getSecondParam(<tag>)`/
+ *    `getTimeParam(<tag>)`) THIRTY-FOUR fields, tags `0xa1` through `0xc2`:
+ *
+ *    | tag  | field                              | tag  | field                              |
+ *    |------|-------------------------------------|------|-------------------------------------|
+ *    | 0xa1 | `isAutoLock` **(current enable state — use THIS, not `A4`, to read it back)** | 0xb3 | *(read, unused in this build)* |
+ *    | 0xa2 | `autoLockTime` (= our `A5`/delay readback) | 0xb4 | *(read, unused in this build)* |
+ *    | 0xa3 | `isSchedule` (= our `A6`)           | 0xb5 | `isPowerSavingMode`                  |
+ *    | 0xa4 | `scheduleStartTime` (= our `A7` readback) | 0xb6 | `powerSavingModeStartTime`     |
+ *    | 0xa5 | `scheduleEndTime` (= our `A8` readback) | 0xb7 | `powerSavingModeEndTime`         |
+ *    | 0xa6 | `isOneTouchLock` (setting-type 1)   | 0xb8 | `keepAliveTime`                      |
+ *    | 0xa7 | `isScramblePasscode` (setting-type 3) | 0xb9 | `isOneTouchRearLock` (setting-type 11) |
+ *    | 0xa8 | `isWrongTryProtect` (setting-type 2) | 0xba | `multiFunctionBtnSinglePressMode` (12) |
+ *    | 0xa9 | `wrongTryTime`                      | 0xbb | `multiFunctionBtnDoublePressMode`    |
+ *    | 0xaa | `lockDownTime`                      | 0xbc | `multiFunctionBtnLongPressMode`      |
+ *    | 0xab | `lockVolume` (setting-type 4)        | 0xbd | `isSoundNotDisturbSchedule`          |
+ *    | 0xac | `wifiStatus` (setting-type 5)        | 0xbe | `soundNotDisturbScheduleStart`       |
+ *    | 0xad | `isEnableLog` (setting-type 6)        | 0xbf | `soundNotDisturbScheduleEnd`         |
+ *    | 0xae | `isRainMode` (setting-type 7)         | 0xc0 | `faceEnabled` (setting-type 13, default 1) |
+ *    | 0xaf | `isPassageMode` (setting-type 8)      | 0xc1 | `faceWakeType` (default 0)           |
+ *    | 0xb0 | `passageModeStartTime`               | 0xc2 | `fingerprintEnabled` (default 1)     |
+ *    | 0xb1 | `passageModeEndTime`                 |      |                                       |
+ *    | 0xb2 | `isPrivacyMode` (setting-type 9)      |      |                                       |
+ *
+ *    `a6` is `isOneTouchLock`, an entirely different setting, which is why it never moves with
+ *    auto-lock's own on/off state — the REAL current-enable-state field is `a1` (our own
+ *    `parseFf09SettingsResponse` already parses it correctly; it is simply not READ by
+ *    `sendFf09Autolock`/`dispatchFf09Autolock`, which only pull `a2`/`a4`/`a5`). Not yet
+ *    wired into any code path — flagged here as a documented opportunity, not a shipped read.
+ *    See {@link decryptFf09Frame} + {@link parseFf09SettingsResponse}.
+ *  - **Also live-verified on the T8531 over P2P** (2026-07-18): the same GET/SET frame shape, live-
+ *    captured off the P2P wire and confirmed byte-identical in structure to the T85D0 capture above
+ *    (same key derivation, same TLV layout, `A5`'s captured value there was 120s/"2 min" vs. this
+ *    doc's 90s/"1.5 min" — different device, same field semantics). `dev.lock()?.setAutoLock()` driven
+ *    end-to-end through the P2P command router against a real T8531, both directions confirmed via the
+ *    app UI — not just byte-exact against a capture. See `transport/p2p/command-router.ts`'s
+ *    `sendFf09Autolock`.
+ *
+ * ## Rain Mode (T8531, 2026-07-18 capture — a SECOND, shorter `SET_SETTINGS` shape)
+ *
+ * Same `apiCommand`/`commandCode` pair as the auto-lock SET above (6015/52), but a genuinely different,
+ * SHORTER plaintext — captured live off the P2P wire toggling Rain Mode off→on: `[A1 time]
+ * [A2 adminUserId][A3 1B settingId][A4 1B value]`, nothing past `A4` (no `A5`-`A9` at all). `A3` here
+ * is NOT the unconfirmed constant from the full-blob write above — it's a setting-id SELECTOR (`0x07`
+ * for Rain Mode), making this a compact single-setting write rather than a read-modify-write of a fixed
+ * blob. Because it doesn't touch any field besides the one being set, it's a pure blind write — no GET
+ * pass needed first. See {@link FF09_SETTING_ID} + {@link buildFf09SettingToggleFrame}. The `A3`
+ * selector addresses at least 14 T8531 settings — the app's own decompiled JS
+ * (`smartLockSetParamsDataParse`, 2026-07-18) confirmed the id→setting map; `RAIN_MODE` is the only one
+ * independently WIRE-CAPTURED so far, and 6 more (one-touch lock/scramble/wifi/enable-log/privacy/
+ * one-touch-rear) are wired but THROW "wire unverified" until each clears that bar — see
+ * {@link FF09_SETTING_ID} for the full id list.
+ * ✅ LIVE-VERIFIED end-to-end (2026-07-18): `dev.lock()?.setRainMode()` driven through the P2P command
+ * router against a real T8531, both directions (off→on and on→off) confirmed via the app UI showing
+ * the new state afterward — not just byte-exact against a capture. See
+ * `transport/p2p/command-router.ts`'s `sendFf09SettingToggle`.
+ */
+import type { AutoLockSnapshot } from "../core/contracts.js";
+/**
+ * `apiCommand` values for the `TRANSFER_PAYLOAD` (1940) envelope `payload`. `ON_OFF_LOCK` (6018)
+ * is THE lock/unlock command for both the video lock (T8531) and the garage door (T85D0) — proven
+ * end-to-end against a T8531 (unlock/lock/unlock/lock capture) and, 2026-07-16, against the garage
+ * door too (2 independent live captures of the real app closing it, both `apiCommand 6018`, matching
+ * eufy-sdk's own already-verified open path). Direction is the ff09 frame's `A3` byte, not the
+ * apiCommand: both lock and unlock issue `apiCommand 6018`.
+ */
+export declare const LOCK_API_COMMAND: {
+    /** Lock / unlock the deadbolt — video lock AND garage door, both directions (see above). */
+    readonly ON_OFF_LOCK: 6018;
+    /**
+     * NOT used by this encoder — kept only as a real, observed constant. `apiCommand 6012` genuinely
+     * appears in live traffic (captured from a real but UNIDENTIFIED iOS app instance on the same
+     * account, 2026-07-16), but sending it from eufy-sdk never once produced a physical actuation in
+     * several live tests. The app's own `ESLCommand` enum (carved from a live `/proc/mem` dump,
+     * 2026-07-18) names 6012 `QUERY_STATUS_IN_LOCK` — a read-only status POLL, not an actuator at all,
+     * which is exactly why it never once opened/closed anything. The name `OPEN_DOOR` is a misnomer,
+     * kept as-is to avoid API churn on a constant that is not usable — do not use it for open, close, or
+     * a status read (this encoder has no query-status support; `GET_SETTINGS`/6016 is the only supported
+     * read path).
+     */
+    readonly OPEN_DOOR: 6012;
+    /** Read the current auto-lock/settings TLV — {@link buildFf09QueryFrame}. Verified live 2026-07-16. */
+    readonly GET_SETTINGS: 6016;
+    /** Write the auto-lock/settings TLV — {@link buildFf09SettingsFrame}. Verified live 2026-07-16. */
+    readonly SET_SETTINGS: 6015;
+};
+/**
+ * `commandCode` values encoded into the `ff09` frame's `cmdEnc` field (`0x4000 | commandCode`).
+ * `ON_OFF_LOCK` (35 = 0x23 → cmdEnc 0x4023) is lock/unlock — video lock AND garage door, both
+ * directions. Distinct from {@link LOCK_API_COMMAND}: this is the inner frame opcode, that is the
+ * outer envelope's `apiCommand`.
+ */
+export declare const LOCK_COMMAND_CODE: {
+    /** Lock / unlock the deadbolt (inner frame opcode) — video lock + garage door, both directions. */
+    readonly ON_OFF_LOCK: 35;
+    /** NOT used by this encoder — see {@link LOCK_API_COMMAND.OPEN_DOOR}; kept as an observed constant only. */
+    readonly OPEN_DOOR: 34;
+    /** Settings GET inner opcode (53 = 0x35 → cmdEnc 0x4035) — see {@link buildFf09QueryFrame}. */
+    readonly GET_SETTINGS: 53;
+    /** Settings SET inner opcode (52 = 0x34 → cmdEnc 0x4034) — see {@link buildFf09SettingsFrame}. */
+    readonly SET_SETTINGS: 52;
+};
+/** The `TRANSFER_PAYLOAD` inner-command id both envelopes carry (P2P `SET_PAYLOAD.cmd` / MQTT `trans.cmd`). */
+export declare const CMD_TRANSFER_PAYLOAD = 1940;
+export interface Ff09FrameInput {
+    /** Actuation direction — the `A3` byte: `true` = engage (byte 0, lock/close), `false` = release (byte 1, unlock/open). */
+    engage: boolean;
+    /** The lock owner's account id (`member.admin_user_id`, 40 hex chars) — drives the key + `A2`. */
+    adminUserId: string;
+    /** The acting user's display name (the login email's local-part) — the `A4` field. Omitted when {@link omitUserFields}. */
+    username?: string;
+    /** The acting member's short id (`member.short_user_id`, hex, e.g. `"0003"`) — the `A5` field. Omitted when {@link omitUserFields}. */
+    shortUserId?: string;
+    /**
+     * Skip the user-attribution TLV fields (A4 username, A5 shortUserId). ✅ The garage-door OPEN command
+     * (`apiCommand 6012` / opcode 34) omits them — its plaintext is just `[A1 time, A2 adminUserId, A3 byte]`
+     * — verified byte-exact from a live capture. Lock/unlock + garage CLOSE keep them (default false).
+     */
+    omitUserFields?: boolean;
+    /** The lock's serial number — the AES IV (zero-padded to 16). */
+    deviceSn: string;
+    /** Override the unix-seconds stamp (testing / byte-exact reproduction). Default = now. */
+    unixTime?: number;
+    /** Override the key-time nonce OR'd into `unixTime` (testing). Default = a random 0..99. */
+    nonce?: number;
+    /** Override the envelope `seq_num` (testing). Default = `unixTime`. */
+    seqNum?: number;
+}
+export interface Ff09Frame {
+    /** The `ff09…` frame, hex — goes verbatim into the envelope `lock_payload` (P2P) or `trans` (MQTT). */
+    lockPayload: string;
+    /** The cleartext `time` the envelope must carry so the device re-derives the key. */
+    time: number;
+    /** The envelope `seq_num`. */
+    seqNum: number;
+    /**
+     * The `apiCommand` the envelope must carry for THIS frame (the `TRANSFER_PAYLOAD` `payload.apiCommand`
+     * — see {@link LOCK_API_COMMAND}). Returned by the builder so neither transport has to know the
+     * frame↔apiCommand pairing: the P2P/MQTT envelope just carries it through. Distinct from the inner
+     * frame `commandCode` the builder also picks internally.
+     */
+    apiCommand: number;
+}
+/**
+ * The `TRANSFER_PAYLOAD` (1940) `payload` object both transports carry for an ff09 frame. The index
+ * signature keeps it assignable to the routers' generic `Record<string, unknown>` envelope-body param
+ * (every field is already `number | string`).
+ */
+export interface Ff09TransferPayload {
+    apiCommand: number;
+    lock_payload: string;
+    seq_num: number;
+    time: number;
+    [field: string]: number | string;
+}
+/**
+ * Project a built {@link Ff09Frame} into the `TRANSFER_PAYLOAD` (1940) `payload` — the ONE place the
+ * frame→envelope field mapping (`lockPayload`→`lock_payload`, `seqNum`→`seq_num`) lives, so neither the
+ * P2P router (`set-payload` body) nor the MQTT router (`trans.payload`) re-spells it.
+ */
+export declare function ff09TransferPayload(frame: Ff09Frame): Ff09TransferPayload;
+/**
+ * Build an `ff09` command frame. Deterministic given `unixTime`/`nonce`/`seqNum`, so a test can
+ * reproduce a captured frame byte-for-byte; otherwise it stamps a fresh `time` per call.
+ *
+ * Throws on missing identity (empty `adminUserId`/`shortUserId`/`deviceSn`) — an all-empty field would
+ * silently produce a frame the device rejects, and both transports send this fire-and-forget (no
+ * error comes back), so we fail loud here instead.
+ */
+export declare function buildFf09Frame(input: Ff09FrameInput): Ff09Frame;
+export interface Ff09QueryFrameInput {
+    /** The lock owner's account id (`member.admin_user_id`, 40 hex chars) — drives the key + `A2`. */
+    adminUserId: string;
+    /** The lock's serial number — the AES IV (zero-padded to 16). */
+    deviceSn: string;
+    /** Override the unix-seconds stamp (testing / byte-exact reproduction). Default = now. */
+    unixTime?: number;
+    /** Override the key-time nonce OR'd into `unixTime` (testing). Default = a random 0..99. */
+    nonce?: number;
+    /** Override the envelope `seq_num` (testing). Default = `unixTime`. */
+    seqNum?: number;
+}
+/**
+ * Build the settings **GET** query frame (`LOCK_COMMAND_CODE.GET_SETTINGS`) — plaintext is just
+ * `[A1 time][A2 adminUserId]`, no user-attribution fields (narrower than `omitUserFields` on
+ * {@link buildFf09Frame}, which still keeps A3). See the module doc's "Settings GET/SET" section.
+ */
+export declare function buildFf09QueryFrame(input: Ff09QueryFrameInput): Ff09Frame;
+export interface Ff09SettingsFrameInput {
+    /** The lock owner's account id (`member.admin_user_id`, 40 hex chars) — drives the key + `A2`. */
+    adminUserId: string;
+    /** The lock's serial number — the AES IV (zero-padded to 16). */
+    deviceSn: string;
+    /** `A4` — auto-lock enable (confirmed semantics). */
+    autoLockEnabled: boolean;
+    /** `A5` (u16 LE) — auto-lock delay in seconds (confirmed semantics; captured value 90 = "1.5 min"). */
+    autoLockDelaySeconds: number;
+    /**
+     * `A7` (u16 LE) — semantics UNCONFIRMED, but the value IS readable back from a GET response
+     * (response field `a4`), so callers should pass through a just-read current value rather than a
+     * guess. See the module doc's "Settings GET/SET" section.
+     */
+    a7: number;
+    /** `A8` (u16 LE) — same caveat as {@link a7} (readable back as GET response field `a5`). */
+    a8: number;
+    /** Override the unix-seconds stamp (testing / byte-exact reproduction). Default = now. */
+    unixTime?: number;
+    /** Override the key-time nonce OR'd into `unixTime` (testing). Default = a random 0..99. */
+    nonce?: number;
+    /** Override the envelope `seq_num` (testing). Default = `unixTime`. */
+    seqNum?: number;
+}
+/**
+ * Build the settings **SET** frame (`LOCK_COMMAND_CODE.SET_SETTINGS`) — plaintext is `[A1 time]
+ * [A2 adminUserId][A3 1B][A4 1B enable][A5 2B LE delay][A6 1B][A7 2B LE][A8 2B LE][A9 1B]`. `A3`/`A6`/
+ * `A9` are sent as the literal `0x00` observed in the one capture available (semantics unconfirmed —
+ * see the module doc). `A7`/`A8` are NOT hardcoded here — the caller (the read-modify-write orchestration
+ * in the client) is expected to pass through values just read from a GET response.
+ */
+export declare function buildFf09SettingsFrame(input: Ff09SettingsFrameInput): Ff09Frame;
+/**
+ * Setting-id selectors for the COMPACT single-setting `SET_SETTINGS` write ({@link
+ * buildFf09SettingToggleFrame}) — a SHORTER TLV than the full-blob write ({@link buildFf09SettingsFrame},
+ * which always sends `A3=0x00` plus all of `A4`-`A9` together for auto-lock). Captured live on a T8531
+ * (2026-07-18): toggling Rain Mode off→on produced just `[A1 time][A2 adminUserId][A3=0x07][A4 0/1]` —
+ * nothing past `A4`, and `A3` here is a setting-id SELECTOR rather than an unconfirmed constant. The
+ * app's own decompiled JS (2026-07-18) mapped the full selector enum (≥14 settings); `RAIN_MODE` is the
+ * only one independently wire-captured, the other 6 ids below ship throwing "wire unverified" pending
+ * their own capture. See the module doc's "Rain Mode" section.
+ *
+ * NOT consulted by {@link buildFf09SettingToggleFrame} or anything else on the production path — the
+ * wire byte actually comes from the `Command`'s opaque `settingId` field, sourced from `model/`'s OWN
+ * copy (`lock.ts`'s `LOCK_SETTING_ID.RAIN_MODE`, per the capability↔transport decorrelation rule this
+ * module's doc already covers). This constant is layer-local wire vocab for THIS file's own callers/
+ * spec only — it documents the value but carries no production reference, so it can't structurally
+ * catch the two copies drifting apart; see `lock.ts`'s doc for that caveat.
+ */
+export declare const FF09_SETTING_ID: {
+    /** One-touch lock toggle. Structurally confirmed via the app's own JS (2026-07-18) — not independently wire-captured. */
+    readonly ONE_TOUCH_LOCK: 1;
+    /** Scramble-passcode toggle. Structurally confirmed via the app's own JS (2026-07-18) — not independently wire-captured. */
+    readonly SCRAMBLE_PASSCODE: 3;
+    /** Wifi-status toggle. Structurally confirmed via the app's own JS (2026-07-18) — not independently wire-captured. */
+    readonly WIFI_STATUS: 5;
+    /** Event-log-enable toggle. Structurally confirmed via the app's own JS (2026-07-18) — not independently wire-captured. */
+    readonly ENABLE_LOG: 6;
+    /** Rain Mode toggle on the T8531 video lock. `A4` = 0 off / 1 on. Verified live 2026-07-18. */
+    readonly RAIN_MODE: 7;
+    /** Privacy-mode toggle. Structurally confirmed via the app's own JS (2026-07-18) — not independently wire-captured. */
+    readonly PRIVACY_MODE: 9;
+    /** One-touch rear-lock toggle. Structurally confirmed via the app's own JS (2026-07-18) — not independently wire-captured. */
+    readonly ONE_TOUCH_REAR_LOCK: 11;
+};
+export interface Ff09SettingToggleFrameInput {
+    /** The lock owner's account id (`member.admin_user_id`, 40 hex chars) — drives the key + `A2`. */
+    adminUserId: string;
+    /** The lock's serial number — the AES IV (zero-padded to 16). */
+    deviceSn: string;
+    /** Which setting this write targets — the `A3` field. See {@link FF09_SETTING_ID}. */
+    settingId: number;
+    /** The new value — the `A4` field (0/1). */
+    value: boolean;
+    /** Override the unix-seconds stamp (testing / byte-exact reproduction). Default = now. */
+    unixTime?: number;
+    /** Override the key-time nonce OR'd into `unixTime` (testing). Default = a random 0..99. */
+    nonce?: number;
+    /** Override the envelope `seq_num` (testing). Default = `unixTime`. */
+    seqNum?: number;
+}
+/**
+ * Build the settings **SET** frame using the COMPACT single-setting shape (`LOCK_COMMAND_CODE.SET_SETTINGS`,
+ * same opcode as {@link buildFf09SettingsFrame}) — plaintext is just `[A1 time][A2 adminUserId]
+ * [A3 1B settingId][A4 1B value]`, no `A5`-`A9` at all. Unlike the full-blob write, this is a pure blind
+ * write — no GET-then-preserve is needed since it doesn't touch any field the device isn't being told to
+ * change. See the module doc's "Rain Mode" section + {@link FF09_SETTING_ID}.
+ */
+export declare function buildFf09SettingToggleFrame(input: Ff09SettingToggleFrameInput): Ff09Frame;
+/**
+ * Decrypt any `ff09` response frame (e.g. the GET-settings reply) back to its plaintext TLV bytes.
+ * Same key/iv derivation as the encoder (`adminUserId.slice(-12) ‖ u32be(keyTime)` / `deviceSn` padded
+ * 16), but normal PKCS#7 unpadding (`createDecipheriv` with auto-padding ON) — unlike the encoder,
+ * which zero-pads its OWN plaintext before letting AES add a genuine PKCS#7 block on top, a device
+ * response is a plain PKCS#7-padded ciphertext with no extra zero-padding layer.
+ *
+ * Validates the `ff09` magic and the trailing XOR checksum (the frame's own self-check), but does NOT
+ * validate `cmdEnc` beyond that — a response's `cmdEnc` carries an extra flag bit vs. a request's
+ * (`0x48xx` not `0x40xx`) and this decoder is generic across whatever inner opcode it's carrying.
+ *
+ * `keyTime` is the response envelope's `time` field parsed as the hex string it actually is (NOT
+ * decimal, unlike the `seq_num`/other envelope fields) — see the module doc.
+ */
+export declare function decryptFf09Frame(input: {
+    lockPayload: string;
+    keyTime: number;
+    adminUserId: string;
+    deviceSn: string;
+}): Buffer;
+/** A decoded settings-response TLV: the leading status byte + the `a1..ad` fields, keyed by separator byte. */
+export interface Ff09SettingsResponse {
+    /** The leading status byte (byte 0 of the decrypted plaintext, before the TLV fields). */
+    status: number;
+    /** `sep` (e.g. `0xa2`) → field bytes. The response's own tag numbering — does NOT line up positionally
+     * with the GET/SET request TLVs (see the module doc). */
+    fields: Map<number, Buffer>;
+}
+/**
+ * Parse a decrypted settings-response plaintext ({@link decryptFf09Frame}'s output) into its leading
+ * status byte + `sep|len|bytes` TLV fields. Stops at a `0x00` separator (real tags start at `0xa1`;
+ * a `0x00` sep only ever shows up as trailing zero-padding, never a real field) so it doesn't choke on
+ * padding past the last real field.
+ */
+export declare function parseFf09SettingsResponse(plain: Buffer): Ff09SettingsResponse;
+/** Read a little-endian u16 out of a TLV field buffer (throws on a missing/short field — a caller-side bug, not a wire ambiguity). */
+export declare function readFf09U16LE(field: Buffer | undefined, name: string): number;
+/** Read a single byte out of a TLV field buffer (throws on a missing field — same convention as {@link readFf09U16LE}). */
+export declare function readFf09U8(field: Buffer | undefined, name: string): number;
+/**
+ * Read a 2-byte `[hour, minute]` time pair out of a TLV field buffer — the app encodes schedule times
+ * as `hour.toString(16)‖minute.toString(16)` (two raw byte VALUES, not a packed LE u16 — see the
+ * module doc's "Settings GET/SET" section). Throws on a missing/short field, same convention as
+ * {@link readFf09U16LE}.
+ */
+export declare function readFf09HourMinute(field: Buffer | undefined, name: string): [number, number];
+/**
+ * Decode a parsed `GET_SETTINGS` response into the auto-lock snapshot both transports return from
+ * `getAutoLockState` — the response tag map's `a1`=enabled, `a2`=delaySeconds, `a3`=isSchedule,
+ * `a4`/`a5`=schedule start/end (`[hour,minute]`). Shared here (rather than copied into each router's
+ * `getAutoLockState`) so the P2P and MQTT read paths can't drift on the field mapping.
+ */
+export declare function decodeFf09AutoLockSnapshot(parsed: Ff09SettingsResponse): AutoLockSnapshot;
+/**
+ * Coerce a settings-response `time` field back to the numeric keyTime, for matching the reply against
+ * the GET's own keyTime. Shared by both transports' autolock GET-reply matchers. A string is parsed
+ * base-16 (the reply `time` is a hex string on the working, test-backed path — `ff09-mqtt-settings-
+ * dispatch.spec` drives the full GET→decrypt→SET flow with a `time.toString(16)` reply); a JSON number
+ * is taken as the value directly (unambiguous). A *decimal string* is deliberately NOT handled — it's
+ * indistinguishable from hex and never observed on the wire, so parsing an all-digit decimal as hex
+ * would silently mis-match. Returns the keyTime, or `undefined` if it doesn't parse to a finite number.
+ */
+export declare function ff09ReplyKeyTime(rawTime: string | number): number | undefined;
+/**
+ * The read-modify-write core of an auto-lock settings write, shared by both transports' autolock
+ * dispatchers ({@link buildFf09QueryFrame} GET → this → send): decrypt the GET-settings reply, pull the
+ * current delay + `A7`/`A8` passthrough values off it, and build the SET frame that changes only
+ * enable/delay while preserving everything else. The transport owns getting the reply (its own GET wire
+ * + reply match) and wrapping/sending the returned frame; the decrypt→read→rebuild sequence lives here
+ * once so the two routers can't drift (e.g. the pending `a2`/`a4`/`a5`→`a1` enable-readback fix the
+ * module doc flags is then a one-place change).
+ */
+export declare function buildFf09AutolockSetFrame(input: {
+    lockPayload: string;
+    keyTime: number;
+    adminUserId: string;
+    deviceSn: string;
+    enabled: boolean;
+    delaySeconds?: number;
+}): Ff09Frame;

package/dist/transport/ffmpeg.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared `ffmpeg` spawn helper — the ONE place that shells out to ffmpeg. It decides ffmpeg's own
+ * verbosity, prepends the common flags, and routes stderr into the SDK's {@link Logger}, so no caller
+ * touches `spawn("ffmpeg", …)` directly. Used by the media paths that mux via ffmpeg (`p2p/media.ts`
+ * snapshot/record). Not byte-on-a-wire, so it sits at the transport root
+ * rather than in a wire subfolder.
+ *
+ * Two independent dials:
+ *   - **ffmpeg verbosity** — how chatty ffmpeg itself is, via `-loglevel`, from the host's
+ *     `new EufyMega({ ffmpegLogLevel })` config (default `"error"`).
+ *   - **where it lands** — the host {@link Logger} and its own min-level gate what's actually shown.
+ *
+ * So `new EufyMega({ ffmpegLogLevel: "trace", logger: new ConsoleLogger() })` surfaces ffmpeg's full
+ * trace at `[ffmpeg]` debug lines; the default level + no logger stays silent.
+ *
+ * WHICH binary runs is a third, orthogonal dial: `new EufyMega({ ffmpegPath })`. See
+ * {@link ffmpegExecutable} — the SDK never edits the process `PATH`, so an explicit path is what names
+ * a binary that is not on it.
+ *
+ * @module transport/ffmpeg
+ */
+import { type ChildProcess, type StdioOptions } from "node:child_process";
+import { type Logger } from "../core/logger.js";
+/**
+ * ffmpeg's `-loglevel` values, quiet → loud. `trace` is the firehose.
+ *
+ * Exported as the set in data form; not published — `FfmpegLevel` states the same members.
+ * @internal
+ */
+export declare const FFMPEG_LEVELS: readonly ["quiet", "panic", "fatal", "error", "warning", "info", "verbose", "debug", "trace"];
+/** A valid ffmpeg `-loglevel`. Set via `new EufyMega({ ffmpegLogLevel })`. */
+export type FfmpegLevel = (typeof FFMPEG_LEVELS)[number];
+/**
+ * Resolve ffmpeg's own verbosity from the SDK config a host passes (`new EufyMega({ ffmpegLogLevel })`),
+ * defaulting to `"error"` (quiet); an unset/invalid value yields the default. This is ffmpeg's
+ * `-loglevel`, NOT the SDK's {@link LogLevel} — the two are orthogonal (ffmpeg decides what to emit,
+ * the Logger decides what's shown).
+ */
+export declare function ffmpegLogLevel(level?: FfmpegLevel): FfmpegLevel;
+/**
+ * Resolve WHICH ffmpeg to run from the SDK config a host passes (`new EufyMega({ ffmpegPath })`),
+ * defaulting to the bare name `"ffmpeg"` so it is looked up on `PATH`.
+ *
+ * An environment where no `ffmpeg` is on `PATH` is ordinary, and the SDK never mutates
+ * `process.env.PATH` process-wide to reach one — this option is how such a binary is named.
+ *
+ * A **blank** value counts as absent: an unset host config commonly arrives as `""` or as whitespace
+ * from a config file, and neither can name a binary, so spawning it would fail as an `ENOENT` on the
+ * empty string — the misleading message this option exists to remove. Any non-blank value is passed
+ * through EXACTLY as given, never trimmed: a leading or trailing space is legal in a POSIX path, and
+ * rewriting one would make a real file unreachable.
+ *
+ * The value is NOT probed here. Spawn failure surfaces to the caller as the media path's own "not
+ * runnable" rejection, which is the same signal a missing `PATH` entry gives, so there is nothing for
+ * an extra `stat` to add. {@link ffmpegAvailable} is the probe.
+ */
+export declare function ffmpegExecutable(path?: string): string;
+/**
+ * Spawn ffmpeg. Prepends `-hide_banner` + the env-driven `-loglevel` (see {@link ffmpegLogLevel}) to
+ * `args`, then forwards the child's stderr to `logger.debug` under an `[ffmpeg]` prefix — the logger's
+ * min-level gates visibility, so a `noopLogger` (the default) swallows it. Callers pass only their
+ * ffmpeg-specific args and read stdin/stdout off the returned child.
+ *
+ * `stdio` defaults to all-pipe; pass e.g. `["pipe", "ignore", "pipe"]` to drop stdout (stderr must
+ * stay piped for forwarding to work). `level` overrides the resolved `-loglevel` (see
+ * {@link ffmpegLogLevel} for precedence); `executable` picks the binary (see
+ * {@link ffmpegExecutable}).
+ */
+export interface FfmpegSpawnOptions {
+    logger?: Logger;
+    stdio?: StdioOptions;
+    level?: FfmpegLevel;
+    /** The ffmpeg binary to run. Default: the bare name, looked up on `PATH`. */
+    executable?: string;
+}
+export declare function spawnFfmpeg(args: string[], opts?: FfmpegSpawnOptions): ChildProcess;
+/**
+ * Whether the resolved ffmpeg is runnable, by running `-version` on it. Resolves the executable exactly
+ * as the media paths do, so the answer is about the SAME binary they will launch.
+ */
+export declare function ffmpegAvailable(executable?: string): boolean;
+/**
+ * Whether `ffprobe` is on `PATH`. The SDK never spawns it, so there is no executable to resolve and
+ * none is taken.
+ */
+export declare function ffprobeAvailable(): boolean;

package/dist/transport/http/decodeImageV1.d.ts

@@ -0,0 +1,20 @@
+export declare const V1_PREFIX = "eufysecurity";
+/** Derive the numeric id-suffix from the station `p2p_did` — a digit-mixing seed used by the key derivation. */
+export declare function getIdSuffix(p2pDid: string): number;
+/** Derive the image "base code" from the camera serial + `p2p_did` — first input to {@link getImageKey}. */
+export declare function getImageBaseCode(serialNumber: string, p2pDid: string): string;
+/** Derive the per-image seed from the `p2p_did` + the image's own code — second input to {@link getImageKey}. */
+export declare function getImageSeed(p2pDid: string, code: string): string;
+/** Derive the AES-128-ECB key for a v1 thumbnail: SHA-256 over the base code + seed, rotated by a hash byte. */
+export declare function getImageKey(serialNumber: string, p2pDid: string, code: string): string;
+/** True if the blob is a legacy v1 `eufysecurity:` image (NOT the v2 variant). */
+export declare function isV1Image(data: Buffer): boolean;
+/**
+ * Decode a v1 `eufysecurity:` blob to a plain JPEG buffer using the station's
+ * `p2p_did`. Returns null if the blob isn't v1. Mirrors the legacy decode: parse
+ * SERIAL + CODE, derive the key, AES-128-ECB-decrypt the first 256 bytes, splice
+ * the decrypted head back in front of the plaintext tail.
+ */
+export declare function decodeImageV1(data: Buffer, p2pDid: string): Buffer | null;
+/** Decode a recognized v1 (device-key) or v2 (keyless) wrapper; leave other media unchanged. */
+export declare function normalizePushImage(data: Buffer, p2pDid?: string): Buffer;

package/dist/transport/http/decodeImageV2.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-channel auto-contrast, a byte-exact port of PIL `ImageOps.autocontrast` (cutoff 0.5%). The lost
+ * quant tables leave the reconstruction low-contrast ("foggy"); stretching each channel's clipped range
+ * to full scale restores a natural-looking image. Mutates `data` (RGBA) in place.
+ *
+ * Parity notes vs PIL: the cutoff count is `n * cutoff // 100` (integer floor); it is trimmed off each
+ * end by zeroing whole histogram bins until the count is spent; the range is then the first/last
+ * non-empty bins; and the LUT truncates toward zero (`int()`), NOT rounds — rounding would shift pixels.
+ */
+export declare function autoContrast(data: Uint8Array, width: number, height: number, cutoff?: number): void;
+/** True if the blob is a v2 `v2_eufysecurity:` push thumbnail. */
+export declare function isV2Image(data: Buffer): boolean;
+/**
+ * Decode a v2 blob to a plain JPEG buffer by reconstructing its header, or null if it isn't v2 or the
+ * plaintext scan can't be located. The search first chooses subsampling and coarse geometry, derives
+ * the fixed MCU count, refines width by row shear, and pins the exact fill height before applying
+ * auto-contrast and re-encoding. See the module doc for the keyless-splice rationale.
+ */
+export declare function decodeImageV2(data: Buffer): Buffer | null;

package/dist/transport/http/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./mega-client.js";
+export { randomPhoneModel, randomUserAgent } from "./phone-model.js";
+export * from "./decodeImageV1.js";
+export * from "./decodeImageV2.js";
+export { listLightEffects, listAiSceneRecommendations, type LightEffectSummary } from "./light-catalog.js";

package/dist/transport/http/light-catalog.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Light-effect **catalogue** over the vendor's `light` HTTP service — `/app/light/discover/list`,
+ * `/app/light/lighteffect/batchget` and `/app/light/aigc/recommend/list`, with their response parsing.
+ * `light` here is the service path the vendor publishes, which is why this sits with the rest of the
+ * HTTP surface.
+ *
+ * This module fetches a catalogue definition; `transport/dp-preset.ts` turns one into wire fields, and
+ * sits at the transport root because both this and the MQTT router serialize through it.
+ *
+ * The catalogue is keyed by numeric id throughout and carries no model vocabulary.
+ */
+import type { MegaHttpClient } from "./mega-client.js";
+import type { DpPresetSpec } from "../dp-preset.js";
+/**
+ * One entry in the light-effect gallery — the browsable catalogue behind {@link listLightEffects}.
+ * `buildable` says whether the entry's definition can be turned into wire fields at all: false when it
+ * carries no layers, or a layer shape this SDK cannot encode.
+ */
+export interface LightEffectSummary {
+    /** The catalogue id that identifies this effect on the wire. */
+    lightId: number;
+    /** Display name from the catalogue (e.g. "Presidents Day"), when present. */
+    name?: string;
+    /** Preview swatch — `"RRGGBB|RRGGBB…"` — when the catalogue entry carries one. */
+    colors?: string;
+    /** Whether this entry can be serialized to wire fields. */
+    buildable: boolean;
+}
+/**
+ * Browse the light-effect gallery — the catalogue of `lightId`s that `setEffect` accepts. Unions every
+ * scene/light id found anywhere in the `/app/light/discover/list` carousel (walked recursively) with a
+ * scan over the default `LIGHT_EFFECT_ID_WINDOW` (the dense id band holding the app's category tabs) plus any
+ * `ids` given, then resolves them via `/app/light/lighteffect/batchget` (which returns an entry only
+ * for ids that exist). Pass `idRange` to widen/narrow the scan or `ids` to fetch specific ones.
+ *
+ * `batchget` is issued in chunks of `BATCHGET_CHUNK` (100) ids — the scanned set runs to the hundreds,
+ * so one request does not swallow it whole.
+ */
+export declare function listLightEffects(mega: MegaHttpClient, opts?: {
+    idRange?: [number, number];
+    ids?: number[];
+}): Promise<LightEffectSummary[]>;
+/**
+ * List the **AI-generated ambient scenes** ("aigc") — e.g. "Enchanting Starry Night", "Moonlit
+ * Serenity". A DIFFERENT resource from {@link listLightEffects}'s id-addressable catalogue:
+ * `/app/light/aigc/recommend/list` returns scene **keywords only, with NO `lightId`**, so they can't be
+ * driven through `setEffect` — the app turns a chosen keyword into an applied effect via a server-side
+ * generate step the SDK hasn't reversed yet. Surfaced for visibility. Needs a `region` (400s
+ * without one) and, for some accounts, a device `sn`; `region` defaults to `"eu"` (the endpoint
+ * returned an identical list across every shard tried).
+ */
+export declare function listAiSceneRecommendations(mega: MegaHttpClient, opts?: {
+    region?: string;
+    sn?: string;
+}): Promise<string[]>;
+/**
+ * Fetch a gallery effect by exact catalog `lightId` and parse it into the {@link DpPresetSpec} the
+ * MQTT router serializes — the "Auto inside setEffect" resolution. Matches the EXACT id (never
+ * substitutes a neighbour — the DP write is fire-and-forget). Only effects with directly-serializable
+ * `params.layer` data are supported; flat/grouped entries throw a clear error rather than emit a guess.
+ */
+export declare function resolveLightEffect(mega: MegaHttpClient, lightId: number): Promise<DpPresetSpec>;