sesame-kit 0.4.0

package/src/crypto.js

@@ -0,0 +1,162 @@
+// SESAME デバイス制御で使う暗号 / バイナリ helpers。
+//
+// Ported from biz3 (CANDY-HOUSE/biz3, MIT):
+//   - vendor reference: references_web/src/utils/Cmac.js (CMAC-AES-128)
+//   - vendor reference: references_web/src/utils/biz3utils.js (uuidBuffer 等)
+//   - vendor reference: references_web/src/constants/cmdCode.js (item code)
+//   - vendor reference: references_web/src/constants/sesameDeviceModel.js (productType)
+//
+// biz3 Web は Web Crypto API + 自前 CMAC 実装、Node では node-aes-cmac (RFC 4493) を使用。
+// 公式 BLE 実装と同じ AES-CMAC で、用途のみ異なる (biz3 は時刻署名 / BLE は session key 派生)。
+
+import { aesCmac } from "node-aes-cmac";
+import { randomUUID } from "node:crypto";
+// 公式 biz3 の純定数を直接 import (手書き複製を排除 = 推測ズレ原理的になし)。
+// vendor/biz3/constants/ は biz3 原文のコピー (vendor/biz3/README.md 参照)。
+import { modelNameByProductType } from "../vendor/biz3/constants/sesameDeviceModel.js";
+
+// ---------- UUID ----------
+
+/**
+ * v4 UUID を生成。biz3 biz3utils.generateUUID:269-280 と一致させる。
+ * 学習リモコンのキーは **クライアントが keyUUID を発番**してサーバに渡す
+ * (learn/index.js:222)。サーバ発番ではない。
+ *
+ * ★重要: biz3 は `randomUUID().toUpperCase()` で **大文字** UUID を返す。
+ *   Node の randomUUID は既定で小文字なので toUpperCase() で揃える。
+ *   (biz3 アプリと同一アカウント併用時に keyUUID 形式を一致させるため)
+ */
+export function generateUUID() {
+  return randomUUID().toUpperCase();
+}
+
+// ---------- AES-CMAC ----------
+
+/**
+ * 時刻ベースの CMAC 署名。
+ * biz3 Cmac.cmacTime() と同じ:
+ *   1. UNIX 秒を 4B LE にパック
+ *   2. 上位 3B (index 1-3) だけを取る → 256 秒粒度の時刻
+ *   3. AES-CMAC(secretKey, message) → 16B MAC
+ *   4. hex 化して先頭 8 文字 (= 4B) を返す
+ *
+ * `node-aes-cmac` は RFC 4493 標準実装。RFC 4493 §4 の Test Vector 2
+ * (key=2b7e1516..., msg=6bc1bee2..., expected=070a16b4...) で動作検証済み
+ * (リポルートで `node _crypto_test.mjs` 実行時 PASS。biz3 Cmac.js も同じ
+ * RFC 4493 標準を Web Crypto 上で自前実装しているため出力は一致する)。
+ *
+ * @param {string} hexKey 16B (32hex) の secretKey
+ * @returns {string} 4B hex (8 文字)
+ */
+export function cmacTime(hexKey) {
+  if (typeof hexKey !== "string") {
+    throw new Error(`secretKey must be a 32-char hex string (got ${typeof hexKey})`);
+  }
+  if (hexKey.length !== 32) {
+    throw new Error(`secretKey must be a 32-char hex string (got length ${hexKey.length})`);
+  }
+  if (!/^[0-9a-fA-F]{32}$/.test(hexKey)) {
+    throw new Error("secretKey must be a 32-char hex string (non-hex characters found)");
+  }
+  const key = Buffer.from(hexKey, "hex");
+  const ts = Math.floor(Date.now() / 1000);
+  const buf = Buffer.alloc(4);
+  buf.writeUInt32LE(ts, 0);
+  const msg = buf.subarray(1, 4); // 上位 3B
+  const mac = aesCmac(key, msg);  // node-aes-cmac は Buffer を返す
+  const macBuf = Buffer.isBuffer(mac) ? mac : Buffer.from(mac, "hex");
+  return macBuf.toString("hex").slice(0, 8);
+}
+
+// ---------- binary helpers ----------
+
+/**
+ * UUID (32hex with hyphens) → 18B base64 (prefix '000c' 付き)。
+ * biz3 utils.uuidBuffer() と同じ。`biz3TriggerLocker` の `history` フィールドに乗せる。
+ *
+ * @param {string} uuid 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' or 32hex
+ * @param {string} prefix デフォルト '000c'
+ * @returns {string} base64 (24 文字)
+ */
+export function uuidToHistoryBase64(uuid, prefix = "000c") {
+  if (typeof uuid !== "string") throw new Error("uuid required (string)");
+  const cleanHex = uuid.replace(/-/g, "");
+  if (cleanHex.length !== 32) {
+    throw new Error(`uuid must be 32 hex chars (got len=${cleanHex.length})`);
+  }
+  return Buffer.from(prefix + cleanHex, "hex").toString("base64");
+}
+
+// ---------- cmd codes ----------
+// クラウドと BLE は同一の SesameItemCode を送る (梱包だけが違う)。コード表は src/itemcodes.js に一本化し、
+// クラウド側ではそれを CMD という別名で参照する (歴史的な名前)。biz3 web が施錠/解錠 UI で送るのは
+// TOGGLE=88 / CLICK(=BOT_CLICK)=89 (useIotCtrl.js:37, VIotSwitch.js:35)。LOCK=82/UNLOCK=83 も
+// サーバ API が解釈する正当値。
+export { ITEM_CODES as CMD } from "./itemcodes.js";
+
+// ---------- IR type (リモコンの wire 値: remote.type / sendIR の irType) ----------
+//
+// これらは「実デバイス (remote.type) に乗る wire 値」。biz3 一次資料で確認:
+//
+//   プリセットリモコン (operation: "remoteEmit"):
+//     ac=0xc000 / tv=0x2000 / light=0xe000 / fan=0x8000
+//     vendor: ir-type-list/index.js — 種別を選ぶとその値がそのまま remote.type になり
+//             sendIR(..., remote.type) に乗る (remote-list/index.js:322, remote-air/index.js:370)。
+//
+//   自己学習リモコン (operation: "learnEmit", カテゴリ情報なし):
+//     learn = 0xFE00 (65024)
+//     vendor: learn/index.js:142 — 学習で作るリモコンは {model:'Learn', type:0xfe00}。
+//             useRemoteCtrl.js:228 も `remoteDevice.type === 0xfe00` を「自己学習」と判定。
+//     ※ ir-type-list の learn メニューは 0xFEFF だが、これは「UI の種別選択メニュー識別子」
+//       であって実 remote.type ではない (選ぶと学習画面へ遷移するだけ)。
+//       プリセットは「メニュー値=実type」だが学習だけ非対称。旧実装の実機実測 65024(0xFE00)
+//       が正しく、UI 値 0xFEFF を実 type と取り違えてはいけない。
+//
+// 通常 sesame は device の stateInfo.remoteList から irType を自動取得するので、
+// これらの定数はフォールバックと `ir search`/`remote-list` の引数用。
+
+export const IR_TYPE = Object.freeze({
+  ac: 0xc000,     // 49152 エアコン (プリセット)
+  tv: 0x2000,     //  8192 テレビ (プリセット)
+  light: 0xe000,  // 57344 照明 (プリセット)
+  fan: 0x8000,    // 32768 扇風機 (プリセット)
+  learn: 0xfe00,  // 65024 自己学習リモコンの実 type (learn/index.js:142 で確証)
+});
+
+/**
+ * irType が不明な場合の保険値。
+ * このツールは自己学習リモコン (learnEmit) を主対象とするため learn (0xFE00) を既定とする。
+ * (フォールバックが実際に使われるのは server が type を報告しない異常時のみ)
+ */
+export const DEFAULT_IR_TYPE = IR_TYPE.learn; // 0xFE00 (65024)
+
+/**
+ * irType を文字列エイリアス (ac/tv/...) または数値文字列から数値に解決する。
+ * @param {string|number} v "ac" | "49152" | 0xc000 等
+ * @returns {number}
+ */
+export function parseIrType(v) {
+  if (typeof v === "number") return v;
+  if (typeof v !== "string") throw new Error(`irType must be a string or number (got ${typeof v})`);
+  const key = v.trim().toLowerCase();
+  if (key in IR_TYPE) return IR_TYPE[key];
+  const n = Number(key);
+  if (Number.isFinite(n)) return n;
+  const aliases = Object.keys(IR_TYPE).join(", ");
+  throw new Error(`Unknown irType "${v}". 数値 (例 49152) かエイリアス (${aliases}) を指定してください。`);
+}
+
+// ---------- productType (model name → byte value) ----------
+// 手書きせず、biz3 の sesameDeviceModel.js を直接逆引きして生成する。
+// biz3 は modelNameByProductType = { <productType>: "<model名>" }。これを反転して
+// PRODUCT_TYPE = { "<model名>": <productType> } を作る。欠番 (12,34) も自動で反映され、
+// biz3 が機種を追加/変更しても vendor を更新すればそのまま追従する。
+export const PRODUCT_TYPE = Object.freeze(
+  Object.fromEntries(
+    Object.entries(modelNameByProductType).map(([pt, model]) => [model, Number(pt)]),
+  ),
+);
+
+export function productTypeFromModelName(modelName) {
+  return PRODUCT_TYPE[modelName];
+}

