dsh-remote-bridge 2.2.4 → 2.3.0

package/lib/index.d.ts

@@ -6,6 +6,17 @@ interface RootView {
   id: string;
   label: string;
   createdAt: number;
+  /**
+   * 这是不是插件自动登记的「DSH 工作区」根。
+   *
+   * 用户要求：默认把当前 DSH 的工作目录作为一个授权根显示出来，**不可删除**，
+   * 但可以正常访问（手机端照常浏览）。标记只影响**删除**这一件事 ——
+   * 它在数据库里就是一条普通的根，`files.*` 授权、配对、写盘全走同一套。
+   *
+   * 不写成 `readonly`，是为了让 REST 契约保持「服务端给什么就是什么」：
+   * 老客户端不认识这个字段会忽略它，行为不变。
+   */
+  builtin?: boolean;
 }
 interface DeviceView {
   id: string;
@@ -69,11 +80,49 @@ declare class WorkspaceDatabase {
   private readonly db;
   constructor(dataDir: string);
   close(): void;
+  /**
+   * 导出 `roots` 的建表语句（只读，诊断与迁移测试用）。
+   *
+   * 存在的理由：迁移要判断「UNIQUE 还在不在」，单看 `PRAGMA table_info` 看不出来 ——
+   * 表结构读出来一模一样，区别在约束上。这个方法让「重建真的发生了」可以被断言，
+   * 而不是靠迁移没报错来推测。
+   */
+  dumpSchema(): string;
   getSetting(key: string): string | undefined;
   setSetting(key: string, value: string): void;
-  addRoot(inputPath: string, label?: string): Promise<StoredRoot>;
+  addRoot(inputPath: string, label?: string, options?: {
+    allowDuplicate?: boolean;
+  }): Promise<StoredRoot>;
   listRoots(): StoredRoot[];
   getRoot(id: string): StoredRoot | undefined;
+  /**
+   * 登记「DSH 工作区」根 —— **幂等**。
+   *
+   * 用户要求：当前 DSH 的工作目录要显示成一个授权根，**不可删除、但可以正常访问**。
+   * 它不是另起一张表，而是**一条普通的根**加一个 `builtin` 标记：配对、`files.*`
+   * 授权、回收站、写盘全走现成逻辑，少一套需要同步维护的规则。
+   *
+   * ## 同目录已有一条普通根时，另起一条而不是复用它
+   *
+   * 这是实测踩到的现实情况：用户早于这个功能**自己**加过同一条目录（本机那条是
+   * 10-08 手工加的），路径和 DSH 工作区一模一样。
+   *
+   * 初版在这里「尊重用户选择」直接返回，结果就是**内置项永远登记不上** —— 因为它
+   * 每次都撞上那条已有的普通根然后什么都不做。界面上那个「不可删除」也就永远出不来。
+   * 用户的选择和功能的正确性在这里是冲突的：用户要的是「这条要不可删」，不是
+   * 「这条不能变」。
+   *
+   * 所以改成**另起一条**：用户原来那条保持可删（那是他的目录，他有权删），内置那条
+   * 独立存在。代价是列表里同一个路径出现两行 —— 这是「两条记录、两种权限」的必然
+   * 结果，比让功能失效或擅自改他的配置都更可接受。
+   *
+   * 幂等不再靠 UNIQUE（它已经被去掉了），而是靠「已存在 `builtin = 1` 的同路径就
+   * 直接返回」。插件**每次启动都可以无脑调一次**。
+   *
+   * 只有传入路径确实存在才登记：工作区可能被用户删掉，这时留一条指向虚空的授权根，
+   * 手机浏览时会一路报错，比不显示更糟。
+   */
+  ensureBuiltinRoot(realPath: string, label: string): Promise<StoredRoot | undefined>;
   removeRoot(id: string): void;
   createPairing(rootIds: string[], scopes: DeviceScope[], ttlMs?: number): {
     code: string;
@@ -89,7 +138,39 @@ declare class WorkspaceDatabase {
   listDevices(): DeviceView[];
   isDeviceActive(id: string): boolean;
   updateDevice(id: string, scopes: DeviceScope[], rootIds: string[]): DeviceView;
+  /**
+   * 撤销设备 = **直接删除这一行**（用户要求：已撤销的不显示，并自动从数据库中删除）。
+   *
+   * 原先是打 `revoked_at` 标记保留行，两处都不好：
+   * - 界面上会出现一长串灰掉的「已撤销」，本机实测堆到了 32 条，全是历史测试与旧设备；
+   * - 行留着就等于凭据的哈希还在库里，是个长期负担 —— 令牌已经没用了，留着没有意义。
+   *
+   * 删除是安全的，因为：
+   * - `device_roots` 是 `ON DELETE CASCADE`，授权行自动清掉；
+   * - `audit.actor_id` 是**普通字符串不是外键**，审计留痕（谁在什么时候撤了谁）一条不少；
+   * - `authenticate` 仍保留 `revoked_at IS NULL` 作为兜底，万一有别处留下的标记行，
+   *   它们依然登不进来 —— 两层保险不冲突。
+   */
   revokeDevice(id: string): void;
+  /**
+   * 一次性清理历史遗留的「标记式」撤销设备（`revoked_at IS NOT NULL` 的行）。
+   *
+   * 撤销改成直接删除之前，每次撤销都只是打个标记，于是库越用越臃肿 —— 本机实测堆到
+   * **32 条**，全是历史测试探针和早已弃用的旧手机，界面上就是一长串灰字。
+   *
+   * 幂等：没有这种行时返回 0，不报错。插件每次启动调一次即可。
+   * 走 `revokeDevice` 的删除语义，但**不能**借它写 `device.revoke` 审计 ——
+   * 那会把「系统清理」记成管理员逐个撤销，审计会失真。清理本身只写一条汇总。
+   */
+  /**
+   * 仅供测试：造一行「撤销改成删除之前」的标记式撤销数据。
+   *
+   * 真实场景来自历史库（每次撤销只打 `revoked_at` 标记，于是越积越多）。测试需要个
+   * 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
+   * 并起一个自见其明的名字，免得有人把它当成正常 API。
+   */
+  markRevokedForTest(id: string): void;
+  purgeRevokedDevices(): number;
   insertTrash(record: TrashRecord): void;
   updateTrashStatus(id: string, status: string): void;
   getTrash(id: string): TrashRecord | undefined;
@@ -103,6 +184,22 @@ declare class WorkspaceDatabase {
   } | undefined;
   saveIdempotent(deviceId: string, key: string, status: number, body: unknown): void;
   private migrate;
+  /** `roots.real_path` 上是否还带 UNIQUE 约束。 */
+  private rootsPathIsUnique;
+  /**
+   * 重建 `roots` 去掉 UNIQUE。
+   *
+   * 这是一次**有真实数据风险**的操作，所以每一步都写清楚理由：
+   * - `PRAGMA foreign_keys=OFF`：`device_roots.root_id` 引用 `roots(id)`，而重建要
+   *   DROP 掉被引用的那张表。开着外键会直接失败。
+   * - 事务：`new_roots` 建好、数据搬完、**最后**才 DROP 老表并改名。中途失败会整体
+   *   回滚，原表原封不动。
+   * - 搬数据用显式列名而不是 `SELECT *`：老表可能还没有 `builtin` 列（两种迁移顺序
+   *   都可能出现），按列名搬才不会在某一台机器上错位。
+   */
+  private dropRootsUniqueConstraint;
+  /** `roots` 表是否已有指定列。 */
+  private hasRootColumn;
 }
 //#endregion
 //#region src/host/settings-adapter.d.ts
@@ -1348,6 +1445,13 @@ interface RouterOptions {
   settings: DshSettingsAdapter;
   remote: RemoteControl;
   maxUploadBytes: number;
+  /**
+   * 解析不出会话工作目录时的图片兜底目录（设置面板里只读展示）。
+   *
+   * 可选：默认按 `database.dataDir` 推出来，测试因此不必每条都补一个字段。
+   * 生产路径由 `index.ts` 传入与交接实际使用**同一个**目录，避免「界面显示 A、落盘在 B」。
+   */
+  imageFallbackDir?: string;
 }
 declare class ApiRouter {
   private readonly options;
@@ -1359,6 +1463,8 @@ declare class ApiRouter {
   private dispatchContent;
   private requireRoot;
   private authorizedRoots;
+  /** 兜底交接目录：没配就用状态目录下的 `image-handoff`（与 `index.ts` 的默认一致）。 */
+  private imageFallbackDir;
   private audit;
   private readIdempotent;
   private saveIdempotent;
@@ -1414,13 +1520,19 @@ declare class RemoteApiServer implements RemoteControl {
   private eventAllowed;
   private trimOperations;
 }
+/** 一条挂在 DSH webserver 上的插件自有路由。 */
+interface EmbeddedRoute {
+  kind: 'exact' | 'prefix';
+  path: string;
+  handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
 declare function attachEmbeddedRoutes(webServer: {
   register(route: {
     kind: 'exact' | 'prefix';
     path: string;
     handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
   }): () => void;
-}, router: ApiRouter, remote: RemoteApiServer): () => void;
+}, router: ApiRouter, remote: RemoteApiServer, extraRoutes?: readonly EmbeddedRoute[]): () => void;
 //#endregion
 //#region src/index.d.ts
 /**