sesame-kit 0.4.0

package/src/ble/protocol.js

@@ -0,0 +1,319 @@
+// SESAME BLE プロトコル — 純 JS のコア (OS 非依存・ゼロ追加依存)。
+//
+// 移植元 (1:1、行番号は調査仕様書準拠):
+//   - ESP32 C 実装: references_esp32/main/sesame/{ssm.c, ssm_cmd.c}, utils/{c_ccm.c, aes-cbc-cmac.c}
+//   - Android SDK : references_android/.../ble/{SesameProtocols.kt, SesameBleReceiver.kt},
+//                   ble/os3/base/{CHSesameOS3.kt, SesameOS3BleCipher.kt}, open/devices/base/CHSesameOS3LockBase.kt
+//
+// 対象は SesameOS3 (SESAME 5 / 5 Pro / Touch 等)。OS2 (SESAME 3/4/Bot) は対象外 (鍵導出・nonce 長が別)。
+//
+// この層は「接続後のバイト列」だけを扱う純関数群。BLE 無線 I/O (scan/connect/write/notify) は
+// transport アダプタの責務で、ここには一切含めない (= どの OS / ライブラリでも動く)。
+
+import crypto from "node:crypto";
+import { Buffer } from "node:buffer";
+import { aesCmac } from "node-aes-cmac";
+import { ITEM_CODES } from "../itemcodes.js";
+
+// ---------- 定数 ----------
+
+/** GATT (blecent.c:13-15 / SesameProtocols.kt:80-83)。 */
+export const GATT = Object.freeze({
+  SERVICE: "fd81",
+  WRITE_CHAR: "16860002-a5ae-9856-b6d3-dbb4c676993e", // RX (app→device, Write Without Response)
+  NOTIFY_CHAR: "16860003-a5ae-9856-b6d3-dbb4c676993e", // TX (device→app, notify)
+});
+
+/** advertise の company ID (LE 5A 05 = 0x055A)。blecent.c:132 */
+export const COMPANY_ID = 0x055a;
+
+/** op_code (candy.h:66-69 / SesameProtocols.kt:55-57)。受信で意味を持つのは response/publish。 */
+export const OP = Object.freeze({
+  CREATE: 0x01, READ: 0x02, UPDATE: 0x03, DELETE: 0x04,
+  SYNC: 0x05, ASYNC: 0x06, RESPONSE: 0x07, PUBLISH: 0x08,
+});
+
+/** item_code。クラウドと共通の正準ソース (src/itemcodes.js) を参照する (重複定義を避ける)。 */
+export const ITEM = ITEM_CODES;
+
+/** セグメントの parsing type (candy.h:44-46 / SesameBleReceiver.kt:5)。ヘッダ = (type<<1) | startBit。 */
+export const SEG = Object.freeze({ APPEND_ONLY: 0, PLAINTEXT: 1, CIPHERTEXT: 2 });
+
+/**
+ * SESAME OS3 デバイスがコマンド応答 (response 0x07) の先頭バイトで返す結果コード。
+ * 出典: 公式 SesameSDK `enum SesameResultCode: UInt8`
+ *   (references_ios/Sources/SesameSDK/Ble/CHDeviceProtocol.swift:195)。
+ * これは **デバイス層 (SesameOS3) の taxonomy** で BLE/WM2 で共通。クラウド (biz3) 経路は
+ * この code を surface しないため、利用できるのは BLE 直接経路のみ。
+ */
+export const RESULT = Object.freeze({
+  0: "success", 1: "invalidFormat", 2: "notSupported", 3: "resultStorageFail",
+  4: "invalidSig", 5: "notFound", 6: "unknown", 7: "busy", 8: "invalidParam", 9: "invalidAction",
+});
+
+/** 結果コード → 名前 (未知は unknown(N))。 */
+export function resultName(code) {
+  return RESULT[code] || `unknown(${code})`;
+}
+
+const CCM_TAG_LEN = 4; // candy.h:42
+const MAX_CHUNK_DATA = 19; // 20B パケット - ヘッダ1B (ssm.c:112-127)
+
+// ---------- セッション鍵 / login ----------
+
+/**
+ * 既存 secretKey と initial token から CCM セッション鍵 (16B) を導出する。
+ * token16 = AES-128-CMAC(secretKey, randomToken)  (ssm_cmd.c:43 / CHSesameOS3LockBase.kt:109)
+ *
+ * @param {string|Buffer} secretKey 16B (32hex)
+ * @param {Buffer} token 4B (initial publish のランダム値)
+ * @returns {Buffer} 16B セッション鍵
+ */
+export function deriveSessionKey(secretKey, token) {
+  const key = Buffer.isBuffer(secretKey) ? secretKey : Buffer.from(secretKey, "hex");
+  if (key.length !== 16) throw new Error(`secretKey must be 16 bytes (got ${key.length})`);
+  if (!Buffer.isBuffer(token) || token.length !== 4) throw new Error("token must be a 4-byte Buffer");
+  const mac = aesCmac(key, token, { returnAsBuffer: true });
+  return Buffer.isBuffer(mac) ? mac : Buffer.from(mac, "hex");
+}
+
+/**
+ * login コマンドの平文ペイロード = [LOGIN(2)] ++ token16[0:4] (ssm_cmd.c:44-45 / CHSesameOS3LockBase.kt:118-120)。
+ * PLAINTEXT セグメントで送る。
+ * @param {Buffer} token16 deriveSessionKey の戻り
+ * @returns {Buffer} 5B
+ */
+export function loginPayload(token16) {
+  return Buffer.concat([Buffer.from([ITEM.LOGIN]), token16.subarray(0, 4)]);
+}
+
+// ---------- AES-128-CCM (c_ccm.c, ssm.c:80-82/100-104) ----------
+
+/**
+ * CCM nonce (13B) = count(8B LE) ++ 0x00 ++ token(4B)。
+ * (ssm.h:17-21 / SesameOS3BleCipher.kt:13 + sault=0x00++token)
+ */
+function ccmNonce(count, token4) {
+  const c = Buffer.alloc(8);
+  c.writeBigUInt64LE(BigInt(count));
+  return Buffer.concat([c, Buffer.from([0x00]), token4]);
+}
+
+const CCM_AAD = Buffer.from([0x00]); // ssm.c:8
+
+/**
+ * コマンド平文を CCM 暗号化し、末尾に 4B tag を付けて返す。
+ * @param {Buffer} token16 セッション鍵
+ * @param {number|bigint} count 送信カウンタ (送信ごと +1)
+ * @param {Buffer} token4 initial token
+ * @param {Buffer} plaintext 暗号化前フレーム ([item, ...data])
+ * @returns {Buffer} ciphertext ++ tag(4B)
+ */
+export function ccmEncrypt(token16, count, token4, plaintext) {
+  const iv = ccmNonce(count, token4);
+  const c = crypto.createCipheriv("aes-128-ccm", token16, iv, { authTagLength: CCM_TAG_LEN });
+  c.setAAD(CCM_AAD, { plaintextLength: plaintext.length });
+  const ct = Buffer.concat([c.update(plaintext), c.final()]);
+  return Buffer.concat([ct, c.getAuthTag()]);
+}
+
+/**
+ * CCM 復号。入力は ciphertext ++ tag(4B)。tag 不一致なら throw。
+ * @param {Buffer} token16
+ * @param {number|bigint} count 受信カウンタ (受信ごと +1)
+ * @param {Buffer} token4
+ * @param {Buffer} ctWithTag ciphertext ++ tag(4B)
+ * @returns {Buffer} 復号平文
+ */
+export function ccmDecrypt(token16, count, token4, ctWithTag) {
+  if (ctWithTag.length < CCM_TAG_LEN) throw new Error("ciphertext too short (no tag)");
+  const iv = ccmNonce(count, token4);
+  const ct = ctWithTag.subarray(0, ctWithTag.length - CCM_TAG_LEN);
+  const tag = ctWithTag.subarray(ctWithTag.length - CCM_TAG_LEN);
+  const d = crypto.createDecipheriv("aes-128-ccm", token16, iv, { authTagLength: CCM_TAG_LEN });
+  d.setAAD(CCM_AAD, { plaintextLength: ct.length });
+  d.setAuthTag(tag);
+  return Buffer.concat([d.update(ct), d.final()]);
+}
+
+// ---------- セグメント分割 / 結合 (ssm.c:70-128 / SesameBleReceiver.kt) ----------
+
+/**
+ * 1 メッセージ (平文 or 暗号文+tag) を 20B パケット列に分割する。
+ * 先頭パケットのみ start bit、最終パケットで parsing type を立てる (中間は APPEND_ONLY)。
+ * @param {Buffer} payload 送るバイト列 (平文ならフレーム、暗号なら ct++tag)
+ * @param {number} parsingType SEG.PLAINTEXT | SEG.CIPHERTEXT
+ * @returns {Buffer[]} 各 ≤20B
+ */
+export function splitSegments(payload, parsingType) {
+  const packets = [];
+  let offset = 0;
+  let first = true;
+  // payload 長 0 でも 1 パケット (ヘッダのみ) を送る必要がある場合に対応 (do-while 的)
+  do {
+    const remain = payload.length - offset;
+    const isLast = remain <= MAX_CHUNK_DATA;
+    const dataLen = isLast ? remain : MAX_CHUNK_DATA;
+    let header = isLast ? (parsingType << 1) : (SEG.APPEND_ONLY << 1);
+    if (first) header |= 1;
+    packets.push(Buffer.concat([Buffer.from([header]), payload.subarray(offset, offset + dataLen)]));
+    offset += dataLen;
+    first = false;
+  } while (offset < payload.length);
+  return packets;
+}
+
+/**
+ * 受信セグメントを結合するアセンブラ。feed() で 1 パケットずつ与え、メッセージ完結時に
+ * { type, data } を返す (未完なら null)。start bit でバッファをリセット。
+ */
+export class SegmentAssembler {
+  constructor() { this._buf = []; }
+
+  /**
+   * @param {Buffer} packet notify で届いた 1 パケット
+   * @returns {{type:number, data:Buffer}|null} 完結時のみ {type, data}
+   */
+  feed(packet) {
+    if (!packet || packet.length < 1) return null;
+    const header = packet[0];
+    if (header & 1) this._buf = []; // start bit → リセット (ssm.c:71-73)
+    this._buf.push(packet.subarray(1));
+    const type = header >> 1;
+    if (type === SEG.APPEND_ONLY) return null; // 継続 (ssm.c:76-78)
+    const data = Buffer.concat(this._buf);
+    this._buf = [];
+    return { type, data };
+  }
+}
+
+// ---------- フレーム build / parse (ssm.c:85-94 / CHSesameOS3.kt:142-150) ----------
+
+/**
+ * 送信フレーム = [item_code] ++ data。op_code は送信時付与しない (CHSesameOS3.kt:495-499)。
+ * @param {number} itemCode
+ * @param {Buffer} [data]
+ * @returns {Buffer}
+ */
+export function buildSendFrame(itemCode, data = Buffer.alloc(0)) {
+  return Buffer.concat([Buffer.from([itemCode]), data]);
+}
+
+/**
+ * 受信フレーム (復号後) = [op_code][item_code][body...] を分解。
+ * response(7) は body=[resultCode][payload...]、publish(8) は body=[payload...] (呼び出し側で解釈)。
+ * @param {Buffer} buf
+ * @returns {{opCode:number, itemCode:number, body:Buffer}}
+ */
+export function parseRecvFrame(buf) {
+  if (buf.length < 2) throw new Error("frame too short");
+  return { opCode: buf[0], itemCode: buf[1], body: buf.subarray(2) };
+}
+
+// ---------- 各コマンドの data 生成 ----------
+
+/**
+ * lock/unlock の data = `[0x00, 0x0E] ++ historyTag`、先頭 20B に切詰め (CHDBModel.kt:37-57)。
+ * 先頭 2B `0x000E` (BE) は tag type = "Android user BLE UUID" (SesameProtocols.kt:70)。
+ *
+ * tag 省略時は type のみ (`[0x00,0x0E]`) を送る = SDK の `historytag=null` パスと同じ。
+ * tag を渡す場合は **Buffer (バイト列) を渡すこと**。type が UUID を示すため、任意 utf8 文字列を
+ * 入れると型と中身が不整合になる (操作ログ用途であり実害は小さいが、SDK 準拠なら bytes)。
+ *
+ * @param {Buffer|Uint8Array} [tag] 操作ログ用タグ (バイト列)。省略可。
+ * @returns {Buffer}
+ */
+export function historyTagBLE(tag) {
+  let tagBuf;
+  if (tag == null) tagBuf = Buffer.alloc(0);
+  else if (Buffer.isBuffer(tag) || tag instanceof Uint8Array) tagBuf = Buffer.from(tag);
+  else throw new Error("historyTagBLE: tag は Buffer/Uint8Array で渡してください (type 0x000E は UUID バイト列を想定)");
+  return Buffer.concat([Buffer.from([0x00, 0x0e]), tagBuf]).subarray(0, 20);
+}
+
+/**
+ * autolock の data = 2B LE 秒数 (delay.toShort().toReverseBytes()、CHSesame5Device.kt:96-105)。0=無効。
+ * @param {number} seconds 0..65535
+ * @returns {Buffer} 2B
+ */
+export function autolockData(seconds) {
+  if (!Number.isInteger(seconds) || seconds < 0 || seconds > 0xffff) {
+    throw new Error("seconds must be an integer 0..65535 (0 = disable)");
+  }
+  const b = Buffer.alloc(2);
+  b.writeUInt16LE(seconds);
+  return b;
+}
+
+// ---------- mechStatus 解析 (ssm.h:29-40, ssm.c:33-39) ----------
+
+/** ロック状態。SESAME 5 (OS3) は施錠範囲フラグの有無の 2 値 (中間 "moved" は無い)。 */
+export const MECH_STATE = Object.freeze({ LOCKED: "locked", UNLOCKED: "unlocked" });
+
+/**
+ * mech_status を OS3 デバイスの種別に応じて解析する。
+ *
+ * SDK は publish payload の **長さ** で具象 MechStatus クラスを選ぶ (CHSesame5Device.kt:213-218,
+ * CHSesameBot2Device.kt:245-248)。それに倣い長さで分岐する:
+ *
+ *   7B = CHSesame5MechStatus (Sesame5/6 系ロック)
+ *     data[0..1]: 電池電圧 ADC 生値 (LE。換算式は本体に無くサーバ側 → ここでは batteryRaw として返すのみ)
+ *     data[2..3]: target   (i16 LE、-32768 は「未設定」→ null)
+ *     data[4..5]: position (i16 LE)
+ *     data[6]   : flags — bit1 isInLockRange / bit3 critical / bit4 stop / bit5 batteryCritical
+ *   3B = CHSesameBot2MechStatus / CHSesameBike2MechStatus (Bot2/Bot3/Bike2/Bike3)
+ *     data[0..1]: 電池電圧 ADC 生値 (LE)
+ *     data[2]   : flags — bit1 isInLockRange / bit2 stop
+ *     position/target の概念なし (null)
+ *
+ * 施錠/解錠は **isInLockRange の有無のみ** で判定する。OS3 に unlock-range ビットも中間 (moved) も無い
+ * (CHSesame5.kt:24-32 / CHSesameBot2.kt:123-126: isInUnlockRange = !isInLockRange)。
+ *
+ * @param {Buffer} buf 3B (bot/bike) または 7B 以上 (lock)
+ * @returns {{state:string, isInLockRange:boolean, target:number|null, position:number|null,
+ *            isStop:boolean, isCritical:boolean, isBatteryCritical:boolean, batteryRaw:number, flags:number}}
+ */
+export function parseMechStatus(buf) {
+  if (!Buffer.isBuffer(buf)) throw new Error("mechStatus must be a Buffer");
+  if (buf.length === 3) return parseMechStatusBot(buf);
+  if (buf.length >= 7) return parseMechStatusLock(buf);
+  throw new Error(`mechStatus は 3B (bot/bike) か 7B 以上 (lock) を想定 (got ${buf.length}B)`);
+}
+
+/** 7B: CHSesame5MechStatus 準拠 (Sesame5/6)。 */
+function parseMechStatusLock(buf) {
+  const batteryRaw = buf.readUInt16LE(0);
+  const target = buf.readInt16LE(2);
+  const position = buf.readInt16LE(4);
+  const flags = buf[6];
+  const isInLockRange = !!(flags & 0b0000_0010); // flags and 2
+  return {
+    state: isInLockRange ? MECH_STATE.LOCKED : MECH_STATE.UNLOCKED,
+    isInLockRange,
+    target: target === -32768 ? null : target,
+    position,
+    isCritical: !!(flags & 0b0000_1000),        // flags and 8
+    isStop: !!(flags & 0b0001_0000),            // flags and 16
+    isBatteryCritical: !!(flags & 0b0010_0000), // flags and 32
+    batteryRaw,
+    flags,
+  };
+}
+
+/** 3B: CHSesameBot2MechStatus / CHSesameBike2MechStatus 準拠 (Bot2/Bot3/Bike2/Bike3)。 */
+function parseMechStatusBot(buf) {
+  const batteryRaw = buf.readUInt16LE(0);
+  const flags = buf[2];
+  const isInLockRange = !!(flags & 0b0000_0010); // flags and 2
+  return {
+    state: isInLockRange ? MECH_STATE.LOCKED : MECH_STATE.UNLOCKED,
+    isInLockRange,
+    target: null,
+    position: null,
+    isCritical: false,
+    isStop: !!(flags & 0b0000_0100),            // flags and 4
+    isBatteryCritical: false,
+    batteryRaw,
+    flags,
+  };
+}

