sesame-kit 0.4.0

package/src/schedule.js

@@ -0,0 +1,108 @@
+// 予約実行スケジュール管理 (biz3Schedule)。
+//
+// Ported from biz3 (CANDY-HOUSE/biz3, MIT):
+//   - vendor reference: references_web/src/api/useManageSchedule.js
+//   - item フィールド: references_web/src/pages/biz/schedule-list/index.js
+//
+// 概要:
+//   biz3Schedule は「指定時刻に lock / unlock / upgrade_firmware を実行する」予約の
+//   一覧取得 (getScheduleList) と取消 (cancelSchedule) の 2 op のみ。
+//   スケジュールの新規作成 op は biz3 web 側に存在しない (createSchedule/addSchedule とも
+//   grep でヒットせず: references_web/src 全体)。登録は別経路/別アプリ由来の可能性があるが
+//   本ファイル群からは未確認。CLI は list + cancel に限定する。
+//
+// フレームの要点 (useManageSchedule.js を 1 行ずつ確認):
+//   - フラットな JSON。obj ラップ無し。companyID / apiKeyId は付与しない。
+//   - userId フィールドに gStripe.customerInfo.subUUID を **加工せず** そのまま入れる
+//     (大文字化やハイフン加工なし / useManageSchedule.js:13,17,52,56)。
+//   - subUUID が falsy なら送信自体を中止 (useManageSchedule.js:14,53 は return)。
+//   - 応答は action+op で dispatch される (useCallbacks.js:17-31 が action→op の 2 段照合 /
+//     registerCallback(action, messageData.op, cb))。よって request の op を frame に
+//     乗せれば transport の `${action}:${op}` キーで一致する。
+
+import { ACTION_TYPES } from "../vendor/biz3/constants/messageConstants.js";
+
+// action 文字列は vendor (biz3 messageConstants) から引く (手書きしない)。
+// messageConstants.js:21  BIZ3_SCHEDULE: 'biz3Schedule'
+const ACT_SCHEDULE = ACTION_TYPES.BIZ3_SCHEDULE; // "biz3Schedule"
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * @typedef {Object} ScheduleItem
+ * @property {string} scheduleId  取消に使う ID (schedule-list/index.js:49,82,102)
+ * @property {string} action      'lock' | 'unlock' | 'upgrade_firmware' 等
+ *                                 (schedule-list/index.js:77 / UI ラベルは正規化された表示用で
+ *                                  サーバ側の正式 enum は未確認)
+ * @property {string} displayTime '2026-01-01 09:00' または 'HH:MM' 形式 (index.js:78,31)
+ * @property {string} deviceName  対象デバイス名 (index.js:92)
+ */
+
+/**
+ * サーバに登録済みの予約スケジュール一覧を取得する。
+ *
+ * フレーム: { action: "biz3Schedule", userId: <subUUID>, op: "getScheduleList" }
+ * 応答:     { action: "biz3Schedule", op: "getScheduleList", data: [ ScheduleItem, ... ] }
+ *           message.data は **オブジェクトでラップされず直接配列** (useManageSchedule.js:34-35
+ *           が count=data.length / Items=data に自前で詰め替えている点に注意)。
+ *
+ * @param {import("./transport.js").Hub3WsClient} client
+ * @param {{subUUID:string, timeoutMs?:number}} params
+ *   subUUID は gStripe.customerInfo.subUUID 相当 (生の文字列をそのまま userId に入れる)
+ * @returns {Promise<ScheduleItem[]>} スケジュール item の配列 (空なら [])
+ */
+export async function getScheduleList(client, { subUUID, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  // biz3: subUUID が falsy なら送信自体を中止 (useManageSchedule.js:14)。
+  if (!subUUID) throw new Error("subUUID required (gStripe.customerInfo.subUUID)");
+
+  // フィールド順は原典 (useManageSchedule.js:15-19) のリテラル順 action, userId, op に合わせる。
+  const frame = {
+    action: ACT_SCHEDULE,
+    userId: subUUID,
+    op: "getScheduleList",
+  };
+  const resp = await client.request(frame, timeoutMs);
+  if (resp && resp.success === false) {
+    throw new Error(`getScheduleList failed: ${resp.message || JSON.stringify(resp)}`);
+  }
+  // 応答 data は配列直返し (useManageSchedule.js:34-35)。欠落時は空配列。
+  return Array.isArray(resp?.data) ? resp.data : [];
+}
+
+/**
+ * 予約スケジュールを 1 件取消す。
+ *
+ * フレーム: { action: "biz3Schedule", userId: <subUUID>, scheduleId: <scheduleId>, op: "cancelSchedule" }
+ *           (フィールド順は原典 useManageSchedule.js:54-59 のリテラル順)
+ * 応答:     { action: "biz3Schedule", op: "cancelSchedule", ... }
+ *
+ * 未確認: cancelSchedule 応答 data の具体構造は web コードからは判別不可。biz3 hook の switch
+ * には cancelSchedule ケースが無く (useManageSchedule.js:31-41 は getScheduleList のみ)、
+ * 完了は registerCallback の cb 受信 (= ack) でしか確認していない。UI は楽観的に isCancelling
+ * フラグを立てるだけ (schedule-list/index.js:47-51)。よって本実装は **ack 受信=成功** とみなし、
+ * resp.success が明示的に false の場合のみ throw する。成功フラグ等の data 形は実機検証要。
+ *
+ * @param {import("./transport.js").Hub3WsClient} client
+ * @param {{subUUID:string, scheduleId:string, timeoutMs?:number}} params
+ *   scheduleId は getScheduleList で得た item.scheduleId をそのまま渡す。
+ * @returns {Promise<any>} サーバ応答 (ack)。data の構造は未確認のため raw を返す。
+ */
+export async function cancelSchedule(client, { subUUID, scheduleId, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  // biz3: subUUID が falsy なら送信中止 (useManageSchedule.js:53)。
+  if (!subUUID) throw new Error("subUUID required (gStripe.customerInfo.subUUID)");
+  if (!scheduleId) throw new Error("scheduleId required");
+
+  const frame = {
+    action: ACT_SCHEDULE,
+    userId: subUUID,
+    scheduleId,
+    op: "cancelSchedule",
+  };
+  const resp = await client.request(frame, timeoutMs);
+  if (resp && resp.success === false) {
+    throw new Error(`cancelSchedule failed: ${resp.message || JSON.stringify(resp)}`);
+  }
+  return resp;
+}
+
+// 公開 op の allowlist (SesameHub3._bindNs / serve registry が参照する単一の真実)。
+export const NAMESPACE_OPS = ["getScheduleList", "cancelSchedule"];

package/src/serve/daemon.js

@@ -0,0 +1,251 @@
+// Daemon — 単一常駐 hub の上に JSON-RPC を多重化する中核。
+//
+// 全フレーミング (stdio/UDS/HTTP/WS/gRPC) はここに Connection を addConnection し、
+// 受信行を handleLine に渡すだけ。Daemon は:
+//   - registry 解決 + rpc.discover
+//   - **メソッド名単位の直列化** (複数クライアントの同一 op 応答入替を防ぐ。
+//     WS の FIFO リゾルバは (action:op) 単位グローバルなため)
+//   - 購読を **daemon が一元所有** (Map<Connection,Set<topic>>)、hub の状態 push を
+//     **1 本だけ**張って購読 Connection へ fan-out (リスナ爆発・IR 副作用を回避)
+//   - authState 管理、起動ポリシー (framing 先・connect 再試行・degraded)、graceful shutdown
+//
+// Connection 契約 (framing が実装): { id:string, send(obj):void, close():void }
+//   send はフレーミング固有の直列化 + 背圧を担う (溢れたらその接続を切る)。
+
+import { handleMessage, makeEvent, RpcError, RPC, KIND } from "./jsonrpc.js";
+import { buildRegistry, buildOpenRpcDoc } from "./registry.js";
+import { TRANSPORT_ERR } from "../transport.js";
+
+const TOPICS = ["lockState", "deviceUpdate"];
+
+/**
+ * handler が投げた素の Error を kind 付き RpcError へ正規化する。判定は transport が付ける
+ * **構造化コード (.code = TRANSPORT_ERR.*)** で行う (跨モジュールの脆弱な文字列正規表現を排除)。
+ * 該当しなければそのまま返し、errorFromThrow が internal にフォールバックする。
+ */
+function classifyError(e) {
+  if (e instanceof RpcError) return e;
+  if (e?.code === TRANSPORT_ERR.TIMEOUT) return new RpcError(String(e.message), { code: RPC.APP_ERROR, kind: KIND.TIMEOUT });
+  if (e?.code === TRANSPORT_ERR.CLOSED) return new RpcError(String(e.message), { code: RPC.APP_ERROR, kind: KIND.CONNECTION_LOST });
+  return e;
+}
+
+export class Daemon {
+  /**
+   * @param {{ hub: object, version?: string, debug?: boolean }} args
+   *   hub は SesameHub3 (テストでは狭いインターフェースの fake)。
+   */
+  constructor({ hub, version = "0.0.0", debug = false }) {
+    if (!hub) throw new Error("hub required");
+    this.hub = hub;
+    this.version = version;
+    this._debug = debug;
+    this.authState = "degraded"; // ok | degraded | expired
+    this._registry = buildRegistry();
+    this._openrpc = buildOpenRpcDoc(this._registry, version);
+    /** @type {Map<string, Promise<any>>} メソッド名→直列化チェーン末尾 */
+    this._locks = new Map();
+    /** @type {Map<object, Set<string>>} Connection→購読 topic */
+    this._subs = new Map();
+    /** hub 状態 push の単一購読の unsubscribe (張っている時のみ非 null) */
+    this._stateUnsub = null;
+    this._stopped = false;
+    this._shuttingDown = false;
+    this._retryTimer = null;
+  }
+
+  _log(...a) { if (this._debug) console.error("[serve]", ...a); }
+
+  // ---- 起動ポリシー (framing は先に上がっている前提。ここは背景で接続を試みる) ----
+  start() {
+    // 再接続のたびに購読を張り直す (C1: subscribe frame 再送が無いとイベントが永久に止まる)。
+    if (typeof this.hub.onReconnect === "function") {
+      this.hub.onReconnect(() => this._reestablishStateSub());
+    }
+    this._connectLoop();
+  }
+
+  async _connectLoop() {
+    let delay = 1000;
+    while (!this._stopped) {
+      try {
+        await this.hub.connect();
+        this.authState = "ok";
+        this._log("cloud connected");
+        this._ensureStateSub();
+        return;
+      } catch (e) {
+        // 認証状態は error 文字列の正規表現ではなく、トークンの有無で決定的に分類する。
+        //   トークンが無い (未ログイン) → expired (= not_authenticated を即返す。"sesame login" 案内)
+        //   トークンはある → degraded (ネットワーク不通等。背景で再試行して復帰を拾う)
+        this.authState = this._hasStoredTokens() ? "degraded" : "expired";
+        // 接続失敗は --debug でなくても見えるように (未ログイン等を初学者が気付けるよう)。
+        console.error(`[serve] cloud connect failed (${this.authState}): ${String(e?.message || e).slice(0, 160)}`);
+        await this._sleep(delay);
+        delay = Math.min(delay * 2, 30000);
+      }
+    }
+  }
+
+  _hasStoredTokens() {
+    try {
+      const t = this.hub.tokenStore?.load?.();
+      return !!(t && (t.refreshToken || t.idToken));
+    } catch { return false; }
+  }
+
+  /** キャンセル可能な sleep。shutdown 時に即 resolve してループを抜けさせる。 */
+  _sleep(ms) {
+    return new Promise((resolve) => {
+      this._retryResolve = resolve;
+      this._retryTimer = setTimeout(() => { this._retryResolve = null; resolve(); }, ms);
+    });
+  }
+
+  // ---- Connection 管理 ----
+  addConnection(conn) { this._subs.set(conn, new Set()); }
+
+  removeConnection(conn) {
+    this._subs.delete(conn);
+    this._maybeTeardownStateSub();
+  }
+
+  // ---- 受信処理 ----
+  /** 1 メッセージを処理して応答オブジェクト (通知なら null) を返す。push はしない (HTTP POST 用)。 */
+  dispatchMessage(conn, raw) {
+    return handleMessage(raw, (method, params) => this.invoke(method, params, conn));
+  }
+
+  /** framing から: 1 行を処理し、応答があれば conn.send で push する。throw しない。 */
+  async handleLine(conn, raw) {
+    const res = await this.dispatchMessage(conn, raw);
+    if (res) {
+      try { conn.send(res); } catch (e) { this._log("send failed:", e?.message); }
+    }
+  }
+
+  /** メソッド実行。registry 解決 + rpc.discover + メソッド名単位の直列化。常に Promise を返す。 */
+  async invoke(method, params, conn) {
+    if (method === "rpc.discover") return this._openrpc;
+    if (method.startsWith("rpc.")) {
+      throw new RpcError(`Method not found: ${method}`, { code: RPC.METHOD_NOT_FOUND, kind: KIND.NOT_IMPLEMENTED });
+    }
+    const entry = this._registry.get(method);
+    if (!entry) {
+      throw new RpcError(`Method not found: ${method}`, { code: RPC.METHOD_NOT_FOUND, kind: KIND.NOT_IMPLEMENTED });
+    }
+    const p = params == null ? {} : params;
+    if (typeof p !== "object" || Array.isArray(p)) {
+      throw new RpcError("params must be an object", { code: RPC.INVALID_PARAMS, kind: KIND.BAD_PARAMS });
+    }
+    const run = async () => {
+      try {
+        return await entry.handler({ hub: this.hub, params: p, conn, daemon: this });
+      } catch (e) {
+        throw classifyError(e); // transport 由来の timeout/切断を kind 付きに
+      }
+    };
+    return this._serialize(method, run);
+  }
+
+  /**
+   * 同名メソッドを直列化する。これは応答入替の主防御ではなく (request() ベースの op は
+   * transport の (action:op) FIFO が保証する) **listDevices 等 onMessage 先着 resolve で
+   * 解決する op** を、複数クライアント同時呼び出しから守る防御。同名 op を 1 並行に絞る。
+   */
+  _serialize(key, run) {
+    const prev = this._locks.get(key) || Promise.resolve();
+    const p = prev.then(run, run); // 前段の成否に関わらず次を実行
+    // チェーンが無限に伸びないよう、解決したら掃除 (自分が末尾なら削除)
+    const tail = p.catch(() => {});
+    this._locks.set(key, tail);
+    tail.then(() => { if (this._locks.get(key) === tail) this._locks.delete(key); });
+    return p;
+  }
+
+  // ---- 購読 (daemon 一元所有) ----
+  subscribe(conn, topics) {
+    const set = this._subs.get(conn);
+    if (!set) throw new RpcError("connection not registered", { kind: KIND.INTERNAL });
+    for (const t of topics) set.add(t);
+    this._ensureStateSub();
+    return { subscribed: [...set] };
+  }
+
+  unsubscribe(conn, topics) {
+    const set = this._subs.get(conn);
+    if (!set) return { subscribed: [] };
+    for (const t of topics) set.delete(t);
+    this._maybeTeardownStateSub();
+    return { subscribed: [...set] };
+  }
+
+  _anySubscribers() {
+    for (const set of this._subs.values()) if (set.size) return true;
+    return false;
+  }
+
+  /** 状態 push の単一購読を (必要なら) 張る。hub 未接続なら接続時に再試行。 */
+  _ensureStateSub() {
+    if (this._stateUnsub || !this.hub.connected) return;
+    try {
+      // config 上の devices を items に (サーバへ subscribe frame を送るため)。
+      const devices = (this.hub.config && this.hub.config.devices) || {};
+      const items = Object.values(devices).map((d) => ({ deviceUUID: d.deviceUUID, deviceModel: d.deviceModel }));
+      this._stateUnsub = this.hub.onDeviceUpdate(items, (msg) => this._fanout(msg));
+      this._log("state subscription established");
+    } catch (e) {
+      this._log("state sub failed:", e?.message);
+    }
+  }
+
+  _reestablishStateSub() {
+    // 再接続後に購読者が居れば張り直す (サーバ側 subscribe frame は再送が要るため)。
+    // 旧 unsub を必ず呼んでから張り直す。呼ばないと transport の subscribers に古い fn が
+    // 残り、新 fn と二重配信になる (subscribers は再接続を跨いで保持されるため)。
+    if (this._stateUnsub) { try { this._stateUnsub(); } catch { /* ignore */ } this._stateUnsub = null; }
+    if (this._anySubscribers()) this._ensureStateSub();
+  }
+
+  _maybeTeardownStateSub() {
+    if (this._stateUnsub && !this._anySubscribers()) {
+      try { this._stateUnsub(); } catch { /* ignore */ }
+      this._stateUnsub = null;
+      this._log("state subscription torn down");
+    }
+  }
+
+  /**
+   * 状態 push を購読 Connection へ配信する。
+   * 注: lockState と deviceUpdate は現状どちらも biz3 の pubDeviceStateChange を源とする
+   * (同一ストリームの別ラベル)。両方購読している接続には **1 回だけ** 配信する
+   * (最初に購読している topic のラベルで) — 同一イベントの二重配信を避ける。
+   */
+  _fanout(msg) {
+    for (const [conn, set] of this._subs) {
+      const topic = TOPICS.find((t) => set.has(t));
+      if (topic) {
+        try { conn.send(makeEvent(topic, msg)); } catch { /* framing 背圧で切断済み等 */ }
+      }
+    }
+  }
+
+  // ---- shutdown ----
+  /** 冪等。受付停止 → hub.close()(=_pendingCleanups 実行) → 解決。 */
+  async shutdown() {
+    if (this._shuttingDown) return;
+    this._shuttingDown = true;
+    this._stopped = true;
+    if (this._retryTimer) clearTimeout(this._retryTimer);
+    if (this._retryResolve) { this._retryResolve(); this._retryResolve = null; } // connectLoop の sleep を即解除
+    if (this._stateUnsub) { try { this._stateUnsub(); } catch { /* ignore */ } this._stateUnsub = null; }
+    try { await this.hub.close(); } catch (e) { this._log("hub.close error:", e?.message); }
+  }
+
+  /** 購読可能な topic 一覧 (framing が事前検証に使う)。 */
+  get topics() { return TOPICS; }
+
+  /** テスト/イントロスペクション用。 */
+  get registry() { return this._registry; }
+  get openrpc() { return this._openrpc; }
+}

package/src/serve/framing/grpc.js

@@ -0,0 +1,145 @@
+// gRPC フレーミング: **型付き**。op ごとに型付き Request message + 型付き service メソッドを
+// 生成 (scripts/gen-grpc-proto.mjs)。利用者は `LockUnlock({name})` のように型付きで呼べる。
+//   - request: scalar/string配列は protobuf 型、object/動的な葉は JSON 文字列 field (glue が parse)
+//   - response: 動的なので JsonRpc{json} で運ぶ (1 回 JSON.parse)
+//   - Subscribe: topics 購読 → Event{topic, json} stream
+//   - Invoke: 後方互換の汎用 JSON-RPC 経路
+// loopback token を metadata (authorization: Bearer) か SubReq.token で要求。
+
+import { readFileSync } from "node:fs";
+import grpc from "@grpc/grpc-js";
+import protoLoader from "@grpc/proto-loader";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { tokenMatches } from "./token.js";
+import { RpcError } from "../jsonrpc.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PROTO_PATH = resolve(HERE, "..", "sesame.proto");
+const MAP_PATH = resolve(HERE, "..", "grpc-methods.generated.json");
+
+/** server streaming で非 OK status を返す。grpc-js (1.14) では `call.destroy()` は status を
+ *  クライアントに伝えず黙ってハングするため、`emit("error", {code, details})` で返す (実測で確認)。 */
+function endStreamWithError(call, code, message) {
+  call.emit("error", { code, details: message });
+}
+
+/** RpcError.kind → gRPC status (gRPC の作法に沿って status でエラーを返す)。 */
+function grpcStatusFor(kind) {
+  switch (kind) {
+    case "not_authenticated": return grpc.status.UNAUTHENTICATED;
+    case "bad_params": return grpc.status.INVALID_ARGUMENT;
+    case "not_implemented": return grpc.status.UNIMPLEMENTED;
+    case "connection_lost":
+    case "timeout": return grpc.status.UNAVAILABLE;
+    default: return grpc.status.INTERNAL;
+  }
+}
+
+function metaToken(call) {
+  const md = call.metadata?.get?.("authorization");
+  const raw = md && md[0] ? String(md[0]) : "";
+  return /^Bearer\s+(.+)$/i.exec(raw)?.[1] || "";
+}
+
+/**
+ * @param {import("../daemon.js").Daemon} daemon
+ * @param {{ bind?:string, port:number, token:string }} opts
+ * @returns {Promise<{ port:number, stop:()=>Promise<void> }>}
+ */
+export async function startGrpcFraming(daemon, { bind = "127.0.0.1", port, token }) {
+  const pkgDef = protoLoader.loadSync(PROTO_PATH, { keepCase: true, longs: String, defaults: true });
+  const proto = grpc.loadPackageDefinition(pkgDef).sesame;
+  const methodMap = JSON.parse(readFileSync(MAP_PATH, "utf8")); // Pascal → {method, jsonFields}
+  const server = new grpc.Server();
+
+  const impl = {};
+
+  // 型付き unary メソッドを一括登録 (handler は generic に daemon.invoke へ委譲)。
+  for (const [pascal, { method, jsonFields }] of Object.entries(methodMap)) {
+    impl[pascal] = async (call, callback) => {
+      if (!tokenMatches(metaToken(call), token)) return callback({ code: grpc.status.UNAUTHENTICATED, message: "unauthorized" });
+      const params = { ...call.request };
+      for (const f of jsonFields) {
+        if (params[f] === undefined || params[f] === "") { delete params[f]; continue; } // 空=未指定
+        try { params[f] = JSON.parse(params[f]); } catch { return callback({ code: grpc.status.INVALID_ARGUMENT, message: `field "${f}" must be JSON` }); }
+      }
+      const conn = { id: "grpc", ephemeral: true, send() {}, close() {} };
+      daemon.addConnection(conn);
+      try {
+        const result = await daemon.invoke(method, params, conn);
+        callback(null, { json: JSON.stringify(result ?? null) });
+      } catch (e) {
+        const kind = e instanceof RpcError ? e.kind : "internal";
+        const md = new grpc.Metadata(); if (kind) md.set("kind", kind);
+        callback({ code: grpcStatusFor(kind), message: e?.message || "error", metadata: md });
+      } finally {
+        daemon.removeConnection(conn);
+      }
+    };
+  }
+
+  // 後方互換: 任意の JSON-RPC を文字列で運ぶ。
+  impl.Invoke = async (call, callback) => {
+    if (!tokenMatches(metaToken(call), token)) return callback({ code: grpc.status.UNAUTHENTICATED, message: "unauthorized" });
+    const conn = { id: "grpc", ephemeral: true, send() {}, close() {} };
+    daemon.addConnection(conn);
+    let out;
+    try { out = await daemon.dispatchMessage(conn, call.request.json || ""); }
+    finally { daemon.removeConnection(conn); }
+    callback(null, { json: out === null ? "" : JSON.stringify(out) });
+  };
+
+  // イベント購読ストリーム。
+  impl.Subscribe = (call) => {
+    const provided = call.request.token || metaToken(call);
+    if (!tokenMatches(provided, token)) { endStreamWithError(call, grpc.status.UNAUTHENTICATED, "unauthorized"); return; }
+    let buffered = 0;
+    const MAX_BUFFERED = 4 * 1024 * 1024;
+    call.on("drain", () => { buffered = 0; });
+    const conn = {
+      id: "grpc-sub",
+      send: (obj) => {
+        const topic = String(obj.method || "").replace(/^event\./, "");
+        const json = JSON.stringify(obj.params ?? null);
+        try { const ok = call.write({ topic, json }); if (!ok) { buffered += json.length; if (buffered > MAX_BUFFERED) conn.close(); } }
+        catch { /* closed */ }
+      },
+      close: () => { try { call.end(); } catch { /* ignore */ } },
+    };
+    daemon.addConnection(conn);
+    const topics = (call.request.topics || []).filter(Boolean);
+    // 不正 topic は黙殺せず INVALID_ARGUMENT でストリームを閉じる (WS/SSE と同じく拒否。
+    // 黙ってハングするストリームを返すと『gRPC だけイベントが来ない』のデバッグが不能になる)。
+    // daemon.subscribe 自体は検証しないので、ここで daemon.topics に対して明示検証する。
+    const bad = topics.filter((t) => !daemon.topics.includes(t));
+    if (bad.length) {
+      daemon.removeConnection(conn);
+      endStreamWithError(call, grpc.status.INVALID_ARGUMENT, `unknown topic(s): ${bad.join(",")}`);
+      return;
+    }
+    if (topics.length) daemon.subscribe(conn, topics);
+    call.on("cancelled", () => daemon.removeConnection(conn));
+    call.on("close", () => daemon.removeConnection(conn));
+  };
+
+  server.addService(proto.Sesame.service, impl);
+
+  const boundPort = await new Promise((resolve2, reject) => {
+    server.bindAsync(`${bind}:${port}`, grpc.ServerCredentials.createInsecure(), (err, p) => {
+      if (err) reject(err); else resolve2(p);
+    });
+  });
+  return {
+    port: boundPort,
+    // tryShutdown は Subscribe ストリームが開いている限り待ち続けるため、まず graceful を試み、
+    // 1s で畳めなければ forceShutdown で全 call を即キャンセルしてハングを断つ。
+    stop: () => new Promise((resolve2) => {
+      let done = false;
+      const finish = () => { if (!done) { done = true; resolve2(); } };
+      const t = setTimeout(() => { try { server.forceShutdown(); } catch { /* ignore */ } finish(); }, 1000);
+      t.unref?.();
+      server.tryShutdown(() => { clearTimeout(t); finish(); });
+    }),
+  };
+}

package/src/serve/framing/http.js

@@ -0,0 +1,144 @@
+// HTTP フレーミング: 全言語/ブラウザから叩ける。
+//   POST /rpc      → 1 件の JSON-RPC を処理し応答を返す (request/response 専用、購読は持続しない)
+//   GET  /events   → SSE。?topics=lockState,deviceUpdate を購読し event を流す (購読チャネル)
+// 全エンドポイントで loopback token (Authorization: Bearer / ?token=) 必須。
+
+import http from "node:http";
+import { makeError, RPC, KIND } from "../jsonrpc.js";
+import { tokenMatches, extractToken } from "./token.js";
+
+const MAX_BODY = 1_000_000; // 1MB 上限 (過大 body 拒否)
+
+/**
+ * @param {import("../daemon.js").Daemon} daemon
+ * @param {{ bind?:string, port:number, token:string }} opts
+ * @returns {Promise<{ url:string, stop:()=>Promise<void> }>}
+ */
+export async function startHttpFraming(daemon, { bind = "127.0.0.1", port, token }) {
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, "http://localhost");
+
+    // GET / は token 不要の人間向け案内 (ブラウザで開いた初学者が迷子にならないように)。
+    if (req.method === "GET" && url.pathname === "/") {
+      res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+      res.end([
+        "sesame serve is running (JSON-RPC 2.0).",
+        "",
+        "Endpoints (Authorization: Bearer <token> required):",
+        "  POST /rpc     - send one JSON-RPC request, get one response",
+        "  GET  /events  - SSE event stream (?topics=lockState,deviceUpdate)",
+        "",
+        "The token was printed to stderr when the daemon started.",
+        "List all methods:",
+        `  curl -s -H "Authorization: Bearer <token>" \\`,
+        `    -d '{"jsonrpc":"2.0","id":1,"method":"rpc.discover"}' http://${bind}:${port}/rpc`,
+        "",
+        "Watch events (SSE):",
+        `  curl -N -H "Authorization: Bearer <token>" "http://${bind}:${port}/events?topics=lockState"`,
+        "",
+      ].join("\n"));
+      return;
+    }
+
+    if (!tokenMatches(extractToken(req), token)) {
+      res.writeHead(401, {
+        "content-type": "application/json",
+        "www-authenticate": 'Bearer realm="sesame"', // クライアントに token 必須を明示
+      });
+      res.end(JSON.stringify({ error: "unauthorized", hint: "Authorization: Bearer <token> (token は serve 起動時に stderr へ表示)" }));
+      return;
+    }
+
+    if (req.method === "POST" && url.pathname === "/rpc") {
+      const chunks = [];
+      let size = 0;
+      let discarded = 0;
+      let aborted = false;
+      // req の error を握る (未処理だとグローバル uncaughtException 経由で daemon 全停止しうる)。
+      req.on("error", () => { aborted = true; });
+      req.on("data", (c) => {
+        if (aborted) {
+          // 413 送出後: 残り body を**破棄しつつ受け切る** (バッファには積まない=O(1) メモリ)。
+          // ここで socket を destroy するとクライアントの送信中 write が RST で失敗し、送った 413 を
+          // 受け取れず "fetch failed" になる。受け切れば応答が確実に届く。ただし悪質に巨大な
+          // アップロードは上限で打ち切る (DoS 防止)。
+          discarded += c.length;
+          if (discarded > MAX_BODY) { try { req.destroy(); } catch { /* ignore */ } }
+          return;
+        }
+        size += c.length;
+        if (size > MAX_BODY) { // 過大 body は 413 で明示拒否
+          aborted = true;
+          res.writeHead(413, { "content-type": "application/json", connection: "close" });
+          res.end(JSON.stringify({ error: "payload too large" }));
+          return;
+        }
+        chunks.push(c);
+      });
+      req.on("end", async () => {
+        if (aborted) return;
+        const body = Buffer.concat(chunks).toString("utf8"); // チャンク跨ぎ UTF-8 を正しく結合
+        // POST は短命接続 (購読は持続しない)。ephemeral=true で events.* を弾く。
+        const conn = { id: "http-rpc", ephemeral: true, send() {}, close() {} };
+        daemon.addConnection(conn);
+        let out;
+        try {
+          out = await daemon.dispatchMessage(conn, body);
+        } catch {
+          out = makeError(null, RPC.INTERNAL_ERROR, "internal", KIND.INTERNAL);
+        }
+        daemon.removeConnection(conn);
+        if (out === null) { res.writeHead(204); res.end(); return; } // 通知
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify(out));
+      });
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname === "/events") {
+      // topic を事前検証: 指定があるのに全部不正なら 400 (黙って無用なストリームを返さない)。
+      const reqTopics = (url.searchParams.get("topics") || "").split(",").map((s) => s.trim()).filter(Boolean);
+      const validTopics = reqTopics.filter((t) => daemon.topics.includes(t));
+      if (reqTopics.length && validTopics.length === 0) {
+        res.writeHead(400, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: `unknown topic(s): ${reqTopics.join(",")}`, valid: daemon.topics }));
+        return;
+      }
+      res.writeHead(200, {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+      });
+      res.write(": ok\n\n"); // 初期コメントでストリーム確立
+      const conn = {
+        id: "http-sse",
+        send: (obj) => { try { res.write(`data: ${JSON.stringify(obj)}\n\n`); } catch { /* closed */ } },
+        close: () => { try { res.end(); } catch { /* ignore */ } },
+      };
+      daemon.addConnection(conn);
+      try { if (validTopics.length) daemon.subscribe(conn, validTopics); } catch { /* ignore */ }
+      // ハートビート: 中継 proxy のアイドル切断を防ぎ、死んだ接続を検知する。
+      const heartbeat = setInterval(() => { try { res.write(": ping\n\n"); } catch { /* closed */ } }, 25000);
+      req.on("close", () => { clearInterval(heartbeat); daemon.removeConnection(conn); });
+      return;
+    }
+
+    res.writeHead(404, { "content-type": "application/json" });
+    res.end(JSON.stringify({ error: "not found" }));
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, bind, () => resolve());
+  });
+  const addr = server.address();
+  return {
+    url: `http://${bind}:${addr.port}`,
+    // SSE 購読者が keep-alive で居座ると server.close は idle 接続を閉じずハングするため、
+    // 全接続を能動 destroy してから close (closeAllConnections は Node 18.2+)。
+    stop: () => new Promise((resolve) => {
+      try { server.closeAllConnections?.(); } catch { /* ignore */ }
+      server.close(() => resolve());
+    }),
+  };
+}