package/src/devices.js

@@ -0,0 +1,228 @@
+// SESAME デバイス管理 (history / battery / status / firmware / webapi proxy)。
+//
+// Ported from biz3 (CANDY-HOUSE/biz3, MIT):
+//   - vendor reference: references_web/src/api/useManageDevice.js
+//   - vendor reference: references_web/src/api/useManageGroup.js (getHistory)
+//   - vendor reference: references_web/src/api/useDeveloper.js (firmware, invokeAPI)
+//   - vendor reference: references_web/src/components/MobileBatteryChart.js (battery)
+//
+// 既存 client.js の listDevices() (getCompanyDevice) はそのまま残し、
+// 個人ユーザ向けの getUserDevice、CRUD、履歴系をここに集める。
+
+import { ACTION_TYPES } from "../vendor/biz3/constants/messageConstants.js";
+import { assertSuccess } from "./util.js";
+
+// action 文字列は vendor (biz3 messageConstants) から引く (手書きしない)。
+const ACT_MANAGE = ACTION_TYPES.BIZ3_MANAGE_DEVICE;       // "biz3ManageDevice"
+const ACT_HISTORY = ACTION_TYPES.BIZ3_GET_DEVICEHISTORY;  // "biz3GetDeviceHistory"
+const ACT_BATTERY = ACTION_TYPES.BIZ3_GET_BATTERY_RECORD; // "biz3GetDeviceBatteryRecord"
+const ACT_FIRMWARE = ACTION_TYPES.BIZ3_LIST_FIRMWARE;     // "biz3ListFirmware"
+const ACT_WEBAPI = ACTION_TYPES.BIZ3_INVOKE_WEBAPI;       // "biz3InvokeWebAPIs"
+const ACT_TRIGGER = ACTION_TYPES.BIZ3_TRIGGER_LOCKER;     // "biz3TriggerLocker" (state push)
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+// ---------- device CRUD (biz3ManageDevice) ----------
+
+/** 個人ユーザのデバイス一覧。companyID 不要。 */
+export async function getUserDevices(client, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  // 応答は PubedUserDevice 系で来る可能性 (catalog より)。pending 単純解決を試み、
+  // 失敗時は listener fallback を用意する。
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const to = setTimeout(() => {
+      if (done) return;
+      done = true;
+      unsub();
+      reject(new Error("getUserDevice timeout"));
+    }, timeoutMs);
+    const unsub = client.subscribe(`${ACT_MANAGE}:PubedUserDevice`, (msg) => {
+      if (done) return;
+      done = true;
+      clearTimeout(to);
+      unsub();
+      resolve(msg?.data?.data?.list || msg?.data?.list || msg?.data || []);
+    });
+    client.send({ action: ACT_MANAGE, op: "getUserDevice" });
+  });
+}
+
+/** 単機の現在状態 (ロック開閉、電池等)。biz3 では isFromApp=true 限定だが CLI でも投げてみる価値あり。 */
+export async function getDeviceStatus(client, { deviceUUID }) {
+  const resp = await client.request(
+    { action: ACT_MANAGE, op: "getDeviceStatus", deviceUUID },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "getDeviceStatus", { strict: true });
+  return resp.data;
+}
+
+/** デバイス名変更。subUUID は呼び出し側 (client.js) が持つ。 */
+export async function updateDeviceName(client, { subUUID, deviceUUID, deviceName }) {
+  const resp = await client.request(
+    {
+      action: ACT_MANAGE,
+      op: "updateName",
+      obj: { subUUID, deviceUUID, deviceName },
+    },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "updateDeviceName", { strict: true });
+  return resp;
+}
+
+/** デバイスを company から削除。items=[{deviceUUID,...}] */
+export async function deleteDevices(client, { companyID, items }) {
+  const resp = await client.request(
+    { action: ACT_MANAGE, op: "del", companyID, items },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "deleteDevices", { strict: true });
+  return resp;
+}
+
+/**
+ * デバイス state push を購読。subscribeDevicesUpdate (biz3ManageDevice) を投げて購読要求し、
+ * 実際の state push は **`biz3TriggerLocker:pubDeviceStateChange`** で届く。
+ *
+ * 注 (監査で修正): 購読要求の op は biz3ManageDevice/subscribeDevicesUpdate
+ * (useManageDevice.js:325) だが、**応答の push は別 action/op** で来る:
+ * biz3 は `biz3TriggerLocker` action の `pubDeviceStateChange` (小文字, useIotCtrl.js:11,21)
+ * として state 変化を流す。push 本体は `data = {deviceUUID, stateInfo}`。
+ * 旧実装は `biz3ManageDevice:PubedDeviceStateChange` (大文字 P・別 action) を購読しており
+ * push を1件も受信できなかった。
+ *
+ * **既知の制限**: biz3 プロトコルに `unsubscribeDevicesUpdate` op は無いため、
+ * unsubscribe()/close() 後もサーバ側 push は止まらない (ローカルで無視するだけ)。
+ */
+export function subscribeDevicesUpdate(client, { companyID, items, onUpdate }) {
+  client.send({ action: ACT_MANAGE, op: "subscribeDevicesUpdate", items, companyID });
+  return client.subscribe(`biz3TriggerLocker:pubDeviceStateChange`, (msg) => {
+    try { onUpdate(msg); } catch { /* ignore */ }
+  });
+}
+
+// ---------- history ----------
+
+/**
+ * ロックの開閉履歴を取得。`list` はデバイス指定の配列。
+ * @param {{companyID:string, list:any[], pageSize?:number}} p
+ */
+export async function getDeviceHistory(client, { companyID, list, pageSize = null }) {
+  const resp = await client.request(
+    { action: ACT_HISTORY, op: "getHistory", companyID, list, pageSize },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "getDeviceHistory", { strict: true });
+  return resp.data;
+}
+
+/**
+ * 開閉履歴の1エントリを非表示化 (論理削除)。
+ * biz3 useManageGroup.js makeInvisibleHistory: フラット {action, deviceUUID, timestamp, op}。
+ * @param {{deviceUUID:string, timestamp:number}} p
+ */
+export async function makeHistoryInvisible(client, { deviceUUID, timestamp }) {
+  const resp = await client.request(
+    { action: ACT_HISTORY, op: "makeInvisible", deviceUUID, timestamp },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "makeHistoryInvisible");
+  return resp;
+}
+
+// ---------- battery ----------
+
+/**
+ * 電池履歴を取得。DynamoDB の lastEvaluatedKey でページング。
+ * 1 回呼ぶごとに 1 ページ分。null → 最新ページ。
+ * 戻り値: { records: [{ts, light, heavy, lightPercentage, heavyPercentage}], lastEvaluatedKey }
+ */
+export async function getBatteryRecord(client, { deviceUUID, lastEvaluatedKey = null, pageSize = 100 }) {
+  const resp = await client.request(
+    { action: ACT_BATTERY, op: "batch-get", deviceUUID, lastEvaluatedKey, pageSize },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "getBatteryRecord", { strict: true });
+  return resp.data || { records: [], lastEvaluatedKey: null };
+}
+
+/**
+ * 電池履歴の1エントリを非表示化 (論理削除)。
+ * biz3 MobileBatteryChart.js makeInvisibleRecord: フラット {action, deviceUUID, timestamp_second, op}。
+ * @param {{deviceUUID:string, timestampSecond:number}} p
+ */
+export async function makeBatteryRecordInvisible(client, { deviceUUID, timestampSecond }) {
+  const resp = await client.request(
+    { action: ACT_BATTERY, op: "makeInvisible", deviceUUID, timestamp_second: timestampSecond },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, "makeBatteryRecordInvisible");
+  return resp;
+}
+
+// ---------- firmware ----------
+
+/** 配信中ファームウェア一覧。 */
+export async function listFirmware(client) {
+  // この op は op フィールド無し (action のみ)
+  return new Promise((resolve, reject) => {
+    const to = setTimeout(() => { unsub(); reject(new Error("listFirmware timeout")); }, DEFAULT_TIMEOUT_MS);
+    const unsub = client.subscribe(`${ACT_FIRMWARE}:`, (msg) => {
+      clearTimeout(to);
+      unsub();
+      resolve(msg?.data || []);
+    });
+    client.send({ action: ACT_FIRMWARE });
+  });
+}
+
+// ---------- webapi proxy ----------
+
+/**
+ * biz3InvokeWebAPIs 経由で REST WebAPI を呼ぶ。
+ * func 例: 'webapi_ssm_shadow_get', 'webapi_history_get', 'webapi_cmd_send'。
+ * apiKeyId は別途 biz3 の dev console で発行されたもの。
+ *
+ * @param {{func:string, apiKeyId:string, query?:object, body?:object}} p
+ */
+export async function invokeWebAPI(client, { func, apiKeyId, query = {}, body = {} }) {
+  const resp = await client.request(
+    { action: ACT_WEBAPI, op: func, apiKeyId, query, body },
+    DEFAULT_TIMEOUT_MS,
+  );
+  assertSuccess(resp, `invokeWebAPI(${func})`, { strict: true });
+  return resp.data;
+}
+
+// ---------- 便利ラッパ (WebAPI 経由の高頻度ユースケース) ----------
+
+/** WebAPI 経由で 単機の shadow state を取得。 */
+export function webapiDeviceState(client, { apiKeyId, deviceId }) {
+  return invokeWebAPI(client, {
+    func: "webapi_ssm_shadow_get",
+    apiKeyId,
+    query: { device_id: deviceId },
+  });
+}
+
+/**
+ * WebAPI 経由で履歴を取得。
+ * biz3 useDeveloper.js:67-80: query = {device_id, page:0, lg:5, isBiz:true}。
+ * lg は言語コードの**数値 ID** (biz3 は 5 を渡す)。旧実装は "ja" (文字列) で誤り。
+ */
+export function webapiDeviceHistory(client, { apiKeyId, deviceId, page = 0, lg = 5, isBiz = true }) {
+  return invokeWebAPI(client, {
+    func: "webapi_history_get",
+    apiKeyId,
+    query: { device_id: deviceId, page, lg, isBiz },
+  });
+}
+
+/** WebAPI 経由でロック cmd 送信 (sign/history は呼び出し側で組み立て)。 */
+export function webapiSendCmd(client, { apiKeyId, deviceId, cmd, sign, history }) {
+  return invokeWebAPI(client, {
+    func: "webapi_cmd_send",
+    apiKeyId,
+    body: { device_id: deviceId, cmd, sign, history },
+  });
+}

