dsh-remote-bridge 2.6.0 → 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;
   /**
@@ -333,6 +393,9 @@ declare class WorkspaceDatabase {
   private dropRootsUniqueConstraint;
   /** `roots` 表是否已有指定列。 */
   private hasRootColumn;
+  /** `devices` 表是否已有指定列。 */
+  private hasDeviceColumn;
+  private hasColumn;
 }
 //#endregion
 //#region src/host/settings-namespace.d.ts
@@ -553,9 +616,13 @@ declare class DshSettingsAdapter {
   /**
    * @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[];
   });
   /**
    * 列出全部设置命名空间（通用设置面的读侧）。
@@ -572,6 +639,8 @@ declare class DshSettingsAdapter {
    */
   mutateNamespace(ns: string, ops: unknown, expectedRevision?: number): Promise<SettingsNamespaceEntry>;
   private get writeNamespaces();
+  /** 交给地址策略的选项；集中一处，三个入口不会各配各的。 */
+  private get baseURLOptions();
   /** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
   private settingsService;
   listProviders(): Promise<{
@@ -587,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）。
    *
@@ -622,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
@@ -1927,6 +2027,14 @@ declare class AuthService {
   principal(req: IncomingMessage, options?: {
     allowAdmin?: boolean;
   }): Principal;
+  /**
+   * 把本次请求探测到的身份记进库，并（在允许时）更新设备显示名。
+   *
+   * 吞掉一切异常的理由见调用点注释：设备名是显示信息，不该成为连接的前置条件。
+   *
+   * @returns 改名成功时的新名字；没改名（或探测不到）时 `undefined`。
+   */
+  private recordIdentity;
   /**
    * `/manage/**` 的守门人。
    *
@@ -2696,6 +2804,18 @@ interface Config {
    * 遥控器交出去（理由见 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];