sesame-kit 0.4.0

package/src/ble/transport.js

@@ -0,0 +1,279 @@
+// BLE 無線トランスポートのアダプタ。
+//
+// セッション/プロトコル層 (session.js / protocol.js) は OS 非依存。物理 BLE I/O だけを
+// このアダプタに閉じ込め、ライブラリ本体はどのアダプタにも**ハード依存しない**。
+// 既定アダプタは @abandonware/noble (optionalDependency) を**遅延 require** する。
+// 未導入・Bluetooth 権限なしのときは明確なエラーメッセージを出す。
+//
+// アダプタ契約 (session.js が要求):
+//   connect(onPacket: (packet:Buffer)=>void): Promise<void>   接続+notify購読。各 notify を onPacket へ。
+//   write(bytes: Buffer): Promise<void>                        Write Without Response (順序保証)。
+//   disconnect(): Promise<void>
+//
+// 自前/Web Bluetooth 等の別アダプタも、この 3 メソッドを満たせば session に注入できる。
+
+import { Buffer } from "node:buffer";
+import { createRequire } from "node:module";
+import { GATT, COMPANY_ID } from "./protocol.js";
+
+// optionalDependency (@abandonware/noble) を ESM から遅延 require するためのブリッジ。
+const require = createRequire(import.meta.url);
+
+/** noble 形式 (小文字・ハイフン無し) に正規化。 */
+function nobleUuid(u) {
+  return String(u).replace(/-/g, "").toLowerCase();
+}
+
+/**
+ * SESAME の advertise manufacturerData から deviceUUID を抽出する。
+ * noble の manufacturerData は company ID (LE 5A 05 = 0x055A) を含む生バイト列
+ * (Sesame2BleAdvertisement.kt の valueAt(0) は company ID を除く点に注意 = こちらは +2 オフセット)。
+ * SS5/Touch 系: company(2) + productType(1) + flags(2) + deviceID(16) → deviceID は md[5..21]。
+ *
+ * @param {Buffer|Uint8Array|null|undefined} md
+ * @returns {string|null} "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (小文字) or null
+ */
+export function advToDeviceUUID(md) {
+  if (!md) return null;
+  const b = Buffer.isBuffer(md) ? md : Buffer.from(md);
+  if (b.length < 21) return null;
+  // company ID は LE で 5A 05 (= 0x055A)
+  if (b[0] !== (COMPANY_ID & 0xff) || b[1] !== ((COMPANY_ID >> 8) & 0xff)) return null;
+  const hex = b.subarray(5, 21).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/** 2 つの deviceUUID/アドレスを正規化比較 (ハイフン/大文字無視)。 */
+function idEquals(a, b) {
+  if (!a || !b) return false;
+  return nobleUuid(a) === nobleUuid(b);
+}
+
+// noble (CoreBluetooth バインディング) は一度ロードするとネイティブハンドルがイベントループに
+// 残り、コマンド完了後も node が自然 exit しない。これを立ててエントリポイントで強制 exit を判断する。
+let _nobleLoaded = false;
+/** このプロセスで noble をロード済みか (= 通常 exit ではプロセスが終わらない)。 */
+export function bleWasUsed() { return _nobleLoaded; }
+
+/**
+ * noble を遅延ロードする。未導入・ロード失敗時は導線付きエラー。
+ * @returns {any} noble モジュール
+ */
+function loadNoble() {
+  try {
+    // @abandonware/noble は optionalDependency。未導入なら下で握る。
+    const noble = require("@abandonware/noble");
+    _nobleLoaded = true;
+    return noble;
+  } catch (e) {
+    // MODULE_NOT_FOUND の message は require stack を含むので 1 行目だけ拾う。
+    const cause = String(e?.message || e).split("\n")[0];
+    const err = new Error(
+      "BLE アダプタ (@abandonware/noble) が未導入です。\n" +
+        "  導入: npm i @abandonware/noble  (repo 内で実行 / npm link 環境ならそのまま使えます)\n" +
+        `  (${cause})`,
+    );
+    err.code = "BLE_NO_ADAPTER";
+    throw err;
+  }
+}
+
+/** Bluetooth が poweredOn になるまで待つ (権限/未対応は導線付きエラー)。 */
+function waitPoweredOn(noble, log = () => {}) {
+  return new Promise((resolve, reject) => {
+    if (noble.state === "poweredOn") return resolve();
+    const to = setTimeout(() => { noble.removeListener("stateChange", onState); reject(new Error("Bluetooth 初期化タイムアウト")); }, 10_000);
+    const onState = (state) => {
+      log("noble state", state);
+      if (state === "poweredOn") { clearTimeout(to); noble.removeListener("stateChange", onState); resolve(); }
+      else if (state === "unauthorized") {
+        clearTimeout(to); noble.removeListener("stateChange", onState);
+        const e = new Error("Bluetooth 権限がありません。macOS: システム設定→プライバシーとセキュリティ→Bluetooth で実行中のターミナルを許可してください。");
+        e.code = "BLE_UNAUTHORIZED"; // CLI 側で設定ペインを開く判定に使う
+        reject(e);
+      }
+      else if (state === "poweredOff") {
+        clearTimeout(to); noble.removeListener("stateChange", onState);
+        const e = new Error("Bluetooth がオフです。オンにして再実行してください。");
+        e.code = "BLE_POWERED_OFF";
+        reject(e);
+      }
+      else if (state === "unsupported") {
+        clearTimeout(to); noble.removeListener("stateChange", onState);
+        const e = new Error("この環境では BLE が利用できません (unsupported)。");
+        e.code = "BLE_UNSUPPORTED";
+        reject(e);
+      }
+    };
+    noble.on("stateChange", onState);
+  });
+}
+
+/**
+ * **1 回のスキャン**で近接 SESAME を集める (マルチ接続用)。逐次スキャンを避けるための要。
+ * deviceUUIDs を指定すると、それらが**全て見つかった時点で即終了**、または timeout で打ち切り。
+ * 空指定なら timeout まで全 SESAME を収集。圏外のデバイスは結果に含まれない (= 即スキップ可)。
+ *
+ * @param {{deviceUUIDs?:string[], timeoutMs?:number, debug?:boolean}} opts
+ * @returns {Promise<Map<string, any>>} key = deviceUUID(小文字ダッシュ付き) → noble peripheral
+ */
+export async function scanSesames({ deviceUUIDs = [], timeoutMs = 8_000, debug = false } = {}) {
+  const noble = loadNoble();
+  const log = debug ? (...a) => console.error("[ble:scan]", ...a) : () => {};
+  await waitPoweredOn(noble, log);
+  const want = new Set(deviceUUIDs.map(nobleUuid));
+  const found = new Map(); // deviceUUID(dashed lower) -> peripheral
+
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = async () => {
+      if (done) return; done = true;
+      clearTimeout(to);
+      noble.removeListener("discover", onDiscover);
+      await noble.stopScanningAsync().catch(() => {});
+      resolve(found);
+    };
+    const to = setTimeout(finish, timeoutMs);
+    const onDiscover = (p) => {
+      const uuid = advToDeviceUUID(p.advertisement?.manufacturerData);
+      if (!uuid) return; // SESAME でない
+      if (want.size && !want.has(nobleUuid(uuid))) return; // 対象外
+      if (!found.has(uuid)) { found.set(uuid, p); log("found", uuid); }
+      // 目的の全 UUID が揃ったら早期終了
+      if (want.size && want.size <= found.size && [...want].every((w) => [...found.keys()].some((k) => nobleUuid(k) === w))) {
+        finish();
+      }
+    };
+    noble.on("discover", onDiscover);
+    noble.startScanningAsync([nobleUuid(GATT.SERVICE)], false).catch((e) => {
+      log("scan start failed", e?.message);
+      finish();
+    });
+  });
+}
+
+/**
+ * @abandonware/noble ベースの BLE トランスポート。
+ *
+ * @param {{
+ *   deviceUUID?: string,   // 対象 SESAME の deviceUUID (advertise から照合)
+ *   address?: string,      // BLE アドレスで照合 (deviceUUID が取れない環境向け)
+ *   peripheral?: object,   // 既にスキャン済みの noble peripheral (scanSesames の結果)。あればスキャンしない
+ *   scanTimeoutMs?: number,
+ *   debug?: boolean,
+ * }} opts
+ */
+export class NobleTransport {
+  constructor(opts = {}) {
+    this._opts = opts;
+    this._noble = null;
+    this._peripheral = opts.peripheral || null; // 事前スキャン済みなら受け取る
+    this._scanned = false; // 自前でスキャンしたか (disconnect 時の stopScanning 判定)
+    this._writeChar = null;
+    this._notifyChar = null;
+    this._writeChain = Promise.resolve();
+    this._debug = !!opts.debug;
+  }
+
+  _log(...a) { if (this._debug) console.error("[ble:noble]", ...a); }
+
+  /** @param {(packet:Buffer)=>void} onPacket */
+  async connect(onPacket) {
+    // peripheral が渡されていれば (scanSesames 経由) スキャンを省略 = マルチ接続の高速パス。
+    if (!this._peripheral) {
+      const noble = (this._noble = loadNoble());
+      const { deviceUUID, address, scanTimeoutMs = 15_000 } = this._opts;
+      await this._waitPoweredOn(noble);
+      this._scanned = true;
+      this._peripheral = await this._scanForDevice(noble, { deviceUUID, address, scanTimeoutMs });
+    }
+    const peripheral = this._peripheral;
+    this._log("connecting to", peripheral.address || peripheral.id);
+    await peripheral.connectAsync();
+
+    // 3) service / characteristic を取得
+    const { characteristics } = await peripheral.discoverSomeServicesAndCharacteristicsAsync(
+      [nobleUuid(GATT.SERVICE)],
+      [nobleUuid(GATT.WRITE_CHAR), nobleUuid(GATT.NOTIFY_CHAR)],
+    );
+    this._writeChar = characteristics.find((c) => idEquals(c.uuid, GATT.WRITE_CHAR));
+    this._notifyChar = characteristics.find((c) => idEquals(c.uuid, GATT.NOTIFY_CHAR));
+    if (!this._writeChar || !this._notifyChar) {
+      throw new Error("SESAME GATT characteristic が見つかりません (write/notify)");
+    }
+
+    // 4) notify 購読 → 各パケットを onPacket へ
+    this._notifyChar.on("data", (data) => {
+      try { onPacket(Buffer.isBuffer(data) ? data : Buffer.from(data)); }
+      catch (e) { this._log("onPacket threw", e); }
+    });
+    await this._notifyChar.subscribeAsync();
+    this._log("connected + subscribed");
+  }
+
+  /** Write Without Response。順序保証のため直列化。 */
+  write(bytes) {
+    const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+    this._writeChain = this._writeChain.then(() => {
+      if (!this._writeChar) throw new Error("not connected");
+      return this._writeChar.writeAsync(buf, true); // true = without response
+    });
+    return this._writeChain;
+  }
+
+  async disconnect() {
+    try { if (this._notifyChar) await this._notifyChar.unsubscribeAsync().catch(() => {}); } catch { /* ignore */ }
+    try { if (this._peripheral) await this._peripheral.disconnectAsync(); } catch { /* ignore */ }
+    // 自前スキャンした場合のみ stopScanning (scanSesames 経由は既に停止済み)。
+    try { if (this._scanned && this._noble) await this._noble.stopScanningAsync().catch(() => {}); } catch { /* ignore */ }
+    this._peripheral = null;
+    this._writeChar = null;
+    this._notifyChar = null;
+  }
+
+  _waitPoweredOn(noble) { return waitPoweredOn(noble, (...a) => this._log(...a)); }
+
+  _scanForDevice(noble, { deviceUUID, address, scanTimeoutMs }) {
+    return new Promise((resolve, reject) => {
+      const to = setTimeout(async () => {
+        noble.removeListener("discover", onDiscover);
+        await noble.stopScanningAsync().catch(() => {});
+        reject(new Error(`SESAME が見つかりません (scan ${scanTimeoutMs}ms タイムアウト)。対象が近くにあり登録済みか確認してください。`));
+      }, scanTimeoutMs);
+
+      const onDiscover = async (peripheral) => {
+        const md = peripheral.advertisement?.manufacturerData;
+        const advUuid = advToDeviceUUID(md);
+        // 照合: deviceUUID 指定があれば advertise の deviceUUID か BLE アドレスで一致、
+        // どちらも未指定なら最初に見つかった SESAME (company 0x055A) を採用。
+        const isSesame = advUuid != null;
+        if (!isSesame) return;
+        const match =
+          (!deviceUUID && !address) ||
+          (deviceUUID && advUuid && idEquals(advUuid, deviceUUID)) ||
+          (address && idEquals(peripheral.address, address));
+        if (!match) return;
+        clearTimeout(to);
+        noble.removeListener("discover", onDiscover);
+        await noble.stopScanningAsync().catch(() => {});
+        resolve(peripheral);
+      };
+
+      noble.on("discover", onDiscover);
+      noble.startScanningAsync([nobleUuid(GATT.SERVICE)], false).catch((e) => {
+        clearTimeout(to);
+        noble.removeListener("discover", onDiscover);
+        reject(new Error(`BLE スキャン開始に失敗: ${e?.message || e}`));
+      });
+    });
+  }
+}
+
+/**
+ * 既定の BLE トランスポートを生成する (noble を遅延ロード)。
+ * @param {object} opts NobleTransport の opts
+ * @returns {NobleTransport}
+ */
+export function createBleTransport(opts = {}) {
+  return new NobleTransport(opts);
+}