package/src/index.js

@@ -0,0 +1,55 @@
+// 公開ライブラリエントリ。
+//
+// パッケージ名は "sesame-kit" (package.json の "name")。
+// 注: このパッケージは `"private": true` のため npm publish されていません。
+//     他プロジェクトから使うには `npm link sesame-kit` か
+//     `npm install /path/to/sesame-kit` で取り込んでください。
+//
+// 高レベル:
+//   import { SesameHub3 } from "sesame-kit";
+//   await SesameHub3.use(async (hub) => {
+//     await hub.send("ac", "停止");
+//   });
+//   // または手動で connect/close:
+//   const hub = await SesameHub3.fromConfig();
+//   await hub.connect();
+//   try { await hub.send("ac", "停止"); } finally { await hub.close(); }
+//
+// 低レベル (自前で WS / トークン管理する場合):
+//   import { Hub3WsClient, sendIR, getIRCodes, FileTokenStore } from "sesame-kit";
+//   import { lock } from "sesame-kit";   // lock.* namespace も利用可
+
+export { SesameHub3 } from "./client.js";
+export { Hub3WsClient, sendIR, getIRCodes } from "./transport.js";
+export { FileTokenStore } from "./tokens.js";
+export { ConfigStore } from "./config.js";
+export { configPaths, resolveConfigDir } from "./paths.js";
+export * as auth from "./auth.js";
+export * as crypto from "./crypto.js";
+export * as ir from "./ir.js";
+export * as devices from "./devices.js";
+export * as account from "./account.js";
+export * as schedule from "./schedule.js";
+export * as org from "./org.js";
+export * as company from "./company.js";
+export * as access from "./access.js";
+export * as iot from "./iot.js";
+export * as presetir from "./presetir.js";
+export * as sharekey from "./sharekey.js";
+export * as lock from "./lock.js";
+// BLE 直接制御 (クラウド非経由)。SesameBle.use({secretKey, deviceUUID}, fn) で利用。
+export * as ble from "./ble/index.js";
+export { SesameBle } from "./ble/index.js";
+// WS 応答 success 判定の共通 helper (低レベル import で op を直叩きする消費者向け)。
+export { assertSuccess } from "./util.js";
+// lock.* の主要関数は個別 named export でも提供 (後方互換 + 利便性)。
+// 注: `botClick` は低レベル関数 (client, params) → SesameHub3#botClick(name) とは別物。
+export {
+  triggerLock,
+  lockLock,
+  lockUnlock,
+  lockToggle,
+  botClick,
+  triggerItemCommand,
+  setAutolock,
+} from "./lock.js";