dsh-remote-bridge 2.5.0 → 2.5.2

package/lib/index.d.ts

@@ -79,7 +79,32 @@ declare class WorkspaceDatabase {
   readonly trashDir: string;
   private readonly db;
   private closed;
+  /**
+   * 「设备集合或设备权限发生过写」的进程内单调计数。
+   *
+   * ## 为什么需要它
+   *
+   * WebSocket 广播的每一条事件都要确认「这条连接背后的设备还有效吗、scope/root 变了吗」
+   * —— 旧实现是**每条事件查一次库**（`getActiveDevice`）。多条连接 × 持续事件
+   * 就是成百次纯浪费的 SQLite 查询。
+   *
+   * 有了这个计数，`server.ts` 可以只在**它变了**的时候重新水化设备
+   * （特性探测：getter 不存在就退回逐事件查库，所以迟到或缺席都不会更差）。
+   *
+   * ## 语义（与 perf-reader 的 PERF-1 契约一致）
+   *
+   * 「任何改变**设备是否存在 / scope / rootIds** 的写」都要 +1。当前四处：
+   * `exchangePairing` / `updateDevice` / `revokeDevice` / `purgeRevokedDevices`。
+   *
+   * 根（roots）的增删**不** +1：设备记录本身没变；`/roots` 那条路径本来就是实时查库。
+   *
+   * 保守性：宁可多 +1（多一次缓存失效，代价是一次查询），不可漏 +1
+   * （漏了就是「撤销后仍能收事件」—— 那正是 `device-revocation` 要防的事）。
+   */
+  private devicesRevisionCounter;
   constructor(dataDir: string);
+  /** 当前设备状态版本号。用途见字段注释（`server.ts` 的广播缓存失效）。 */
+  get devicesRevision(): number;
   /** 关闭数据库。**幂等** —— 重复调用不抛错。 */
   close(): void;
   /**
@@ -92,8 +117,16 @@ declare class WorkspaceDatabase {
   dumpSchema(): string;
   getSetting(key: string): string | undefined;
   setSetting(key: string, value: string): void;
+  /**
+   * 登记一条授权根。
+   *
+   * @param options.requestId - 发起这次登记的那条 HTTP 请求的 id。
+   *   审计的用途不只是「记下发生了什么」，还要能回答「**哪一次请求**干的」；
+   *   不传（插件启动期登记内置根）时审计行的 `request_id` 为 null。
+   */
   addRoot(inputPath: string, label?: string, options?: {
     allowDuplicate?: boolean;
+    requestId?: string;
   }): Promise<StoredRoot>;
   listRoots(): StoredRoot[];
   getRoot(id: string): StoredRoot | undefined;
@@ -126,11 +159,27 @@ declare class WorkspaceDatabase {
    */
   ensureBuiltinRoot(realPath: string, label: string): Promise<StoredRoot | undefined>;
   removeRoot(id: string): void;
-  createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number): {
+  /**
+   * 生成一枚配对码。
+   *
+   * @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+   */
+  createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number, options?: {
+    requestId?: string;
+  }): {
     code: string;
     expiresAt: number;
   };
-  exchangePairing(code: string, deviceName: string): {
+  /**
+   * 用配对码换一枚设备令牌。
+   *
+   * 审计**在事务内**写（FUNC-5）：它是「这台设备被授权了」的唯一留痕，
+   * 与设备行同生共死。审计写不进去 → 整个兑换回滚 → 客户端重试，
+   * 而不是「拿到令牌但库里没有这笔授权的记录」。
+   */
+  exchangePairing(code: string, deviceName: string, options?: {
+    requestId?: string;
+  }): {
     token: string;
     device: DeviceView;
   };
@@ -139,7 +188,18 @@ declare class WorkspaceDatabase {
   private hydrateDevice;
   listDevices(): DeviceView[];
   isDeviceActive(id: string): boolean;
-  updateDevice(id: string, scopes: DeviceScope[], rootIds: string[]): DeviceView;
+  /**
+   * 改一台设备的 scope 与 root 授权。
+   *
+   * 审计**在事务内**写（FUNC-5）：它是「谁的权限被扩大了」的唯一留痕。
+   * 审计失败 → 整个更新回滚。宁可让用户重试，也不能出现「权限已经变宽、
+   * 但没有任何记录说是谁在什么时候改的」—— 那是不可审计的提权。
+   *
+   * @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+   */
+  updateDevice(id: string, scopes: DeviceScope[], rootIds: string[], options?: {
+    requestId?: string;
+  }): DeviceView;
   /**
    * 撤销设备 = **直接删除这一行**（用户要求：已撤销的不显示，并自动从数据库中删除）。
    *
@@ -153,7 +213,18 @@ declare class WorkspaceDatabase {
    * - `authenticate` 仍保留 `revoked_at IS NULL` 作为兜底，万一有别处留下的标记行，
    *   它们依然登不进来 —— 两层保险不冲突。
    */
-  revokeDevice(id: string): void;
+  /**
+   * 撤销一台设备 = 删除设备行。
+   *
+   * 审计与删除**在同一事务里**（FUNC-5），且顺序是「先留痕、再删除」：
+   * 审计的 `actor_id` 不带外键，删设备不会把记录带走。反过来若先删后写、
+   * 而写审计失败，就会留下「设备已经没了，但没有任何记录说谁撤的」。
+   *
+   * @param options.requestId - 发起这次请求的 HTTP requestId（审计可追溯）。
+   */
+  revokeDevice(id: string, options?: {
+    requestId?: string;
+  }): void;
   /**
    * 一次性清理历史遗留的「标记式」撤销设备（`revoked_at IS NOT NULL` 的行）。
    *
@@ -173,6 +244,34 @@ declare class WorkspaceDatabase {
    */
   markRevokedForTest(id: string): void;
   purgeRevokedDevices(): number;
+  /**
+   * 删掉早于 `cutoffMs` 的幂等回放记录，返回删除行数。
+   *
+   * 由 `retention.ts`（perf-reader）按调度调用，本方法只做 SQL —— 不判断策略、
+   * 不写日志，所以它可以被单独测试。
+   *
+   * 为什么用 `created_at` 而不是加一列 `expires_at`：24 小时的过期**完全**由
+   * `created_at` 推导得出，加列会让每次插入多写一个字段，还多一次 migration 风险。
+   */
+  pruneIdempotency(cutoffMs: number): number;
+  /**
+   * 清理审计：先按时间删，再兜「总数超过 `keepMax` 就删最旧的」。
+   *
+   * ## 为什么是两段而不是一段
+   *
+   * 只按时间删不够：桥可以被一个「短时间高频写入」的场景灌满审计表
+   * （例如每秒几十条 `chat.delta` 对应的写操作），时间窗内的量仍然能压垮库。
+   * 只按数量删也不够：用户可能希望「一年前的都清掉」，而不在乎条数。
+   *
+   * ## `keepMax` 是**下限保护**
+   *
+   * 即使 `cutoffMs` 设成了未来（把全部行都判成过期），也**至少**保留最近
+   * `keepMax` 条 —— 一句写错的调用不该把审计清空。审计被清空本身就等于
+   * 「抹掉证据」，这个方向必须由这一层挡住。
+   *
+   * 返回删除的行数（两段之和）。
+   */
+  pruneAudit(cutoffMs: number, keepMax: number): number;
   insertTrash(record: TrashRecord): void;
   updateTrashStatus(id: string, status: string): void;
   getTrash(id: string): TrashRecord | undefined;
@@ -399,7 +498,33 @@ declare class DshSettingsAdapter {
     api?: string;
     apiKey?: string;
   }): Promise<ProviderModelView[]>;
+  /**
+   * 取一个 provider 的上下文（目录条目 + 设置命名空间 + 当前 profile）。
+   *
+   * ## 为什么加一层「单请求内复用」
+   *
+   * 修复前 `updateProvider()` 会**连续**调它两次（一次在开头做校验、一次在
+   * `createProvider`/`removeProvider` 里），而每次 `providerContext` 都要打
+   * **两次**内核 RPC（`llm.providers` + `settings.describe`）。于是一次 PATCH
+   * 实际可能产生 4~5 次内核往返 —— 而它们问的是**同一份数据**。
+   *
+   * 这里用一个极短的 TTL（默认 1 秒，覆盖「同一请求内」的连续调用）缓存结果。
+   * 为什么不用「请求作用域」的显式传参：那要改每个方法的签名，而调用点散在
+   * router 与 adapter 两处 —— 收益远不抵这次改动。1 秒 TTL 的副作用是：
+   * 同一秒内两次改同一个 provider 时，第二次读到的是第一次之前的快照 ——
+   * 而 `settings.mutate` 有 `expectedRevision` 做真正的并发控制，所以不会写坏。
+   */
+  private readonly providerContextCache;
   private providerContext;
+  /**
+   * 写操作之后**必须**让缓存失效。
+   *
+   * 为什么不能只靠 TTL：`updateProvider` 改完 baseURL 之后，同一个请求尾部的
+   * `listProviders()` 要给出新值。靠 TTL 等 1 秒等于把一个「刚刚改成功」的
+   * 界面回滚成旧值 —— 那会被用户当成「改了没生效」。
+   */
+  private invalidateProviderContext;
+  private loadProviderContext;
 }
 //#endregion
 //#region src/host/dsh-0.2-bridge.d.ts
@@ -1422,6 +1547,31 @@ declare class DshChatAdapter {
   private readonly api;
   private readonly database;
   private readonly commandServices?;
+  /**
+   * 会话 → 可见性快照的短 TTL 缓存。
+   *
+   * ## 为什么需要（这是本文件最热的一处浪费）
+   *
+   * `requireSession()` 会在**几乎每个** API 调用里跑一遍 `listSessions()`，
+   * 而 `listSessions` 一次要打两次内核 RPC（`sessions.list` + `workspace.list`）
+   * 加一次 `database.listRoots()`。也就是说 history / commands / approvals /
+   * models / questions / prompt 每条请求都白花两次内核往返 —— 只为回答
+   * 「这个 session 能不能被这台设备看见」。
+   *
+   * ## 为什么 TTL 是 2 秒（短到近乎无感，长到足以省掉重复）
+   *
+   * 客户端在打开一个会话时会**连续**打四五个接口（历史、审批、提问、命令、模型），
+   * 2 秒足以把这一串并成一两次真实查询。再长就会让「刚建的会话看不到」
+   * 变成一个可感受到的延迟 —— 而那正是我们要避免的另一类 bug。
+   *
+   * ## 缓存的是什么（关键：缓存的是**授权结论**，不是会话内容）
+   *
+   * 只缓存「这个 sessionId 对当前设备可见吗」这一个布尔结论，且按 `principal.id`
+   * 分桶。**不缓存会话正文**：正文会被 `rename`/`archive`/新消息改掉，
+   * 缓存它等于制造陈旧数据；而可见性只随「根授权变没变」与「会话删没删」变，
+   * 两者都是低频且由用户操作驱动的。
+   */
+  private readonly sessionVisibility;
   private readonly sessionRootIds;
   private readonly sessionRootLookups;
   private readonly pendingApprovals;
@@ -1603,6 +1753,15 @@ declare class DshChatAdapter {
    */
   private commandAgent;
   private requireSession;
+  /**
+   * 记一条可见性结论，并顺手把过期条目清掉。
+   *
+   * 为什么在这里做清扫而不是定时器：缓存条目数与「设备数 × 会话数」同阶，
+   * 对单机部署来说是千级 —— 每次写入顺手扫一遍完全够，而且**没有定时器泄漏**。
+   * （本仓的纪律：服务端不引入 `setInterval`，见 `server.ts` 的心跳是唯一的例外，
+   * 且它 `unref` 过。）
+   */
+  private rememberVisibility;
   private requireWorkspace;
   private visibleWorkspaces;
   private requireAuthorizedRoot;
@@ -1621,16 +1780,65 @@ declare class FixedWindowLimiter {
 }
 //#endregion
 //#region src/host/auth.d.ts
+interface AuthServiceOptions {
+  /**
+   * 隧道运行状态探针（`CloudflaredTunnelManager.tunnelActive`）。
+   *
+   * 用函数而不是快照：隧道随时启停，鉴权发生在请求那一刻，读的必须是当下状态。
+   * 不注入（测试、未接隧道的构建）即为「没有隧道」，判据 0 恒不触发。
+   */
+  tunnelActive?: () => boolean;
+}
 declare class AuthService {
   private readonly database;
-  private readonly authFailures;
-  readonly pairingAttempts: FixedWindowLimiter;
-  readonly requests: FixedWindowLimiter;
-  constructor(database: WorkspaceDatabase);
+  private readonly options;
+  /**
+   * 两个「按对端分类」分开计的桶（键 = `<class>:<remoteAddress>`）。
+   *
+   * 阈值刻意**两边一致**：分桶的目的是「互不连坐」，不是「给本机开后门」。
+   * 如果本机侧更宽，那它就成了一条「怎么把自己伪装成本机」的动机 —— 而伪装是免费的
+   * （不发头即可），于是更宽的那一侧等于被取消。
+   * 阈值相等时，攻击者伪装成 local 只会消耗 local 配额，**没有额外收益**。
+   *
+   * `requests`：120/60s。`authFailures`：20/5min。
+   */
+  private readonly authFailuresByPeer;
+  /** 配对兑换：本机与隧道分开。隧道侧公网暴力尝试不该锁死本机的配对。 */
+  readonly pairingAttemptsByPeer: {
+    local: FixedWindowLimiter;
+    tunnelled: FixedWindowLimiter;
+  };
+  readonly requestsByPeer: {
+    local: FixedWindowLimiter;
+    tunnelled: FixedWindowLimiter;
+  };
+  constructor(database: WorkspaceDatabase, options?: AuthServiceOptions);
+  /** 这套服务当前的对端分类（`tunnelActive` 走 fail-closed 探针）。 */
+  private peerOf;
+  /** 按对端取请求配额桶。 */
+  requestLimiter(req: IncomingMessage): FixedWindowLimiter;
+  /** 按对端取认证失败桶。 */
+  failureLimiter(req: IncomingMessage): FixedWindowLimiter;
+  /** 按对端取配对尝试桶（`router.ts` 的 exchange 端点用）。 */
+  pairingLimiter(req: IncomingMessage): FixedWindowLimiter;
+  /**
+   * 隧道是否在跑。探针抛错时**按「在跑」处理**（fail closed）：探针读的是我们自己
+   * 对象上的 getter，它抛错意味着状态不可知；状态不可知时放行管理面正是这次修复要
+   * 消灭的那类决定。
+   */
+  private tunnelRunning;
   principal(req: IncomingMessage, options?: {
     allowAdmin?: boolean;
   }): Principal;
-  requireAdmin(req: IncomingMessage): Principal;
+  /**
+   * `/manage/**` 的守门人。
+   *
+   * @param options.allowTunnelMode - 只有「隧道状态下读/停隧道」这几个端点会传 true。
+   *   见 `adminRefusal` 的同名说明与 `router.ts` 的 `TUNNEL_MODE_EXEMPT_PATHS`。
+   */
+  requireAdmin(req: IncomingMessage, options?: {
+    allowTunnelMode?: boolean;
+  }): Principal;
   requireScope(principal: Principal, scope: DeviceScope): void;
   requireRoot(principal: Principal, rootId: string): void;
 }
@@ -1825,23 +2033,82 @@ interface TunnelPublicState {
   /** 对外地址，已统一为 `https://` 前缀原文，供配置文本直接使用。 */
   url: string | null;
   running: boolean;
+  /**
+   * 兜底的**英文短消息**（调试/日志用）。
+   *
+   * 2.5.2 起它**已脱敏**：不含完整 URL、不含绝对路径（见 `sanitizeDownloadError`）。
+   * 客户端应优先用 `errorKey` 本地化；这个字段只在没有键可用时兜底。
+   */
   error?: string;
+  /**
+   * 结构化错误键（客户端据此本地化）。渲染优先级 **errorKey > error**。
+   */
+  errorKey?: TunnelErrorKey;
+  /** `errorKey` 的插值参数。 */
+  errorParams?: Record<string, string | number>;
 }
 /** 「创建云隧道」进行中任务的阶段状态，供前端轮询显示进度。`percent=null` 表示该阶段无确定百分比（流动条）。 */
 interface TunnelActivity {
   /** 阶段标识：locating / downloading / unpacking / starting；`idle` 表示当前无进行中任务。 */
   stage: 'idle' | 'locating' | 'downloading' | 'unpacking' | 'starting';
-  /** 人类可读的阶段文案（如「已找到本机二进制，直接复用」）。 */
-  label: string;
+  /**
+   * 阶段文案的 **i18n 键**（不是给人看的句子）。
+   *
+   * 2.5.2 起取代原来的 `label: string`：服务端不再决定用哪种语言说这句话，
+   * 由客户端按自己的界面语言渲染。`''` 表示 idle（无进行中任务）。
+   *
+   * 键清单是**跨端契约**（见 `TunnelStageKeys`），改名会让 UI 显示原始键名。
+   * `''` = idle（没有进行中的任务，UI 不显示进度条）。
+   */
+  labelKey: TunnelStageKey | '';
+  /** 键里的插值参数（如下载进度的 `{ mb, all }`）。 */
+  labelParams?: Record<string, string | number>;
   /** 0-100 的进度百分比；null = 该阶段无法量化（前端显示流动条）。 */
   percent: number | null;
 }
+/**
+ * 隧道阶段文案的 i18n 键 —— **跨端契约，不得随意改名**。
+ *
+ * 客户端（`dsh-companion` / 桌面面板）按这套键查词典。改名 = UI 直接显示键名。
+ */
+type TunnelStageKey =
+/** 正在定位本机二进制。 */
+'tunnelStageLocating' |
+/** 已找到本机二进制，直接复用（不需要下载）。 */
+'tunnelStageBinaryFound' |
+/** 正在从官方 GitHub 下载。 */
+'tunnelStageDownloadGithub' |
+/** 正在从官方 deb 仓库下载。 */
+'tunnelStageDownloadDeb' |
+/** 下载中，带进度：`labelParams = { mb, all }`。 */
+'tunnelStageDownloadProgress' |
+/** 下载完成但**没有校验和可用**：内容未经验证（H5 的可见化）。 */
+'tunnelStageDownloadUnverified' |
+/** 正在解包 deb 并提取二进制。 */
+'tunnelStageUnpackDeb' |
+/** 正在写入二进制并赋执行权限。 */
+'tunnelStageWriteBinary' |
+/** 正在启动 cloudflared 隧道。 */
+'tunnelStageStarting';
+/**
+ * 隧道错误的结构化键。与 `error`（兜底英文短消息）并存：
+ * 客户端渲染优先级 **errorKey > error**。
+ */
+type TunnelErrorKey =
+/** cloudflared 进程退出且没拿到地址：`errorParams = { code, signal }`。 */
+'tunnelErrorExited' |
+/** 下载/解包失败（已脱敏，无参数）。 */
+'tunnelErrorDownload' |
+/** 已经在运行，拒绝重复启动。 */
+'tunnelErrorAlreadyRunning';
 /** 一次 cloudflared 子进程生命周期 + 对外状态机。 */
 declare class CloudflaredTunnelManager {
   private process;
   private url;
   private channel;
   private errorText;
+  private errorKey;
+  private errorParams;
   private listeners;
   private activity;
   /** 当前进行中任务的阶段进度（无任务时 stage 为 idle）。 */
@@ -1850,10 +2117,27 @@ declare class CloudflaredTunnelManager {
   reportActivity(a: TunnelActivity): void;
   /** 任务结束（成功或失败）时清空进行中进度。 */
   clearActivity(): void;
+  /**
+   * 是否有隧道在运行 —— 管理面鉴权的**判据 0**。
+   *
+   * 判据取自**进程持有状态**，不是请求头，所以它对「隧道把外部流量转进 127.0.0.1」
+   * 这条绕过路径 100% 可靠：不管转发进来的请求长什么样，只要隧道开着，管理面就关门。
+   * 见 `auth.ts` 的 `adminRefusal` 与 `PITFALLS.md` §隧道让回环判据失效。
+   *
+   * `running` 与 `publicState.running` 是同一个表达式（同一份真相），这里单独暴露是为了
+   * 让鉴权层不必构造一个含 url 的视图对象 —— 少一处把地址带进意外地方的机会。
+   */
+  get tunnelActive(): boolean;
   get publicState(): TunnelPublicState;
   /** 订阅状态变化；返回取消函数。 */
   onStatus(cb: () => void): () => void;
+  /** 取消一个状态订阅（onStatus 返回的函数与 waitForUrl 共用）。 */
+  private offStatus;
   private emit;
+  /**
+   * 记录一次错误。`error` 保留脱敏后的短消息（兜底/日志），
+   * `errorKey` + `errorParams` 供客户端本地化（优先级 errorKey > error）。
+   */
   private setError;
   /**
    * 启动一次 Quick Tunnel。
@@ -1861,6 +2145,18 @@ declare class CloudflaredTunnelManager {
    * @param port bridge 监听端口，cloudflared 把外网请求转发到 localhost:port
    */
   startQuick(exe: string, port: number): Promise<TunnelPublicState>;
+  /**
+   * 等待子进程把随机域名打印到 stdout（spawn 后 `url` 通常还要几秒才有）。
+   *
+   * 存在的理由（2.5.2）：`POST /manage/cloudflare/create` 发生在隧道**起来之前**，
+   * 此刻管理面还没被判据 0 关门；一旦在这次请求里等出地址并顺带出令牌配置文本，
+   * 客户端就不必在隧道运行后再打一次 `/manage/config/text`（那时必然 403，
+   * 这正是「一键开隧道+出令牌」失效的根因）。
+   *
+   * 任一条件满足即结算：地址出现 → resolve(url)；进程退出/超时 → resolve(null)
+   * （不抛，调用方据 null 决定要不要让客户端走轮询补一步）。调用方传 AbortSignal 可提前走人。
+   */
+  waitForUrl(timeoutMs?: number, signal?: AbortSignal): Promise<string | null>;
   /** 停止当前隧道。 */
   stop(): TunnelPublicState;
   /** 注入已抓到的地址 + 通道（命名隧道用）。 */
@@ -1985,6 +2281,35 @@ declare class ApiRouter {
   handle(req: IncomingMessage, res: ServerResponse, stripPrefix?: string): Promise<void>;
   private dispatch;
   private dispatchManagement;
+  /**
+   * 隧道状态视图。
+   *
+   * **这里不做脱敏，因为用不上**：判据 1 已经把 Cloudflare 边缘头（`Cf-Connecting-IP` /
+   * `Cf-Ray` / …）算作「前面有代理」的证据，于是任何真实隧道来源的请求在
+   * `requireAdmin` 就被 403 挡住了，根本到不了这个方法。能走到这里的只有真·本机请求
+   * （判据 1/2/3 全过），所以 `url` 可以照常给它 —— 那是桌面端「用隧道地址生成配置文本」
+   * 的依据。
+   *
+   * 为什么仍然保留这个方法而不是直接 `publicState`：脱敏的位置要留在一个**语义明确**的
+   * 出口上。将来若有人为了「让远程客户端也能读到隧道是否开着」而放宽判据 1，
+   * 必须在这里重新定义脱敏，而不是顺手把 `url` 一起放出去。
+   * 评估结论见报告：本轮选择「远程一律 403」而不是「远程读得到但 `url` 为 null」，
+   * 因为后者需要为状态端点在判据 1 上再开一个口子，而那正是这次修复要消灭的东西。
+   */
+  /**
+   * 生成一行可粘贴的 `DSH1:` 配置文本（POST /manage/config/text 与「一键开隧道并出令牌」
+   * 的 create 端点共用，避免两处各写一套配对/兑换/编码逻辑而漂移）。
+   *
+   * 入参字段与 /manage/config/text 的窄格式一致：
+   * - endpoints：显式给出则不再做本机网卡探测（隧道场景必须只塞隧道地址，不能混入 LAN）；
+   * - rootIds / scopes / deviceName / displayName / port：全部可选，缺省沿用原端点口径；
+   * - scopes 缺省是**五个非破坏性默认权限**（不含 files.delete / settings.write），
+   *   调用方若显式传 DEVICE_SCOPES 会放大手机权限，create 一键路径不传。
+   *
+   * 刻意不返回 pairing.expiresAt：那是配对码的十分钟有效期，设备令牌本身不过期。
+   */
+  private buildConfigText;
+  private tunnelStateFor;
   private dispatchEntries;
   private dispatchContent;
   private requireRoot;
@@ -2005,6 +2330,31 @@ interface RemoteApiServerOptions {
   chat: DshChatAdapter;
   events: WorkspaceEventBus;
   handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+  /**
+   * 同时允许的 WebSocket 连接数上限（默认 [DEFAULT_MAX_CONNECTIONS]）。
+   *
+   * 为什么必须有：`sockets` 此前是一个无界 Map —— 一个循环重连的客户端就能堆出任意多
+   * 连接，每条都参与广播、每条都查一次库。上限在**鉴权之后**才判定，所以它不会成为
+   * 未鉴权用户可探测的攻击面。
+   */
+  maxConnections?: number;
+  /** 单帧最大字节数（默认 1 MiB）。超限由 `ws` 直接 `close(1009)`。 */
+  maxPayloadBytes?: number;
+  /** 心跳间隔（默认 30 s）。测试传小值，不必干等半分钟。 */
+  heartbeatIntervalMs?: number;
+  /** 单连接事件队列上限（默认 512）。溢出按「丢可重建帧」策略处理。 */
+  socketQueueLimit?: number;
+  /** 发送缓冲高水位（默认 4 MiB）。连续两次越过就 `close(1013)`。 */
+  highWaterMarkBytes?: number;
+  /**
+   * 运行时能力开关，喂给 `connectionReadyData()`。
+   *
+   * 为什么在构造参数里而不是全局变量：能力位是**这台服务端此刻**能做什么，
+   * 同一进程里可能有多个实例（测试、重绑），用实例参数才不会被互相污染。
+   */
+  capabilities?: {
+    jobs?: boolean;
+  };
 }
 declare class RemoteApiServer implements RemoteControl {
   private readonly options;
@@ -2019,8 +2369,15 @@ declare class RemoteApiServer implements RemoteControl {
   private readonly webSockets;
   private readonly eventsAbort;
   private unsubscribeEvents;
-  private broadcastQueue;
+  /** 所有连接的 drain 完成信号；`Promise.all` 它们即可等排空。 */
+  private readonly pendingDrains;
+  private heartbeatTimer;
+  private changeTimer;
   private changing;
+  private readonly maxConnections;
+  private readonly socketQueueLimit;
+  private readonly highWaterMarkBytes;
+  private readonly heartbeatIntervalMs;
   constructor(options: RemoteApiServerOptions);
   start(): Promise<void>;
   stop(): Promise<void>;
@@ -2036,12 +2393,39 @@ declare class RemoteApiServer implements RemoteControl {
   disable(): RemoteOperationView;
   configure(host: string, port: number): RemoteOperationView;
   private scheduleChange;
+  /** 取消还没触发的监听变更。幂等：没定时器就什么都不做。 */
+  private clearChangeTimer;
   private performChange;
   private rebind;
   private bind;
   private createBoundServer;
+  /**
+   * 关掉当前监听与全部连接，**有界**。
+   *
+   * `server.close()` 的回调要等所有连接结束；而**升级过的 WebSocket 不在
+   * `closeAllConnections()` 的管理范围里**（HTTP 层已经不跟踪它了）。于是只要有一条
+   * 连接读不动（暂停读 / 半开），`close()` 就永远等不到回调 —— 插件卸载会挂死。
+   *
+   * 所以这里的顺序是：先礼后兵 —— 发 1012（客户端会看到「服务端重绑」而不是异常断开），
+   * 等一小段宽限期；宽限期到就 `terminate()`，同时让 `close()` 的等待一起收尾。
+   */
   private closeCurrent;
   private handleUpgrade;
+  /**
+   * 心跳循环：每 `heartbeatIntervalMs` 检查一次存活标记。
+   *
+   * 时序要看清：`isAlive` **先读后置假**，并且只在本轮「活着」时才补一次 `ping`。
+   * 于是：
+   * - 本轮活着 → 标记为可疑，再 ping 一次；
+   * - 本轮仍可疑（上一轮 ping 没换来 pong）→ `terminate()`。
+   *
+   * 结果是**连续错过两个周期**才踢人。偶发丢一个包不会误杀在线设备，真正断掉的
+   * （手机切网 / 熄屏后 NAT 表项过期）最多两个周期就清掉 —— 而修复前它只能等
+   * TCP 自己超时，等于「半开连接长期占着额度，还在每轮广播里被白查一次库」。
+   *
+   * `unref()` 必需：这个定时器永不结束，不 unref 会让进程退不掉。
+   */
+  private startHeartbeat;
   /**
    * 把待处理的**审批与提问**补推给刚建立的这条连接。
    *
@@ -2051,15 +2435,78 @@ declare class RemoteApiServer implements RemoteControl {
    * 重连窗口里产生的审批就会静默消失（内核阻塞着等决定、手机上却一片安静）。
    * 重放把「新连接一定能拿到仍待处理的审批」变成**服务端保证**，而不是客户端的义务。
    *
-   * 三个刻意的取舍：
+   * 四个刻意的取舍：
    * - **不 await**：重放要按会话做授权过滤（异步），握手不能为它排队；
    * - **只发这一条连接**：不走 `broadcast`，避免每次有人重连就骚扰所有在线设备；
    * - **失败静默**：重放是补救措施，它出错不该影响这条连接正常收事件。
-   *   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖。
+   *   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖；
+   * - **走连接自己的队列**：重放帧与随后的广播帧必须保序。直接 `socket.send`
+   *   会让「重放的第 2 帧」插到「广播的第 1 帧」前面去。
    */
   private replayPendingInteractions;
-  private broadcast;
+  /** 当前设备授权版本；`database` 还没提供就返回 undefined（退回逐事件查库的旧路径）。 */
+  private devicesRevisionOf;
+  /**
+   * 广播入口：**只做快照 + 入队**，全程同步。
+   *
+   * 这里是宿主事件循环上的热路径 —— 订阅回调里的任何 `await`（查库、查内核、
+   * 发网络）都会反过来把宿主的 `push` 拖住。修复前正是这样：一条全局 promise 链
+   * 串起「事件 × 连接」，一个慢判定让所有事件、所有客户端一起排队，`stop()`
+   * 还得 `await` 那条链。
+   */
+  private enqueueBroadcast;
+  /**
+   * 单连接入队：溢出时按「先丢可重建帧」处理，并给客户端一个 resync 信号。
+   *
+   * 为什么溢出不断连：手机端解码慢一次不该被踢下线（那会触发一条重连风暴，
+   * 而重连风暴又会把刚建好的连接再挤掉）。但「静默丢帧」更糟 —— 客户端会以为
+   * 事件流还连续，于是它手里的状态永远停在丢帧之前。所以丢的时候记一笔，
+   * 随后补发 `connection.resyncRequired`，把「静默」变成「告知」。
+   */
+  private enqueue;
+  /** 保证一条连接只有一个 drain 循环（否则同一连接内的顺序会被打乱）。 */
+  private startDrain;
+  /**
+   * 一条连接的发送循环。
+   *
+   * `await` 只发生在「这条连接自己的准备工作」上（刷新设备身份、判断会话授权）。
+   * 于是慢连接只慢它自己 —— 这正是与修复前的根本区别。
+   */
+  private drain;
+  /**
+   * 记录一次「越过发送高水位」，并安排复查。
+   *
+   * @returns 这条连接是否已经被关掉（调用方据此决定还要不要继续 drain）。
+   *
+   * 两拍才关是刻意的：一次越线可能只是客户端的短暂抖动（切网、GC），
+   * 立刻踢下线会制造重连风暴。但**必须有复查** —— 否则「第二拍」永远不会发生，
+   * 连接就卡在「不发也不关」的僵尸态，比直接断掉更难排查。
+   */
+  private noteHighWater;
+  private sendFrame;
+  /** 清掉这条连接自己的定时器。**必须**在连接被摘掉时调用，否则定时器会拖住进程。 */
+  private clearSocketTimers;
+  private closeBackpressured;
+  /**
+   * 按需刷新这条连接的身份快照。
+   *
+   * 有 `devicesRevision` 时：只有版本变了才查库 —— 正常情况**一件事都不做**，
+   * 而修复前是「每个事件、每条连接都查一次 `getActiveDevice`」。
+   * 没有该 getter 时退回旧行为（逐事件查库）：老数据库上功能不变，只是慢一点。
+   * 这比「广播路径依赖一个可能不存在的 API」安全得多，也让两侧改动可以分批落地。
+   *
+   * @returns 最新身份；设备已被撤销时返回 undefined。
+   */
+  private refreshPrincipal;
   private eventAllowed;
+  /**
+   * 等所有连接排空，**有上限**。
+   *
+   * `stop()` 不能无限等：一条读不动的 socket 会让插件卸载挂死，进而拖住进程退出。
+   * 超时后照样会断开它们（`closeCurrent` 负责），只是不再尝试把队列里的东西送出去 ——
+   * 卸载路径上「送达」本来就不是目标。
+   */
+  private drainAll;
   private trimOperations;
 }
 /** 一条挂在 DSH webserver 上的插件自有路由。 */