package/src/cli/access.js

@@ -0,0 +1,373 @@
+// `sesame access …` コマンド群 — SESAME Touch (Pro) の NFC カード / キーパッド暗証番号 (passcode)。
+//
+// 本体ロジックは src/access.js (biz3ManageAccessCtlAuthData)。ここは commander への配線と
+// 入出力整形のみを担う。hub.access.* は companyID/subUUID 自動注入の namespace。
+//
+// ⚠️ 2層構造の注意 (本体 access.js / biz3 由来):
+//   本モジュールの WS op は **サーバ DB 側の同期** を担う。カード/パスコードの実機ファーム
+//   ウェアへの物理書き込み・削除は別系統 (BLE iotCmd) の責務であり、ここでは扱わない。
+//   biz3 では BLE で実機を変更 → その ack 内で本 WS op を投げて DB を追従させる設計。
+//   よって rm/post 系は「DB 同期のみ」であり、実機側とは別管理になりうる点に注意。
+//
+// 注: access の WS op (getCards/postCards/delCards/clearCards/update* 等) は送信フレームに
+//     companyID も subUUID も載せない (本体 access.js 参照)。namespace が注入する値も各関数が
+//     destructure しないため破棄される。よって refreshAccount() は不要で、**ctx.withHub** を使う
+//     (schedule.js と同様。withAccount だと毎コマンド余分な biz3GetLoginUser 往復が発生する)。
+//
+// ctx 契約 (cli.js makeCtx が供給。schedule.js のコメント参照):
+//   ctx.withHub(fn)     : connect → fn(hub, {opts}) → close。
+//   ctx.out(json, humanFn, jsonObj) : --json 時は jsonObj、それ以外は humanFn()。
+//   ctx.die(msg, code)  : エラー表示して exit。
+//   ctx.canPrompt()     : TTY かつ --json なし。
+//   ctx.prompts         : { selectFromList, promptText, confirm, promptLine }。
+//   ctx.parseJson(raw, hint) : --json 文字列を JSON.parse (失敗時 die(...,2))。
+
+/**
+ * --device オプション値を deviceUUID 配列に正規化する。
+ * commander の variadic / 繰り返し指定で配列になるが、各要素に "uuid1,uuid2" の
+ * カンマ連結が混ざっても受けられるように分解する。
+ * @param {string[]|string|undefined} raw
+ * @returns {string[]}
+ */
+function normalizeDevices(raw) {
+  if (!raw) return [];
+  const arr = Array.isArray(raw) ? raw : [raw];
+  return arr
+    .flatMap((s) => String(s).split(","))
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * deviceUUID 群を確定する。--device 指定があればそれを優先。
+ * 未指定かつ対話可能なら listDevices() から選択させる (selectFromList は単一選択)。
+ * 非対話なら die(...,2) で必須を案内。
+ * @param {object} hub
+ * @param {object} ctx
+ * @param {string[]} devices
+ * @param {string} cmdHint die 時に出すコマンド例
+ * @returns {Promise<string[]|null>} 確定できなければ null (die 済み)
+ */
+async function resolveDeviceUUIDs(hub, ctx, devices, cmdHint) {
+  if (devices.length > 0) return devices;
+  if (ctx.canPrompt()) {
+    const list = await hub.listDevices();
+    if (!Array.isArray(list) || list.length === 0) {
+      // 対象未確定で操作が実行できない異常終了なので非 0 (2) で抜ける。
+      ctx.die("デバイスが見つかりません。", 2);
+      return null;
+    }
+    const picked = await ctx.prompts.selectFromList(
+      "対象デバイスを選択",
+      list,
+      (d) => `${d.deviceName ?? "(no-name)"}  ${d.deviceUUID}`,
+    );
+    return picked?.deviceUUID ? [picked.deviceUUID] : null;
+  }
+  ctx.die(`--device <uuid...> が必要です: ${cmdHint} (非対話モード)`, 2);
+  return null;
+}
+
+/** --device オプション (variadic) のヘルプ文言。複数指定 or カンマ連結を受ける。 */
+const DEVICE_OPT_DESC = "対象 deviceUUID (複数指定 or カンマ連結。省略時は対話選択)";
+
+/**
+ * @param {import("commander").Command} program
+ * @param {object} ctx cli.js makeCtx() が供給する共有コンテキスト
+ */
+export function registerAccessCommands(program, ctx) {
+  const access = program
+    .command("access")
+    .description("アクセス制御データ (NFC カード/暗証番号の WS DB 同期。実機書き込みは別系統 BLE)");
+
+  // ===== カード =====
+  const cards = access.command("cards").description("NFC カード (DB 同期)");
+
+  // sesame access cards ls --device <uuid...>
+  cards
+    .command("ls")
+    .description("対象デバイスのカード一覧 (getCards。pub*LinkedIDs の async push を集約して返す)")
+    .option("-d, --device <uuid...>", DEVICE_OPT_DESC)
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        const devices = normalizeDevices(subOpts.device);
+        const deviceUUIDs = await resolveDeviceUUIDs(hub, ctx, devices, "sesame access cards ls --device <uuid...>");
+        if (!deviceUUIDs) return;
+        const { items, byDevice } = await hub.access.getCards({ deviceUUIDs });
+        ctx.out(opts.json, () => {
+          if (!Array.isArray(items) || items.length === 0) {
+            console.log("(no cards)");
+            return;
+          }
+          console.log(`Found ${items.length} card(s):`);
+          for (const c of items) {
+            const id = c.cardID ?? "(no-id)";
+            const nm = c.name ? ` ${c.name}` : "";
+            const ty = c.cardType != null ? ` type=${c.cardType}` : "";
+            console.log(`  ${id}${nm}${ty}\t[${(c.uuids || []).join(",")}]`);
+          }
+        }, { ok: true, count: Array.isArray(items) ? items.length : 0, items, byDevice });
+      }),
+    );
+
+  // sesame access cards rm --json <items>
+  cards
+    .command("rm")
+    .description("カードを DB から削除 (delCards。fire-and-forget・応答 op なし)")
+    .option("--json <items>", 'items 配列の JSON。要素は {deviceID, cardID} (deviceUUID ではない)。')
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        // delCards は items 配列をトップレベルに置く構造。deviceUUID ではなく deviceID 注意。
+        if (!subOpts.json) {
+          ctx.die('--json <items> が必要です: 要素は {deviceID, cardID} の配列。', 2);
+          return;
+        }
+        const items = ctx.parseJson(subOpts.json, "items");
+        if (items === undefined) return;
+        if (!Array.isArray(items)) {
+          ctx.die("items は配列である必要があります。", 2);
+          return;
+        }
+        // 本体は boolean を返す (送信したら true、空配列なら false)。応答 op は来ない。
+        const sent = hub.access.delCards({ items });
+        ctx.out(opts.json, () => {
+          console.log(sent ? `OK: sent delCards for ${items.length} item(s)` : "(no items — nothing sent)");
+        }, { ok: true, sent, count: items.length });
+      }),
+    );
+
+  // sesame access cards clear --device <uuid>
+  cards
+    .command("clear")
+    .description("指定デバイスのカードを全削除 (clearCards。単一 deviceUUID)")
+    .option("-d, --device <uuid>", "対象 deviceUUID (省略時は対話選択)")
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        const devices = normalizeDevices(subOpts.device);
+        // clearCards は単一 deviceUUID のみ。複数渡されても先頭を使う。
+        const deviceUUIDs = await resolveDeviceUUIDs(hub, ctx, devices, "sesame access cards clear --device <uuid>");
+        if (!deviceUUIDs) return;
+        const deviceUUID = deviceUUIDs[0];
+        if (ctx.canPrompt()) {
+          const ok = await ctx.prompts.confirm(`デバイス ${deviceUUID} のカードを全削除しますか?`, { defaultYes: false });
+          if (!ok) {
+            console.error("中止しました。");
+            return;
+          }
+        }
+        const resp = await hub.access.clearCards({ deviceUUID });
+        ctx.out(opts.json, () => {
+          console.log(`OK: cleared cards on ${deviceUUID}`);
+        }, { ok: true, deviceUUID, response: resp });
+      }),
+    );
+
+  // sesame access cards name --json <item>
+  cards
+    .command("name")
+    .description("カード名 / nameUUID を更新 (updateCardName)")
+    .option(
+      "--json <item>",
+      'item の JSON: { cardID, name, cardNameUUID, timestamp?, cardType?, stpDeviceUUID }。' +
+        ' ⚠️ cardNameUUID が UUIDv4 でないと biz3 は BLE 前段を挟む。CLI は v4 を渡すこと。',
+    )
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        if (!subOpts.json) {
+          ctx.die('--json <item> が必要です: { cardID, name, cardNameUUID, stpDeviceUUID }。', 2);
+          return;
+        }
+        const item = ctx.parseJson(subOpts.json, "item");
+        if (item === undefined) return;
+        const resp = await hub.access.updateCardName({ item });
+        ctx.out(opts.json, () => {
+          console.log(`OK: updated card name (cardID=${item.cardID ?? "?"})`);
+        }, { ok: true, item, response: resp });
+      }),
+    );
+
+  // sesame access cards owner <cardID> [ownerSubUUID]
+  cards
+    .command("owner <cardID> [ownerSubUUID]")
+    .description("カードの所有者 (メンバー subUUID) を割当 (updateCardOwner)。省略で対話、空文字 '' で未割当解除")
+    .action((cardID, ownerSubUUID) =>
+      ctx.withHub(async (hub, { opts }) => {
+        // biz3: 'ownerSubUUID' in item の時だけ送る。undefined は送らない。'' は送って解除。
+        if (ownerSubUUID === undefined && ctx.canPrompt()) {
+          ownerSubUUID = await ctx.prompts.promptText(
+            "割当先 ownerSubUUID (空 Enter で未割当解除)",
+            { required: false, defaultValue: "" },
+          );
+        }
+        if (ownerSubUUID === undefined) {
+          ctx.die("ownerSubUUID が必要です (非対話モード。'' で未割当解除): sesame access cards owner <cardID> <ownerSubUUID>", 2);
+          return;
+        }
+        const resp = await hub.access.updateCardOwner({ cardID, ownerSubUUID });
+        ctx.out(opts.json, () => {
+          console.log(`OK: cardID=${cardID} owner -> ${ownerSubUUID === "" ? "(未割当)" : ownerSubUUID}`);
+        }, { ok: true, cardID, ownerSubUUID, response: resp });
+      }),
+    );
+
+  // sesame access cards post --device <uuid> --json <list>
+  cards
+    .command("post")
+    .description("カードを DB に登録 (postCards。⚠️ DB 同期のみ。実機書き込みは別系統 BLE)")
+    .option("-d, --device <uuid>", "登録先 deviceUUID (省略時は対話選択)")
+    .option("--json <list>", 'list 配列の JSON。要素は { cardID, nameUUID, name, cardType, memberID? } 等。')
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        if (!subOpts.json) {
+          ctx.die('--json <list> が必要です: カード要素の配列。', 2);
+          return;
+        }
+        const list = ctx.parseJson(subOpts.json, "list");
+        if (list === undefined) return;
+        if (!Array.isArray(list)) {
+          ctx.die("list は配列である必要があります。", 2);
+          return;
+        }
+        const devices = normalizeDevices(subOpts.device);
+        const deviceUUIDs = await resolveDeviceUUIDs(hub, ctx, devices, "sesame access cards post --device <uuid> --json <list>");
+        if (!deviceUUIDs) return;
+        const deviceUUID = deviceUUIDs[0];
+        // 本体は list.length < 1 なら null を返す。
+        const resp = await hub.access.postCards({ deviceUUID, list });
+        ctx.out(opts.json, () => {
+          console.log(resp === null ? "(empty list — nothing posted)" : `OK: posted ${list.length} card(s) to ${deviceUUID}`);
+        }, { ok: true, deviceUUID, count: list.length, response: resp });
+      }),
+    );
+
+  // ===== パスコード =====
+  const passcodes = access.command("passcodes").description("キーパッド暗証番号 (DB 同期)");
+
+  // sesame access passcodes ls --device <uuid...>
+  passcodes
+    .command("ls")
+    .description("対象デバイスの暗証番号一覧 (getPasscodes。pubPasscodeLinkedIDs を集約して返す)")
+    .option("-d, --device <uuid...>", DEVICE_OPT_DESC)
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        const devices = normalizeDevices(subOpts.device);
+        const deviceUUIDs = await resolveDeviceUUIDs(hub, ctx, devices, "sesame access passcodes ls --device <uuid...>");
+        if (!deviceUUIDs) return;
+        const { items, byDevice } = await hub.access.getPasscodes({ deviceUUIDs });
+        ctx.out(opts.json, () => {
+          if (!Array.isArray(items) || items.length === 0) {
+            console.log("(no passcodes)");
+            return;
+          }
+          console.log(`Found ${items.length} passcode(s):`);
+          for (const p of items) {
+            const id = p.passwordID ?? "(no-id)";
+            const nm = p.name ? ` ${p.name}` : "";
+            console.log(`  ${id}${nm}\t[${(p.uuids || []).join(",")}]`);
+          }
+        }, { ok: true, count: Array.isArray(items) ? items.length : 0, items, byDevice });
+      }),
+    );
+
+  // sesame access passcodes rm --json <items>
+  passcodes
+    .command("rm")
+    .description("暗証番号を DB から削除 (delPasscodes。fire-and-forget・応答 op なし)")
+    .option("--json <items>", 'items 配列の JSON。要素は {deviceID, passwordID}。')
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        if (!subOpts.json) {
+          ctx.die('--json <items> が必要です: 要素は {deviceID, passwordID} の配列。', 2);
+          return;
+        }
+        const items = ctx.parseJson(subOpts.json, "items");
+        if (items === undefined) return;
+        if (!Array.isArray(items)) {
+          ctx.die("items は配列である必要があります。", 2);
+          return;
+        }
+        const sent = hub.access.delPasscodes({ items });
+        ctx.out(opts.json, () => {
+          console.log(sent ? `OK: sent delPasscodes for ${items.length} item(s)` : "(no items — nothing sent)");
+        }, { ok: true, sent, count: items.length });
+      }),
+    );
+
+  // sesame access passcodes clear --device <uuid>
+  passcodes
+    .command("clear")
+    .description("指定デバイスの暗証番号を全削除 (clearPasscodes。単一 deviceUUID)")
+    .option("-d, --device <uuid>", "対象 deviceUUID (省略時は対話選択)")
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        const devices = normalizeDevices(subOpts.device);
+        const deviceUUIDs = await resolveDeviceUUIDs(hub, ctx, devices, "sesame access passcodes clear --device <uuid>");
+        if (!deviceUUIDs) return;
+        const deviceUUID = deviceUUIDs[0];
+        if (ctx.canPrompt()) {
+          const ok = await ctx.prompts.confirm(`デバイス ${deviceUUID} の暗証番号を全削除しますか?`, { defaultYes: false });
+          if (!ok) {
+            console.error("中止しました。");
+            return;
+          }
+        }
+        const resp = await hub.access.clearPasscodes({ deviceUUID });
+        ctx.out(opts.json, () => {
+          console.log(`OK: cleared passcodes on ${deviceUUID}`);
+        }, { ok: true, deviceUUID, response: resp });
+      }),
+    );
+
+  // sesame access passcodes name --json <item>
+  passcodes
+    .command("name")
+    .description("暗証番号名 / nameUUID を更新 (updatePasscodeName)")
+    .option(
+      "--json <item>",
+      'item の JSON: { stpDeviceUUID, keyBoardPassCode, keyBoardPassCodeNameUUID, name }。' +
+        ' ⚠️ keyBoardPassCodeNameUUID が UUIDv4 でないと biz3 は BLE 前段を挟む。CLI は v4 を渡すこと。',
+    )
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        if (!subOpts.json) {
+          ctx.die('--json <item> が必要です: { stpDeviceUUID, keyBoardPassCode, keyBoardPassCodeNameUUID, name }。', 2);
+          return;
+        }
+        const item = ctx.parseJson(subOpts.json, "item");
+        if (item === undefined) return;
+        const resp = await hub.access.updatePasscodeName({ item });
+        ctx.out(opts.json, () => {
+          console.log(`OK: updated passcode name (keyBoardPassCode=${item.keyBoardPassCode ?? "?"})`);
+        }, { ok: true, item, response: resp });
+      }),
+    );
+
+  // sesame access passcodes post --device <uuid> --json <list>
+  passcodes
+    .command("post")
+    .description("暗証番号を DB に登録 (postPasscodes。⚠️ DB 同期のみ。list 要素は未確認・実機検証要)")
+    .option("-d, --device <uuid>", "登録先 deviceUUID (省略時は対話選択)")
+    .option("--json <list>", 'list 配列の JSON。要素フィールドは biz3 上では未確認 (getPasscodes 応答 item と対応と推測)。')
+    .action((subOpts) =>
+      ctx.withHub(async (hub, { opts }) => {
+        if (!subOpts.json) {
+          ctx.die('--json <list> が必要です: 暗証番号要素の配列。', 2);
+          return;
+        }
+        const list = ctx.parseJson(subOpts.json, "list");
+        if (list === undefined) return;
+        if (!Array.isArray(list)) {
+          ctx.die("list は配列である必要があります。", 2);
+          return;
+        }
+        const devices = normalizeDevices(subOpts.device);
+        const deviceUUIDs = await resolveDeviceUUIDs(hub, ctx, devices, "sesame access passcodes post --device <uuid> --json <list>");
+        if (!deviceUUIDs) return;
+        const deviceUUID = deviceUUIDs[0];
+        const resp = await hub.access.postPasscodes({ deviceUUID, list });
+        ctx.out(opts.json, () => {
+          console.log(resp === null ? "(empty list — nothing posted)" : `OK: posted ${list.length} passcode(s) to ${deviceUUID}`);
+        }, { ok: true, deviceUUID, count: list.length, response: resp });
+      }),
+    );
+}