package/src/ble/session.js

@@ -0,0 +1,235 @@
+// SESAME BLE セッション状態機械 (OS 非依存)。
+//
+// 接続後のバイト列のやり取りだけを担い、無線 I/O は注入された transport に委譲する
+// (= mock transport でハードウェア無しにテスト可能)。
+//
+// フロー (調査仕様 §C/D/E/F、ssm.c / CHSesameOS3LockBase.kt 準拠):
+//   connect → transport.connect(onPacket)
+//     → device が publish(8)+initial(14)+token4 を送る
+//     → counters=0、session鍵=CMAC(secretKey, token)、login(2) を PLAINTEXT で送信
+//     → device が response(7)+login(2)+resultCode を返す → resultCode==0 で接続完了
+//   request(item, data) → frame を CCM 暗号化 (encCount++) → セグメント送信
+//     → response(7)+item を待って {resultCode, payload} で解決
+//   publish(8)+mechStatus(81) は onStatus リスナへ。
+
+import { Buffer } from "node:buffer";
+import {
+  deriveSessionKey, loginPayload, ccmEncrypt, ccmDecrypt,
+  splitSegments, SegmentAssembler, buildSendFrame, parseRecvFrame,
+  parseMechStatus, OP, ITEM, SEG, resultName,
+} from "./protocol.js";
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const LOGIN_TIMEOUT_MS = 8_000;
+
+/**
+ * BLE デバイスが非 0 の resultCode を返したときのエラー。
+ * `resultName` (notFound/busy/invalidSig…) で機械的に分岐できる (SesameResultCode 由来)。
+ */
+export class BleResultError extends Error {
+  /** @param {"login"|"command"} phase @param {number} resultCode @param {number|null} itemCode */
+  constructor(phase, resultCode, itemCode = null) {
+    const name = resultName(resultCode);
+    // 紛らわしいコードに一言ヒント (エラーそのものに載るので別 docs を読む必要がない)。
+    const hint = { invalidSig: " (secretKey 不一致?)", notFound: " (op 非対応 or 内部リソース無し)", busy: " (デバイスが他操作中)" }[name] || "";
+    super(`BLE ${phase} failed: ${name}${hint} (resultCode=${resultCode}${itemCode != null ? `, item=${itemCode}` : ""})`);
+    this.name = "BleResultError";
+    this.resultCode = resultCode;
+    this.resultName = name;
+    this.itemCode = itemCode;
+  }
+}
+
+/**
+ * @typedef {object} BleTransport BLE 無線 I/O アダプタ (transport.js のアダプタが満たす契約)。
+ * @property {(onPacket:(packet:Buffer)=>void)=>Promise<void>} connect 接続+notify購読。各 notify を onPacket へ。
+ * @property {(bytes:Buffer)=>void|Promise<void>} write Write Without Response。
+ * @property {()=>void|Promise<void>} disconnect 切断。
+ */
+
+export class SesameBleSession {
+  /**
+   * @param {{transport:BleTransport, secretKey:string|Buffer, debug?:boolean,
+   *          defaultTimeoutMs?:number}} opts
+   */
+  constructor({ transport, secretKey, debug = false, defaultTimeoutMs = DEFAULT_TIMEOUT_MS }) {
+    if (!transport) throw new Error("transport required");
+    if (!secretKey) throw new Error("secretKey required");
+    this._transport = transport;
+    this._secretKey = Buffer.isBuffer(secretKey) ? secretKey : Buffer.from(secretKey, "hex");
+    this._debug = debug;
+    this._defaultTimeoutMs = defaultTimeoutMs;
+
+    this._asm = new SegmentAssembler();
+    this._token = null; // 4B initial token
+    this._key = null; // 16B session key
+    this._encCount = 0;
+    this._decCount = 0;
+    this._loggedIn = false;
+
+    /** @type {Map<number, Array<{resolve:Function, reject:Function, timer:any}>>} item → FIFO */
+    this._pending = new Map();
+    this._statusListeners = new Set();
+    this._publishListeners = new Set();
+    this._lastStatus = null;
+    this._loginWaiter = null;
+  }
+
+  _log(...a) { if (this._debug) console.error("[ble]", ...a); }
+
+  /** 最後に受信した mechStatus (parseMechStatus の結果)。未受信なら null。 */
+  get lastStatus() { return this._lastStatus; }
+  get isLoggedIn() { return this._loggedIn; }
+
+  /** mechStatus publish を購読。戻り値 unsubscribe。 */
+  onStatus(fn) { this._statusListeners.add(fn); return () => this._statusListeners.delete(fn); }
+  /** 任意 publish を購読 ({opCode,itemCode,body})。戻り値 unsubscribe。 */
+  onPublish(fn) { this._publishListeners.add(fn); return () => this._publishListeners.delete(fn); }
+
+  /**
+   * 接続して login まで完了させる。
+   * @returns {Promise<void>} login 成功で resolve
+   */
+  async connect() {
+    const loginPromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._loginWaiter = null;
+        reject(new Error("BLE login timeout (initial/login 応答なし)"));
+      }, LOGIN_TIMEOUT_MS);
+      this._loginWaiter = { resolve, reject, timer };
+    });
+    await this._transport.connect((packet) => this._onPacket(packet));
+    return loginPromise;
+  }
+
+  async disconnect() {
+    // pending を全て reject してリーク防止
+    for (const [, queue] of this._pending) {
+      for (const p of queue) { clearTimeout(p.timer); p.reject(new Error("BLE disconnected")); }
+    }
+    this._pending.clear();
+    if (this._loginWaiter) { clearTimeout(this._loginWaiter.timer); this._loginWaiter = null; }
+    await this._transport.disconnect();
+    this._loggedIn = false;
+  }
+
+  /**
+   * 暗号化コマンドを送り、response(7)+item を待って返す。
+   * @param {number} itemCode
+   * @param {Buffer} [data]
+   * @param {{timeoutMs?:number}} [opts]
+   * @returns {Promise<{resultCode:number, payload:Buffer}>}
+   */
+  request(itemCode, data = Buffer.alloc(0), { timeoutMs } = {}) {
+    if (!this._loggedIn) return Promise.reject(new Error("not logged in (connect() を先に)"));
+    const to = timeoutMs ?? this._defaultTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._dequeue(itemCode, entry);
+        reject(new Error(`BLE request timeout (item=${itemCode})`));
+      }, to);
+      const entry = { resolve, reject, timer };
+      if (!this._pending.has(itemCode)) this._pending.set(itemCode, []);
+      this._pending.get(itemCode).push(entry);
+      // 送信は subscribe 登録後に (race 防止)
+      this._sendCipher(buildSendFrame(itemCode, data));
+    });
+  }
+
+  /** 暗号化なしで item+data を送る (login 等のハンドシェイク用低レベル)。 */
+  _sendPlain(frame) {
+    for (const seg of splitSegments(frame, SEG.PLAINTEXT)) this._transport.write(seg);
+  }
+
+  /** CCM 暗号化して送る (encCount++)。 */
+  _sendCipher(frame) {
+    const ct = ccmEncrypt(this._key, this._encCount, this._token, frame);
+    this._encCount += 1;
+    for (const seg of splitSegments(ct, SEG.CIPHERTEXT)) this._transport.write(seg);
+  }
+
+  _dequeue(itemCode, entry) {
+    const queue = this._pending.get(itemCode);
+    if (!queue) return;
+    const i = queue.indexOf(entry);
+    if (i >= 0) queue.splice(i, 1);
+    if (queue.length === 0) this._pending.delete(itemCode);
+  }
+
+  // ---------- 受信 ----------
+
+  _onPacket(packet) {
+    let assembled;
+    try { assembled = this._asm.feed(Buffer.isBuffer(packet) ? packet : Buffer.from(packet)); }
+    catch (e) { this._log("assemble error", e); return; }
+    if (!assembled) return; // 未完
+
+    let frame;
+    if (assembled.type === SEG.CIPHERTEXT) {
+      try {
+        frame = ccmDecrypt(this._key, this._decCount, this._token, assembled.data);
+      } catch (e) {
+        // 復号失敗 = カウンタずれ or 破損。デバイス側が当該メッセージで enc カウンタを進めたかは
+        // 判別不能なため _decCount は進めない (進めると正常時にずれる)。以降ずれ続けるが、これは
+        // 異常系であり、回復は再接続 (initial で両カウンタ 0 リセット) に委ねる。
+        this._log("decrypt failed (count desync / corruption)", e?.message);
+        return;
+      }
+      this._decCount += 1;
+    } else {
+      frame = assembled.data; // PLAINTEXT (initial / login 応答が平文の場合)
+    }
+
+    let parsed;
+    try { parsed = parseRecvFrame(frame); }
+    catch (e) { this._log("parse error", e?.message); return; }
+    const { opCode, itemCode, body } = parsed;
+    this._log("recv", { opCode, itemCode, len: body.length });
+
+    if (opCode === OP.PUBLISH) {
+      if (itemCode === ITEM.INITIAL) { this._handleInitial(body); return; }
+      if (itemCode === ITEM.MECH_STATUS) {
+        try { this._lastStatus = parseMechStatus(body); } catch { /* ignore */ }
+        for (const fn of [...this._statusListeners]) { try { fn(this._lastStatus); } catch { /* ignore */ } }
+      }
+      for (const fn of [...this._publishListeners]) { try { fn({ opCode, itemCode, body }); } catch { /* ignore */ } }
+      return;
+    }
+
+    if (opCode === OP.RESPONSE) {
+      const resultCode = body.length > 0 ? body[0] : 0;
+      const payload = body.subarray(1);
+      if (itemCode === ITEM.LOGIN) { this._handleLoginResponse(resultCode); return; }
+      this._resolvePending(itemCode, resultCode, payload);
+    }
+  }
+
+  _handleInitial(token) {
+    if (!token || token.length < 4) { this._log("initial token too short"); return; }
+    this._token = Buffer.from(token.subarray(0, 4));
+    this._encCount = 0;
+    this._decCount = 0;
+    this._key = deriveSessionKey(this._secretKey, this._token);
+    this._log("initial token received, sending login");
+    this._sendPlain(loginPayload(this._key)); // login は PLAINTEXT
+  }
+
+  _handleLoginResponse(resultCode) {
+    if (!this._loginWaiter) return;
+    const w = this._loginWaiter;
+    this._loginWaiter = null;
+    clearTimeout(w.timer);
+    if (resultCode === 0) { this._loggedIn = true; w.resolve(); }
+    else w.reject(new BleResultError("login", resultCode));
+  }
+
+  _resolvePending(itemCode, resultCode, payload) {
+    const queue = this._pending.get(itemCode);
+    if (!queue || queue.length === 0) return; // 対応する request なし (unsolicited)
+    const entry = queue.shift();
+    if (queue.length === 0) this._pending.delete(itemCode);
+    clearTimeout(entry.timer);
+    if (resultCode === 0) entry.resolve({ resultCode, payload });
+    else entry.reject(new BleResultError("command", resultCode, itemCode));
+  }
+}