sesame-kit 0.4.0

package/src/auth.js

@@ -0,0 +1,248 @@
+// Cognito 認証。
+//
+// Ported from biz3 (CANDY-HOUSE/biz3, MIT):
+//   - vendor reference: references_web/src/api/useAuthState.js (AWS Amplify Auth.signIn / Auth.signUp ベース)
+//   - vendor reference: references_web/src/aws-exports.js (region / UserPool / Client ID)
+//
+// Amplify はブラウザ前提 (localStorage / IndexedDB) のため Node では使えず、
+// @aws-sdk/client-cognito-identity-provider 直叩きに置換している。
+// 振る舞いは biz3 と同じ:
+//   - User Pool: ap-northeast-1_bY2byhlCa (biz / consumer 共有)
+//   - CUSTOM_AUTH passwordless: USERNAME → CUSTOM_CHALLENGE (email にコード) → コード回答
+//   - 新規ユーザーは dummy password "Aa123456" で SignUp してから sign-in (useAuthState.js:109-122)
+//
+// biz3 との唯一の機能的相違: Client ID を biz3 の `21u50hboia4s5q0sbk6pbdfmss` から、
+// 公式 iOS/Android/chat.candyhouse.co と同じ Consumer Client `6ialca0p8u0lsgvbmvsljfm305` に
+// 差し替え。これで refreshToken が事実上失効しなくなる。
+//
+// 状態は TokenStore (load/save/clear + loadPending/savePending/clearPending) に永続化を委譲。
+// CLI からは FileTokenStore、ライブラリ消費者は独自実装を渡せる。
+
+import {
+  CognitoIdentityProviderClient,
+  InitiateAuthCommand,
+  RespondToAuthChallengeCommand,
+  SignUpCommand,
+} from "@aws-sdk/client-cognito-identity-provider";
+
+const COGNITO_REGION = "ap-northeast-1";
+const USER_POOL_ID = "ap-northeast-1_bY2byhlCa";
+// 公式アプリ (iOS/Android Sesame, chat.candyhouse.co) と同じ client。
+// biz3 aws-exports.js:5 の userPoolWebClientId と一致 (一次資料で確認済み)。
+export const CONSUMER_CLIENT_ID = "6ialca0p8u0lsgvbmvsljfm305";
+// 注 (出所未確認): biz.candyhouse.co の管理 web client とされる値だが、
+// biz3 の現行ソース (references_web) には 1 件も現れない (旧実装由来の値)。
+// デフォルトでは使われず export のみ。biz3 web 自体も aws-exports の consumer client を使う。
+export const BIZ_CLIENT_ID = "21u50hboia4s5q0sbk6pbdfmss";
+// デフォルトは consumer (公式アプリと同じ寿命)
+const DEFAULT_CLIENT_ID = CONSUMER_CLIENT_ID;
+// 公式が新規 sign-up 時に使う ダミーパスワード (Cognito policy 通過用)
+const DUMMY_PASSWORD = "Aa123456";
+
+const cognito = new CognitoIdentityProviderClient({ region: COGNITO_REGION });
+
+/** JWT を decode して exp を返す (秒、UNIX時間)。失敗時は 0。 */
+function jwtExp(token) {
+  try {
+    const payload = token.split(".")[1];
+    const json = Buffer.from(payload, "base64").toString("utf8");
+    return JSON.parse(json).exp || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** idToken の aud claim (= clientId) を返す。 */
+function jwtAud(token) {
+  try {
+    const payload = token.split(".")[1];
+    const json = Buffer.from(payload, "base64").toString("utf8");
+    return JSON.parse(json).aud || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * idToken の `sub` claim (= Cognito user UUID) を返す。
+ * biz3 が `gStripe.customerInfo.subUUID` として使っている値と同じで、
+ * `biz3TriggerLocker` の `history` フィールドに乗せる必要がある。
+ */
+export function jwtSub(token) {
+  try {
+    const payload = token.split(".")[1];
+    const json = Buffer.from(payload, "base64").toString("utf8");
+    return JSON.parse(json).sub || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 失効していない idToken を返す。必要なら refresh する。
+ * 失効まで `marginSec` 以下なら早期 refresh する (デフォルト 60秒)。
+ *
+ * @param {{load:Function, save:Function}} store
+ */
+export async function getValidIdToken(store, { marginSec = 60 } = {}) {
+  const t = store.load();
+  if (!t) {
+    throw new Error("No tokens stored. `sesame login <email>` で sign-in してください。");
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const exp = jwtExp(t.idToken);
+  if (t.idToken && exp - now > marginSec) {
+    return t.idToken;
+  }
+
+  if (!t.refreshToken) {
+    throw new Error("idToken expired and no refreshToken. Re-run login.");
+  }
+
+  const clientId = t.clientId || DEFAULT_CLIENT_ID;
+  const authParameters = { REFRESH_TOKEN: t.refreshToken };
+  if (t.deviceKey) authParameters.DEVICE_KEY = t.deviceKey;
+
+  const resp = await cognito.send(
+    new InitiateAuthCommand({
+      AuthFlow: "REFRESH_TOKEN_AUTH",
+      ClientId: clientId,
+      AuthParameters: authParameters,
+    }),
+  );
+
+  const r = resp.AuthenticationResult;
+  if (!r?.IdToken) {
+    throw new Error(`Cognito refresh returned no IdToken: ${JSON.stringify(resp)}`);
+  }
+
+  t.idToken = r.IdToken;
+  if (r.AccessToken)  t.accessToken  = r.AccessToken;
+  if (r.RefreshToken) t.refreshToken = r.RefreshToken; // rotation 対応
+  t.lastRefresh = new Date().toISOString();
+  store.save(t);
+  return t.idToken;
+}
+
+/**
+ * Step 1: CUSTOM_AUTH を開始。Cognito が email に確認コードを送る。
+ * 新規ユーザーの場合は SignUp してから retry。
+ *
+ * @param {{savePending:Function}} store
+ */
+export async function loginInitiate(store, username, { clientId = DEFAULT_CLIENT_ID } = {}) {
+  const initiate = () =>
+    cognito.send(
+      new InitiateAuthCommand({
+        AuthFlow: "CUSTOM_AUTH",
+        ClientId: clientId,
+        AuthParameters: { USERNAME: username },
+      }),
+    );
+
+  let resp;
+  try {
+    resp = await initiate();
+  } catch (e) {
+    if (e.name === "UserNotFoundException") {
+      // 公式アプリと同じ自動 sign-up
+      await cognito.send(
+        new SignUpCommand({
+          ClientId: clientId,
+          Username: username,
+          Password: DUMMY_PASSWORD,
+        }),
+      );
+      resp = await initiate();
+    } else {
+      throw e;
+    }
+  }
+
+  if (resp.ChallengeName !== "CUSTOM_CHALLENGE") {
+    throw new Error(`Unexpected challenge: ${resp.ChallengeName} (expected CUSTOM_CHALLENGE)`);
+  }
+  store.savePending({
+    clientId,
+    username,
+    session: resp.Session,
+    initiatedAt: new Date().toISOString(),
+  });
+  return { challenge: resp.ChallengeName, params: resp.ChallengeParameters };
+}
+
+/**
+ * Step 2: email で受け取ったコードで CUSTOM_CHALLENGE を回答。
+ * 成功するとトークンを保存し、pending 状態を消す。
+ *
+ * @param {{loadPending:Function, save:Function, clearPending:Function}} store
+ */
+export async function loginVerify(store, code) {
+  const s = store.loadPending();
+  if (!s) {
+    throw new Error("No pending sign-in. 先に `login <email>` を実行してください。");
+  }
+  const resp = await cognito.send(
+    new RespondToAuthChallengeCommand({
+      ClientId: s.clientId,
+      ChallengeName: "CUSTOM_CHALLENGE",
+      Session: s.session,
+      ChallengeResponses: {
+        USERNAME: s.username,
+        ANSWER: code,
+      },
+    }),
+  );
+
+  if (!resp.AuthenticationResult) {
+    if (resp.ChallengeName) {
+      throw new Error(`Another challenge required: ${resp.ChallengeName}. (再 login が必要)`);
+    }
+    throw new Error(`No AuthenticationResult: ${JSON.stringify(resp)}`);
+  }
+
+  const r = resp.AuthenticationResult;
+  const tokens = {
+    clientId: s.clientId,
+    idToken: r.IdToken,
+    refreshToken: r.RefreshToken,
+    accessToken: r.AccessToken,
+    deviceKey: r.NewDeviceMetadata?.DeviceKey || null,
+    deviceGroupKey: r.NewDeviceMetadata?.DeviceGroupKey || null,
+    username: s.username,
+    lastRefresh: new Date().toISOString(),
+  };
+  store.save(tokens);
+  store.clearPending();
+  return tokens;
+}
+
+/**
+ * 既存の localStorage ダンプから bootstrap (互換用)。
+ *
+ * @param {{save:Function}} store
+ */
+export function bootstrap(store, values) {
+  if (!values.idToken)      throw new Error("idToken required");
+  if (!values.refreshToken) throw new Error("refreshToken required");
+  const clientId = jwtAud(values.idToken) || DEFAULT_CLIENT_ID;
+  const t = {
+    clientId,
+    idToken:      values.idToken,
+    refreshToken: values.refreshToken,
+    accessToken:  values.accessToken || null,
+    deviceKey:    values.deviceKey   || null,
+    username:     values.username    || null,
+    lastRefresh:  new Date().toISOString(),
+  };
+  store.save(t);
+  return t;
+}
+
+export const CONFIG_META = {
+  region: COGNITO_REGION,
+  userPoolId: USER_POOL_ID,
+  consumerClientId: CONSUMER_CLIENT_ID,
+  bizClientId: BIZ_CLIENT_ID,
+};

package/src/ble/devicemodel.js

@@ -0,0 +1,164 @@
+// SESAME デバイスの「型モデル」。公式 SesameSDK (Android) の CHProductModel
+// (open/devices/base/CHDeivceProtocols.kt) と各デバイスの能力 (capability) を Node に移植したもの。
+//
+// SDK では能力 (lock/unlock/toggle/click/autolock) が「型ごとのインターフェース」に個別宣言されており、
+// 共通基底 (CHDevices / CHSesameLock) は施錠操作を一切持たない。つまり型ごとに能力が非対称。
+// ここではその非対称性をそのままテーブル化する (共通基底に lock を生やすのは原典と乖離するため避ける)。
+//
+// 出典: _sesame_sdk_ref/sesame-sdk/.../open/devices/{CHSesame5,CHSesameBot2,CHSesameBike2,...}.kt,
+//       CHBleManager.kt (productModel.deviceFactory() で生成する実装クラス → OS世代/能力)。
+
+/**
+ * BLE 上の「デバイス種別 (kind)」。productType→実装クラスの多対一を、能力の単位でまとめたもの。
+ * - lock5     : Sesame5/5Pro/6/6Pro/US/miwa, BLE Connector (OS3 ロック)
+ * - bot2      : SESAME Bot2/Bot3 (OS3) — click のみ
+ * - bike2     : SESAME Bike2/Bike3 (OS3) — unlock のみ
+ * - sesame2   : Sesame2/3/4 (OS2 ロック) — BLE は別プロトコル (未実装)
+ * - botOs2    : SESAME Bot1 (OS2) — BLE 未実装
+ * - bikeOs2   : Bike1 (OS2) — BLE 未実装
+ * - biometric : Touch/Face/OpenSensor/Remote (鍵束デバイス。施錠操作なし)
+ * - hub3      : Hub3/Hub3 LTE (IoT 中継。BLE 施錠操作なし)
+ * - wifi      : WifiModule2
+ */
+export const KIND = Object.freeze({
+  LOCK5: "lock5", BOT2: "bot2", BIKE2: "bike2",
+  SESAME2: "sesame2", BOT_OS2: "botOs2", BIKE_OS2: "bikeOs2",
+  BIOMETRIC: "biometric", HUB3: "hub3", WIFI: "wifi",
+  UNKNOWN: "unknown", // テーブルに無い model。操作を捏造せず「操作なし」にする (lock5 に化けさせない)
+});
+
+/**
+ * kind ごとの能力定義。**経路 (cloud / ble) ごとに操作可能な op 集合**を持ち、
+ * 実際にユーザーに見せる/送れる op は両者の **和集合** で決まる (どちらの経路でも操作できないものは出さない)。
+ *  - os       : 世代 (2 | 3)
+ *  - cloud    : この CLI が **クラウド経由**で送れる制御 op (biz3TriggerLocker: lock/unlock/toggle/click、
+ *               Hub3 は biz3OperateIoT/IR: ir/relay/led)。autolock はクラウド中継で実機未反映なので含めない。
+ *  - ble      : この CLI が **BLE 直接**で送れる制御 op。OS2 系は BLE プロトコル未実装なので空。
+ *  - mechKind : mechStatus の解釈方法 ("os3lock" 7B / "os3bot" 3B / null)
+ *  - label    : 表示用の種別名
+ *
+ * 出典: 型×経路の可否は調査で確定 (lock.js triggerLock=機種非依存に lock/unlock/toggle/click を中継、
+ *       autolock はクラウド未反映=lock.js:127-131、Hub3 の ir/relay/led=iot.js/transport.js、
+ *       OS2 BLE 未実装=ble/* 、biometric は制御 op なし=管理のみ)。
+ */
+const CAPS = Object.freeze({
+  [KIND.LOCK5]:    { os: 3, cloud: ["lock", "unlock", "toggle"], ble: ["lock", "unlock", "toggle", "autolock"], mechKind: "os3lock", label: "SESAME (lock)" },
+  [KIND.BOT2]:     { os: 3, cloud: ["click"],                    ble: ["click"],                                 mechKind: "os3bot",  label: "SESAME Bot" },
+  [KIND.BIKE2]:    { os: 3, cloud: ["unlock"],                   ble: ["unlock"],                                mechKind: "os3bot",  label: "SESAME Bike" },
+  [KIND.SESAME2]:  { os: 2, cloud: ["lock", "unlock", "toggle"], ble: [],                                        mechKind: null,      label: "SESAME (OS2 lock)" },
+  [KIND.BOT_OS2]:  { os: 2, cloud: ["click"],                    ble: [],                                        mechKind: null,      label: "SESAME Bot (OS2)" },
+  [KIND.BIKE_OS2]: { os: 2, cloud: ["unlock"],                   ble: [],                                        mechKind: null,      label: "SESAME Bike (OS2)" },
+  [KIND.BIOMETRIC]:{ os: 3, cloud: [],                           ble: [],                                        mechKind: null,      label: "SESAME Touch/Face/Sensor/Remote" },
+  [KIND.HUB3]:     { os: 3, cloud: ["ir", "relay", "led"],       ble: [],                                        mechKind: null,      label: "SESAME Hub3" },
+  [KIND.WIFI]:     { os: 3, cloud: ["ir", "relay", "led"],       ble: [],                                        mechKind: null,      label: "WiFi Module 2" },
+  [KIND.UNKNOWN]:  { os: 0, cloud: [],                           ble: [],                                        mechKind: null,      label: "(未知のデバイス)" },
+});
+
+/** cloud と ble の op を和集合し、自然な提示順で返す (ble 由来を先、cloud 固有を後)。 */
+function unionOps(caps) {
+  const seen = new Set();
+  const out = [];
+  for (const o of [...caps.ble, ...caps.cloud]) if (!seen.has(o)) { seen.add(o); out.push(o); }
+  return out;
+}
+
+/**
+ * productType (整数) → { model, kind }。
+ * 値は CHProductModel enum (CHDeivceProtocols.kt:28-252) と deviceFactory() の生成クラスに準拠。
+ * pType 12 は SDK でも欠番。
+ */
+export const PRODUCT_TYPES = Object.freeze({
+  0:  { model: "sesame_2",                 kind: KIND.SESAME2 },
+  1:  { model: "wm_2",                      kind: KIND.WIFI },
+  2:  { model: "ssmbot_1",                  kind: KIND.BOT_OS2 },
+  3:  { model: "bike_1",                    kind: KIND.BIKE_OS2 },
+  4:  { model: "sesame_4",                  kind: KIND.SESAME2 },
+  5:  { model: "sesame_5",                  kind: KIND.LOCK5 },
+  6:  { model: "bike_2",                    kind: KIND.BIKE2 },
+  7:  { model: "sesame_5_pro",              kind: KIND.LOCK5 },
+  8:  { model: "open_sensor_1",             kind: KIND.BIOMETRIC },
+  9:  { model: "ssm_touch_pro",             kind: KIND.BIOMETRIC },
+  10: { model: "ssm_touch",                 kind: KIND.BIOMETRIC },
+  11: { model: "BLE_Connector_1",           kind: KIND.LOCK5 },
+  13: { model: "hub_3",                     kind: KIND.HUB3 },
+  14: { model: "remote",                    kind: KIND.BIOMETRIC },
+  15: { model: "remote_nano",               kind: KIND.BIOMETRIC },
+  16: { model: "sesame_5_us",               kind: KIND.LOCK5 },
+  17: { model: "bot_2",                     kind: KIND.BOT2 },
+  18: { model: "sesame_face_Pro",           kind: KIND.BIOMETRIC },
+  19: { model: "sesame_face",               kind: KIND.BIOMETRIC },
+  20: { model: "sesame_6",                  kind: KIND.LOCK5 },
+  21: { model: "sesame_6_pro",              kind: KIND.LOCK5 },
+  22: { model: "sesame_face_pro_ai",        kind: KIND.BIOMETRIC },
+  23: { model: "sesame_face_ai",            kind: KIND.BIOMETRIC },
+  24: { model: "open_sensor_2",             kind: KIND.BIOMETRIC },
+  25: { model: "ssm_touch_2",               kind: KIND.BIOMETRIC },
+  26: { model: "ssm_touch_2_pro",           kind: KIND.BIOMETRIC },
+  27: { model: "sesame_face_2",             kind: KIND.BIOMETRIC },
+  28: { model: "ssm_face_2_pro",            kind: KIND.BIOMETRIC },
+  29: { model: "sesame_miwa",               kind: KIND.LOCK5 },
+  30: { model: "sesame_face_2_ai",          kind: KIND.BIOMETRIC },
+  31: { model: "sesame_face_2_pro_ai",      kind: KIND.BIOMETRIC },
+  32: { model: "sesame_6_pro_slidingdoor",  kind: KIND.LOCK5 },
+  33: { model: "bike_3",                    kind: KIND.BIKE2 },
+  35: { model: "bot_3",                     kind: KIND.BOT2 },
+  36: { model: "hub_3_lte",                 kind: KIND.HUB3 },
+});
+
+/** model 文字列 → kind の逆引き表。 */
+const KIND_BY_MODEL = Object.freeze(
+  Object.fromEntries(Object.values(PRODUCT_TYPES).map((v) => [v.model, v.kind])),
+);
+
+/**
+ * model 文字列から kind を返す。
+ *   - model 未指定 (null/空) → lock5 (SesameBle の config-less 利用 & 既存ロック config の後方互換。
+ *     config.locks は同期時にロック機種のみ whitelist + model 保存なので、ここに来るのは実質ロック)。
+ *   - model 文字列がテーブルに無い → **UNKNOWN (操作なし)**。未知機種を勝手にロック扱いして解錠等を
+ *     捏造しない (Hub3 が解錠を出していた類のバグを構造的に防ぐ)。
+ * @param {string|null|undefined} model
+ * @returns {string} KIND
+ */
+export function kindForModel(model) {
+  if (!model) return KIND.LOCK5;
+  return KIND_BY_MODEL[model] || KIND.UNKNOWN;
+}
+
+/**
+ * model 文字列から能力定義を返す。
+ *   - cloud / ble : 各経路で操作可能な op
+ *   - ops         : 和集合 (UI で見せる操作・提示順)
+ *   - bleSupported: BLE 制御を実装しているか (= ble.length>0)
+ * @param {string|null|undefined} model
+ * @returns {{kind:string, os:number, cloud:string[], ble:string[], ops:string[], mechKind:string|null, bleSupported:boolean, label:string}}
+ */
+export function capabilitiesForModel(model) {
+  const kind = kindForModel(model);
+  const caps = CAPS[kind];
+  return { kind, ...caps, ops: unionOps(caps), bleSupported: caps.ble.length > 0 };
+}
+
+/** その model が op を (いずれかの経路で) 操作できるか。 */
+export function supportsOp(model, op) {
+  return capabilitiesForModel(model).ops.includes(op);
+}
+
+/** その model が (いずれかの経路で) 何か操作できるか。session の対象判定に使う。 */
+export function isOperable(model) {
+  return capabilitiesForModel(model).ops.length > 0;
+}
+
+/**
+ * その model の op を運べる transport 一覧 (型×経路の能力テーブルから導出)。
+ * 例: lock5 の autolock は ["ble"]、lock は ["ble","cloud"]、hub3 の ir は ["cloud"]。
+ * @param {string|null|undefined} model
+ * @param {string} op
+ * @returns {string[]} ("ble" / "cloud" の部分集合)
+ */
+export function transportsForOp(model, op) {
+  const caps = capabilitiesForModel(model);
+  const t = [];
+  if (caps.ble.includes(op)) t.push("ble");
+  if (caps.cloud.includes(op)) t.push("cloud");
+  return t;
+}

package/src/ble/index.js

@@ -0,0 +1,185 @@
+// SESAME BLE 直接制御の公開エントリ。
+//
+// クラウド (WebSocket/biz3) を介さず、PC の Bluetooth から登録済み SESAME を直接操作する。
+// クラウドでは不可だった設定系 (autolock 等) も BLE なら本体に反映される。
+//
+// 使い方 (高レベル):
+//   import { SesameBle } from "sesame-kit";        // もしくは: import { ble } from "sesame-kit"
+//   await SesameBle.use({ deviceUUID, secretKey }, async (lock) => {
+//     await lock.unlock();
+//     await lock.autolock(30);              // ← クラウド不可・BLE 可
+//     console.log(lock.lastStatus);
+//   });
+//
+// 低レベル層 (protocol/session/transport) も個別 export。独自トランスポートを注入する場合は
+// new SesameBle({ secretKey, transport }) で差し替え可能。
+
+import { Buffer } from "node:buffer";
+import { SesameBleSession } from "./session.js";
+import { createBleTransport } from "./transport.js";
+import {
+  ITEM, MECH_STATE, historyTagBLE, autolockData,
+} from "./protocol.js";
+import { capabilitiesForModel } from "./devicemodel.js";
+
+import { scanSesames, NobleTransport } from "./transport.js";
+
+export { SesameBleSession, BleResultError } from "./session.js";
+// SesameResultCode (デバイス層の結果コード taxonomy)。BLE エラーの .resultName で分岐可能。
+export { RESULT as SESAME_RESULT_CODES, resultName } from "./protocol.js";
+export { NobleTransport, createBleTransport, advToDeviceUUID, scanSesames } from "./transport.js";
+export * as protocol from "./protocol.js";
+export * as devicemodel from "./devicemodel.js";
+export { capabilitiesForModel, kindForModel, supportsOp, isOperable, transportsForOp, KIND, PRODUCT_TYPES } from "./devicemodel.js";
+
+/** deviceUUID 正規化 (照合用)。 */
+function normId(u) { return String(u).replace(/-/g, "").toLowerCase(); }
+
+const STATUS_WAIT_MS = 4_000;
+
+/**
+ * 登録済み SESAME を BLE で直接操作する高レベルファサード。
+ */
+export class SesameBle {
+  /**
+   * @param {{
+   *   secretKey: string|Buffer,   // 32hex のロック共通鍵 (cloud の `sesame devices` で取得済み)
+   *   deviceUUID?: string,        // 対象識別 (advertise 照合)。複数 SESAME が近接する環境で必須
+   *   address?: string,           // BLE アドレスで識別する代替
+   *   debug?: boolean,
+   *   transport?: object,         // 独自トランスポート (省略時 noble)
+   * }} opts
+   */
+  constructor({ secretKey, deviceUUID, address, model = null, debug = false, scanTimeoutMs, transport } = {}) {
+    if (!secretKey) throw new Error("secretKey required (32hex)");
+    this._transport = transport || createBleTransport({ deviceUUID, address, debug, scanTimeoutMs });
+    this._session = new SesameBleSession({ transport: this._transport, secretKey, debug });
+    this._model = model;
+    this._caps = capabilitiesForModel(model); // 型ごとの能力 (SDK CHProductModel 準拠)
+  }
+
+  /** デバイスの model 文字列 (例 "sesame_5" / "bot_2")。未指定なら null。 */
+  get model() { return this._model; }
+  /** 型ごとの能力 { kind, os, ops, mechKind, bleSupported, label }。 */
+  get capabilities() { return this._caps; }
+  /** この操作を BLE で送れるか (このファサードは BLE 専用なので ble 能力で判定)。 */
+  supports(op) { return this._caps.ble.includes(op); }
+
+  /** BLE で送れない操作を弾く。SDK では型ごとに能力が非対称 (Bot は click のみ等)。 */
+  _assertOp(op) {
+    if (!this._caps.ble.includes(op)) {
+      const ok = this._caps.ble.length ? this._caps.ble.join("/") : "(BLE 施錠操作なし)";
+      throw new Error(`${this._caps.label}${this._model ? ` (${this._model})` : ""} は BLE で ${op} をサポートしません。可能な操作: ${ok}`);
+    }
+  }
+
+  /** mechStatus publish を購読 (戻り値 unsubscribe)。 */
+  onStatus(fn) { return this._session.onStatus(fn); }
+  /** 最後に受信した mechStatus。 */
+  get lastStatus() { return this._session.lastStatus; }
+  get isConnected() { return this._session.isLoggedIn; }
+
+  /** 接続 + login。 */
+  async connect() { await this._session.connect(); return this; }
+  /** 切断。 */
+  async close() { await this._session.disconnect(); }
+
+  /**
+   * 施錠 (BLE item=82)。tag は履歴に残す任意ラベル。
+   * @returns {Promise<{resultCode:number, payload:Buffer}>}
+   */
+  lock(tag) { this._assertOp("lock"); return this._session.request(ITEM.LOCK, historyTagBLE(tag)); }
+
+  /** 解錠 (BLE item=83)。Sesame5/6 ロックと Bike2 が対応。 */
+  unlock(tag) { this._assertOp("unlock"); return this._session.request(ITEM.UNLOCK, historyTagBLE(tag)); }
+
+  /**
+   * SESAME Bot のクリック (BLE item=89)。Bot2/Bot3 のみ。
+   * @param {Buffer} [tag] 履歴タグ (UUID バイト列)
+   */
+  click(tag) { this._assertOp("click"); return this._session.request(ITEM.CLICK, historyTagBLE(tag)); }
+
+  /**
+   * トグル (Sesame5/6 ロックのみ)。直近の mechStatus が無ければ status() を取得してから判定。
+   * locked → unlock、それ以外 → lock (CHSesame5Device.kt:128-145 準拠)。
+   */
+  async toggle(tag) {
+    this._assertOp("toggle");
+    let s = this.lastStatus;
+    if (!s) s = await this.status().catch(() => null);
+    if (s && s.state === MECH_STATE.LOCKED) return this._session.request(ITEM.UNLOCK, historyTagBLE(tag));
+    return this._session.request(ITEM.LOCK, historyTagBLE(tag));
+  }
+
+  /**
+   * オートロック設定 (BLE item=11、2byte LE 秒数。0=無効)。Sesame5/6 ロックのみ。
+   * **BLE 経由なら実機に反映される** (クラウドの biz3TriggerLocker では ack のみで未反映だった機能)。
+   * @param {number} seconds 0..65535
+   */
+  autolock(seconds) { this._assertOp("autolock"); return this._session.request(ITEM.AUTOLOCK, autolockData(seconds)); }
+
+  /**
+   * 現在の mechStatus を返す。未受信なら publish を待つ (timeout 付き)。
+   * @param {{timeoutMs?:number}} [opts]
+   * @returns {Promise<object>} parseMechStatus の結果
+   */
+  status({ timeoutMs = STATUS_WAIT_MS } = {}) {
+    if (this._session.lastStatus) return Promise.resolve(this._session.lastStatus);
+    return new Promise((resolve, reject) => {
+      const to = setTimeout(() => { off(); reject(new Error("mechStatus を受信できませんでした (timeout)")); }, timeoutMs);
+      const off = this._session.onStatus((s) => { clearTimeout(to); off(); resolve(s); });
+    });
+  }
+
+  /**
+   * 履歴を 1 バッチ取得 (BLE item=4)。payload の解析は呼び出し側 (生バイト返し)。
+   * @returns {Promise<Buffer>}
+   */
+  async history() {
+    const r = await this._session.request(ITEM.HISTORY, Buffer.from([0x01]));
+    return r.payload;
+  }
+
+  /**
+   * connect → fn → close を自動で行うヘルパー。
+   * @param {object} opts コンストラクタ opts
+   * @param {(lock:SesameBle)=>Promise<any>} fn
+   */
+  static async use(opts, fn) {
+    const lock = new SesameBle(opts);
+    await lock.connect();
+    try { return await fn(lock); }
+    finally { await lock.close(); }
+  }
+
+  /**
+   * 複数ロックに**1 回のスキャン**で同時接続する (逐次スキャンを避ける正攻法)。
+   * 近接していないロックは結果に現れず即スキップ (per-device の scan timeout を払わない)。
+   * 見つかったロックへは**並行接続** (login まで)。
+   *
+   * @param {Array<{name:string, deviceUUID:string, secretKey:string, model?:string}>} entries
+   * @param {{debug?:boolean, scanTimeoutMs?:number}} [opts]
+   * @returns {Promise<{connected: Map<string, SesameBle>, unreachable: string[], failed: Array<{name:string, error:Error}>}>}
+   */
+  static async connectMany(entries, { debug = false, scanTimeoutMs = 8_000 } = {}) {
+    const found = await scanSesames({ deviceUUIDs: entries.map((e) => e.deviceUUID), timeoutMs: scanTimeoutMs, debug });
+    const byNorm = new Map([...found.entries()].map(([uuid, p]) => [normId(uuid), p]));
+
+    const connected = new Map();
+    const unreachable = [];
+    const failed = [];
+
+    const inRange = entries.filter((e) => byNorm.has(normId(e.deviceUUID)));
+    for (const e of entries) if (!byNorm.has(normId(e.deviceUUID))) unreachable.push(e.name);
+
+    // 見つかったものは並行で connect+login (別 peripheral なので同時接続可)。
+    await Promise.all(inRange.map(async (e) => {
+      const peripheral = byNorm.get(normId(e.deviceUUID));
+      const ble = new SesameBle({ secretKey: e.secretKey, deviceUUID: e.deviceUUID, model: e.model, debug, transport: new NobleTransport({ peripheral, debug }) });
+      try { await ble.connect(); connected.set(e.name, ble); }
+      catch (error) { failed.push({ name: e.name, error }); await ble.close().catch(() => {}); }
+    }));
+
+    return { connected, unreachable, failed };
+  }
+}