dsh-remote-bridge 2.5.2 → 2.6.0

package/lib/index.d.ts

@@ -242,7 +242,39 @@ declare class WorkspaceDatabase {
    * 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
    * 并起一个自见其明的名字，免得有人把它当成正常 API。
    */
+  /**
+   * 仅供测试：把某台设备的「最后使用时间/创建时间」拨到过去。
+   *
+   * 生产路径没法造出「30 天没动过」的设备（认证一次就刷新 `last_seen_at`），而
+   * `pruneInactiveDevices` 的核心语义恰恰只在这种时间跨度上才看得见。与
+   * `markRevokedForTest` 同样的理由：显式开一个自见其明的测试入口，别让人误当 API。
+   */
+  backdateDeviceForTest(id: string, options: {
+    lastSeenAt?: number;
+    createdAt?: number;
+  }): void;
   markRevokedForTest(id: string): void;
+  /**
+   * 按「最后使用时间」批量清掉长期没动过的设备。
+   *
+   * 「最后使用」取 `last_seen_at`（每次令牌认证成功都会刷新），从没认证过的设备退回
+   * `created_at` —— 否则一条配好就再没开过的设备会永远躲过清理，而那恰恰是用户最想
+   * 一键清掉的那类（换手机、临时配对、旧测试探针）。
+   *
+   * 与 `purgeRevokedDevices` 的区别：后者清的是历史遗留的「标记式撤销」脏行，这里清的是
+   * **仍然有效、但已经不用了**的设备 —— 用户的原话是「一键清理多少天未使用设备」。
+   *
+   * 语义边界（故意这么定）：
+   * - 只删设备行 + 级联的 `device_roots`，不碰审计（审计的 `actor_id` 不是外键）；
+   * - **不删本机正在用的那台**（`keepDeviceId`）：调用方就是它，删掉自己会让当前
+   *   客户端立刻 401，看起来像「点一下清理把手机踢下线了」；
+   * - 天数被夹在 1..3650，避免 `0` 或负数变成「清空所有设备」；
+   * - 返回真正删掉的条数，0 也是一次合法结果。
+   */
+  pruneInactiveDevices(olderThanDays: number, options?: {
+    keepDeviceId?: string;
+    requestId?: string;
+  }): number;
   purgeRevokedDevices(): number;
   /**
    * 删掉早于 `cutoffMs` 的幂等回放记录，返回删除行数。
@@ -303,15 +335,56 @@ declare class WorkspaceDatabase {
   private hasRootColumn;
 }
 //#endregion
-//#region src/host/settings-adapter.d.ts
+//#region src/host/settings-namespace.d.ts
+/**
+ * 内核 `settings.describe()` 的命名空间视图（DSH 0.2.x）。
+ *
+ * 字段比 2.6.0 之前多：`autoGenerate` / `applies` / `secrets` 都原样透出，
+ * 手机端要靠 `secrets[].path` 判断「哪些字段是密钥位、只读」，比按键名猜可靠。
+ */
 interface SettingsNamespaceView {
   ns: string;
+  autoGenerate?: unknown;
   schema?: unknown;
   value: unknown;
   base?: unknown;
   user?: unknown;
+  applies?: unknown;
+  secrets?: SettingsNamespaceSecret[];
   revision: number;
 }
+/** 一个密钥位的路径与「是否已设置」；**只有路径，没有值**。 */
+interface SettingsNamespaceSecret {
+  path: string[];
+  set: boolean;
+}
+type SettingsNamespaceReason = 'HOST_READONLY' | 'HIGH_RISK_NAMESPACE';
+/** 手机端看到的单个命名空间：内核视图 + 能不能写 + 为什么不能写。 */
+interface SettingsNamespaceEntry {
+  ns: string;
+  revision: number;
+  schema?: unknown;
+  value: unknown;
+  base?: unknown;
+  user?: unknown;
+  autoGenerate?: unknown;
+  applies?: unknown;
+  secrets?: SettingsNamespaceSecret[];
+  writable: boolean;
+  reason?: SettingsNamespaceReason;
+}
+/**
+ * `GET /api/v1/settings/namespaces` 的响应。
+ *
+ * 刻意**不**透出内核的 `hasDocument`：它对手机端没有决策价值，而响应多一个字段
+ * 就等于契约多一个字段（另一侧已按 `{writable, namespaces}` 定稿）。
+ */
+interface SettingsNamespacesView {
+  writable: boolean;
+  namespaces: SettingsNamespaceEntry[];
+}
+//#endregion
+//#region src/host/settings-adapter.d.ts
 interface ConfigurableProvider {
   provider: string;
   displayName: string;
@@ -476,7 +549,31 @@ interface CustomProviderCapability {
 }
 declare class DshSettingsAdapter {
   private readonly api;
-  constructor(api: SettingsApiProxy);
+  private readonly options;
+  /**
+   * @param options.writeNamespaces 额外允许手机端写入的设置命名空间（精确 ns 或
+   *   `前缀*`），与内置策略（`ui-*` / 以 `locale` 结尾）叠加；默认为空。
+   */
+  constructor(api: SettingsApiProxy, options?: {
+    writeNamespaces?: readonly string[];
+  });
+  /**
+   * 列出全部设置命名空间（通用设置面的读侧）。
+   *
+   * 与 `listProviders()` 的区别：它不理解任何 provider 语义，原样透出内核按插件
+   * 划分的命名空间，由手机端按 `schema` 自己长表单 —— 新装插件不必等 App 发版。
+   */
+  describeNamespaces(): Promise<SettingsNamespacesView>;
+  /**
+   * 按路径改一个命名空间（通用设置面的写侧）。
+   *
+   * 校验顺序是刻意的：ns 策略 → ops 结构 → 内核 describe（host 可写性）→ mutate。
+   * 先验策略既省一次内核往返，也保证「高危命名空间」无论 ops 怎么错都先得到 403。
+   */
+  mutateNamespace(ns: string, ops: unknown, expectedRevision?: number): Promise<SettingsNamespaceEntry>;
+  private get writeNamespaces();
+  /** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
+  private settingsService;
   listProviders(): Promise<{
     writable: boolean;
     revisionByNamespace: Record<string, number>;
@@ -2281,6 +2378,37 @@ declare class ApiRouter {
   handle(req: IncomingMessage, res: ServerResponse, stripPrefix?: string): Promise<void>;
   private dispatch;
   private dispatchManagement;
+  /**
+   * 打开隧道并（可选）顺带产出配置文本 —— HTTP `POST /manage/cloudflare/create` 与
+   * IM `/tunnel` 命令**共用**这一条实现。
+   *
+   * 抽出来的原因：两条入口的前半段完全一致（确保 cloudflared → startQuick → 等随机域名 →
+   * 建配置文本），差别只在「谁在调用」——HTTP 侧要先把请求体读干净（流会随时间关闭），
+   * 命令侧没有请求体。复制一份会让「一键出令牌」在两条路径上慢慢漂移。
+   *
+   * @param createBody - 已解析的请求体（HTTP 侧）或 `{ configText: true }`（命令侧）。
+   * @param requestId - 审计与配对记录共用的请求 ID。
+   * @param actorLabel - 审计里的操作者标签：`loopback-admin`（本机管理面）或 `im-command`。
+   * @returns 合并了「等到地址」的 state，以及（wantConfig 且拿到地址时）配置文本。
+   */
+  private createTunnel;
+  /**
+   * IM `/tunnel` 命令的宿主侧入口：开隧道并返回一行可粘贴的配置文本。
+   *
+   * 与 HTTP 路径的两点差别：
+   *
+   * 1. **隧道已在运行时直接复用当前地址**，不重复 spawn（第二次 `startQuick` 会撞
+   *    `TUNNEL_ALREADY_RUNNING`，而用户在 IM 里连发两条是很常见的）。
+   * 2. 配置文本的 endpoint 只用隧道地址，设备名缺省由 `buildConfigText` 决定 —— 命令
+   *    不接受参数，所以没有 `endpointLabel` / `rootIds` 的透传面。
+   *
+   * @throws 当 12 秒内没拿到公网地址，或 cloudflared 下载失败时。
+   */
+  openTunnelForCommand(): Promise<{
+    url: string;
+    text: string;
+    deviceName: string;
+  }>;
   /**
    * 隧道状态视图。
    *
@@ -2560,6 +2688,14 @@ interface Config {
   port?: number;
   remoteHost?: string;
   maxUploadBytes?: number;
+  /**
+   * 额外允许手机端写入的设置命名空间（默认空）。
+   *
+   * 精确 ns（`ui-chat`）或通配前缀（`llm-*`）。与内置策略叠加：`ui-*` 与以
+   * `locale` 结尾的命名空间本来就可写；其余默认只读，因为改模型/权限等于把
+   * 遥控器交出去（理由见 docs/project/SECURITY.md）。
+   */
+  settingsWriteNamespaces?: readonly string[];
 }
 interface HostContext extends Dsh02HostServices {
   webServer: Parameters<typeof attachEmbeddedRoutes>[0];