dsh-remote-bridge 2.5.2 → 2.6.1

package/lib/index.d.ts

@@ -26,6 +26,24 @@ interface DeviceView {
   createdAt: number;
   lastSeenAt?: number;
   revokedAt?: number;
+  /**
+   * 设备自称/被推断出的平台与型号（`android` / `harmonyos` / …）。
+   *
+   * **可选**：老设备从未上报过就是 `undefined`，客户端必须能接受缺省。
+   * 这两个字段只用于界面显示与排查，**不参与任何授权判断** —— 它们是客户端
+   * 自称的，不是可信身份。
+   */
+  platform?: string;
+  model?: string;
+  /**
+   * `name` 是怎么来的，决定后续能不能自动改名。
+   *
+   * - `default`：配对时的占位名（`'Android 设备'` 之类）。设备第一次带身份
+   *   连上来时**允许**被自动改成「平台 · 型号」。
+   * - `detected`：由探测到的身份自动生成。后续身份变了仍可再自动更新。
+   * - `declared`：用户手工改的。**永不再自动覆盖** —— 用户起的名比机器猜的准。
+   */
+  nameSource?: 'default' | 'detected' | 'declared';
 }
 interface FileEntryView {
   name: string;
@@ -179,6 +197,7 @@ declare class WorkspaceDatabase {
    */
   exchangePairing(code: string, deviceName: string, options?: {
     requestId?: string;
+    nameSource?: 'default' | 'declared';
   }): {
     token: string;
     device: DeviceView;
@@ -186,6 +205,47 @@ declare class WorkspaceDatabase {
   authenticate(token: string): AuthenticatedDevice | undefined;
   getActiveDevice(id: string): AuthenticatedDevice | undefined;
   private hydrateDevice;
+  /**
+   * 记录一次探测到的设备身份，必要时顺手把占位名改成「平台 · 型号」。
+   *
+   * 时序说明：配对时桥只知道「有个设备要连」，真正的平台与型号要等设备
+   * **第一次发请求**才拿得到。所以这个方法由认证路径调用（见 `auth.ts`
+   * 的 `principal`），而不是配对路径。
+   *
+   * ## 什么时候改名
+   *
+   * 只有 `name_source` 是 `default`（配对时的占位名）或 `detected`（上次自动
+   * 生成的）才改名。`declared`（用户手工改的）**永不动** —— 用户起的名比机器
+   * 猜的准，而且他能改一次就能改第二次，但机器每次连接都覆盖就再也留不住了。
+   *
+   * 老库的 `name_source` 是 NULL：那些行里的名字多半是硬编码的「Android 设备」，
+   * 但**也可能是用户手工改过的**（此前没有任何改名通道，所以实际上只有占位名；
+   * 不过万一有人直接改过库，我们不能替他决定）。保守起见把 NULL 当作
+   * `declared` 处理 —— 名字不动，只补 platform/model 两列。
+   *
+   * ## 为什么不做成「每次请求都写库」
+   *
+   * 调用方只在**探测结果与库里不同**时才调这里（见 `auth.ts`），所以正常情况
+   * 下一台设备一生只写一次。这不是性能考虑，而是避免把一次读请求变成写请求：
+   * 写请求会碰 WAL、会影响 `devicesRevisionCounter`，进而触发全体客户端重拉设备表。
+   *
+   * @returns 是否真的改了库（调用方据此决定要不要递增设备版本号）。
+   */
+  recordDeviceIdentity(id: string, identity: {
+    platform?: string;
+    model?: string;
+    suggestedName?: string;
+  }): boolean;
+  /**
+   * 用户手工改名。
+   *
+   * 一旦走这条路，`name_source` 就变成 `declared`，此后任何自动探测都**不再**
+   * 覆盖它。这是「用户意图优先于机器推断」的唯一实现点，所以单独一个方法而不是
+   * 塞进 `updateDevice`：权限变更与改名是两件不同的事，审计动作也不该混。
+   */
+  renameDevice(id: string, name: string, options?: {
+    requestId?: string;
+  }): DeviceView;
   listDevices(): DeviceView[];
   isDeviceActive(id: string): boolean;
   /**
@@ -242,7 +302,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` 的幂等回放记录，返回删除行数。
@@ -301,17 +393,61 @@ declare class WorkspaceDatabase {
   private dropRootsUniqueConstraint;
   /** `roots` 表是否已有指定列。 */
   private hasRootColumn;
+  /** `devices` 表是否已有指定列。 */
+  private hasDeviceColumn;
+  private hasColumn;
 }
 //#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 +612,37 @@ interface CustomProviderCapability {
 }
 declare class DshSettingsAdapter {
   private readonly api;
-  constructor(api: SettingsApiProxy);
+  private readonly options;
+  /**
+   * @param options.writeNamespaces 额外允许手机端写入的设置命名空间（精确 ns 或
+   *   `前缀*`），与内置策略（`ui-*` / 以 `locale` 结尾）叠加；默认为空。
+   * @param options.allowPrivateProviderHosts 允许供应商 `baseURL` 指向的私网 / 回环
+   *   host 白名单（默认空 = 一律拒绝）。要连本地 LLM 的部署方显式填，理由见
+   *   `provider-url-policy.ts` 文件头。
+   */
+  constructor(api: SettingsApiProxy, options?: {
+    writeNamespaces?: readonly string[];
+    allowPrivateProviderHosts?: 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();
+  /** 交给地址策略的选项；集中一处，三个入口不会各配各的。 */
+  private get baseURLOptions();
+  /** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
+  private settingsService;
   listProviders(): Promise<{
     writable: boolean;
     revisionByNamespace: Record<string, number>;
@@ -490,14 +656,38 @@ declare class DshSettingsAdapter {
       message: string;
     }[];
   }>;
-  updateProvider(providerId: string, patch: ProviderPatch): Promise<void>;
-  createProvider(input: CustomProviderCreate): Promise<void>;
+  /**
+   * 更新供应商配置。
+   *
+   * 返回 `baseURLHost`（仅当本次 patch 动了 `baseURL` 时存在）供路由层写审计：
+   * 攻击者可以用 discover 把凭据发到任意地址，事后必须能从审计里看出「打了哪」。
+   * 只记 host 不记完整 URL —— path/query 可能带凭据，审计表不该成为新的泄露点。
+   */
+  updateProvider(providerId: string, patch: ProviderPatch): Promise<{
+    baseURLHost?: string;
+  }>;
+  createProvider(input: CustomProviderCreate): Promise<{
+    baseURLHost: string;
+  }>;
   removeProvider(providerId: string, expectedRevision?: number): Promise<void>;
+  /**
+   * 发现供应商可用模型。
+   *
+   * `draft.baseURL` 是**临时覆盖**（不写配置），但内核会带着该供应商已配置的真实
+   * 凭据去请求它 —— 这正是 SEC-H11 的窃取路径：攻击者把自己的服务器填进来即可收到
+   * `Authorization: Bearer <真实 key>`。因此临时覆盖与持久化写入过同一道地址策略。
+   *
+   * 返回 `baseURLHost` 供路由层审计；不传 `baseURL` 时（用配置里的地址）同样返回，
+   * 这样「打了哪个地址」在任何情况下都能追溯。
+   */
   discover(providerId: string, draft: {
     baseURL?: string;
     api?: string;
     apiKey?: string;
-  }): Promise<ProviderModelView[]>;
+  }): Promise<{
+    models: ProviderModelView[];
+    baseURLHost?: string;
+  }>;
   /**
    * 取一个 provider 的上下文（目录条目 + 设置命名空间 + 当前 profile）。
    *
@@ -525,6 +715,13 @@ declare class DshSettingsAdapter {
    */
   private invalidateProviderContext;
   private loadProviderContext;
+  /**
+   * 该供应商当前是否已经存了凭据。
+   *
+   * 单独一次 `credentials.describe` 只在「要换 baseURL host」时才调 —— 那是罕见路径，
+   * 而正常保存（改 models / 显示名 / 协议）不该为此多付一次内核往返。
+   */
+  private providerHoldsCredential;
 }
 //#endregion
 //#region src/host/dsh-0.2-bridge.d.ts
@@ -1830,6 +2027,14 @@ declare class AuthService {
   principal(req: IncomingMessage, options?: {
     allowAdmin?: boolean;
   }): Principal;
+  /**
+   * 把本次请求探测到的身份记进库，并（在允许时）更新设备显示名。
+   *
+   * 吞掉一切异常的理由见调用点注释：设备名是显示信息，不该成为连接的前置条件。
+   *
+   * @returns 改名成功时的新名字；没改名（或探测不到）时 `undefined`。
+   */
+  private recordIdentity;
   /**
    * `/manage/**` 的守门人。
    *
@@ -2281,6 +2486,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 +2796,26 @@ interface Config {
   port?: number;
   remoteHost?: string;
   maxUploadBytes?: number;
+  /**
+   * 额外允许手机端写入的设置命名空间（默认空）。
+   *
+   * 精确 ns（`ui-chat`）或通配前缀（`llm-*`）。与内置策略叠加：`ui-*` 与以
+   * `locale` 结尾的命名空间本来就可写；其余默认只读，因为改模型/权限等于把
+   * 遥控器交出去（理由见 docs/project/SECURITY.md）。
+   */
+  settingsWriteNamespaces?: readonly string[];
+  /**
+   * 允许供应商 `baseURL` 指向的私网 / 回环 host 白名单（默认空 = 一律拒绝）。
+   *
+   * 默认拒绝的理由：手机端改 `baseURL` 就等于把模型请求（含 `Authorization:
+   * Bearer <真实 key>`）引到任意地址，这是 SEC-H11 的窃取路径。默认拒绝把
+   * 「谁能连内网」变成部署方的显式决定。
+   *
+   * 要连本地 LLM（ollama / LM Studio 之类）时填这里，推荐带端口：
+   * `["127.0.0.1:11434", "localhost:1234"]`。带端口的条目只放行该端口，裸
+   * host 条目放行该主机的任意端口（面更大）。规则见 `src/host/provider-url-policy.ts`。
+   */
+  allowPrivateProviderHosts?: readonly string[];
 }
 interface HostContext extends Dsh02HostServices {
   webServer: Parameters<typeof attachEmbeddedRoutes>[0];