dsh-server-connector 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # 更新日志
 
+## 0.2.1 — 2026-11-06
+
+### 修复（严重：导致 DSH 无法启动）
+
+- **密码凭证引用格式非法，会让整个 DSH 启动失败**。此前密码认证生成
+  `server-connector:<id>:password`，其中含冒号与连字符，而
+  `@deepseek-ai/dsh-credentials` 要求所有凭证引用匹配 `/^[A-Za-z_][A-Za-z0-9_]*$/`。
+  这条非法引用一旦写入 `servers.json`，下次启动时 `credentials` 插件解析失败；
+  由于它是必需插件，整个 Host 起不来——**而且禁用本插件也没用，因为坏值已经在磁盘上**。
+
+  三处修复，缺一不可：
+  - 改为生成 `DSH_SERVER_CONNECTOR_<ID>_PASSWORD`，并校验调用方传入的引用，
+    使本插件再也无法写入非法值；
+  - 加载时迁移**旧格式**，让已经落盘的记录继续可用，而不是把「Host 崩溃」换成
+    「插件加载失败」；
+  - 迁移后**回写文件**，否则之后复制的文件副本仍带着非法值。已经合法的文件不会被重写。
+
+  只迁移本插件曾经写出的那一种格式；其他非法引用仍然拒绝，因为静默改写可能让记录
+  指向另一个密钥。
+
+- 同时修正 README 与设计文档中展示的引用格式（它们此前在教读者写出非法值）。
+
+### 升级说明
+
+升级到 0.2.1 后**无需手动改文件**：插件加载时会自动把旧引用迁移成合法值并回写。
+
+若 DSH 当前因该问题无法启动，先做下面任一操作再启动：
+
+- 编辑 `~/.dsh/server-connector/servers.json`，把
+  `"server-connector:srv-01:password"` 改成 `"DSH_SERVER_CONNECTOR_SRV_01_PASSWORD"`
+  （`srv-02` 同理）；或
+- 直接删除该文件中 `auth.kind` 为 `password` 的服务器记录。
+
+然后安装 0.2.1。
+
+> 迁移只改引用名，**不搬运密钥值**。升级后原密码可能需要重新输入一次
+> （取决于该密钥此前是否成功写入 `~/.dsh/.credentials.yaml`）。
+
+---
+
 ## 0.2.0 — 2026-11-05
 
 ### 新增

package/README.md

@@ -506,7 +506,8 @@ $DSH_HOME/server-connector/
 
 ### 凭据
 
-- 密码交给 DSH 凭据服务（`$DSH_HOME/.credentials.yaml`），`servers.json` 只存引用，如 `server-connector:srv-03:password`；
+- 密码交给 DSH 凭据服务（`$DSH_HOME/.credentials.yaml`），`servers.json` 只存引用，如 `DSH_SERVER_CONNECTOR_SRV_03_PASSWORD`
+  （必须是 POSIX 标识符，不能含冒号或连字符）；
 - 面板只显示「已设置 / 未设置」，不会回显明文；接口也不会返回密钥；
 - 没有凭据服务时，密码认证会报 `NO_CREDENTIAL`，改用私钥认证即可；
 - 私钥认证只记录**路径**，密钥内容由 `ssh2` 自己读，插件不缓存。

package/lib/registry.js

@@ -336,13 +336,92 @@ function normalizeOptionalTimestamp(value, field, errorCode) {
   return normalizeTimestamp(value, field, errorCode)
 }
 
+/**
+ * The grammar every credential ref must satisfy: a POSIX shell identifier.
+ *
+ * This is @deepseek-ai/dsh-credentials' own contract (`REF_PATTERN`), not an
+ * invention of this plugin. Keeping a local copy is deliberate: a ref this
+ * plugin persists is later parsed by that package, and a mismatch is not a
+ * local error — it prevents `credentials` from activating, which fails the whole
+ * Host startup.
+ */
+const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/**
+ * The ref this plugin derives for a server's password (doc §6.3).
+ *
+ * `server-connector:<id>:password` was the old shape and it was illegal: the
+ * colon and the dash fall outside the grammar above, so persisting it broke the
+ * next startup. The id is folded into a single identifier instead
+ * (`DSH_SERVER_CONNECTOR_SRV_01_PASSWORD`).
+ * @param {string} serverId - e.g. `srv-01`
+ * @returns {string}
+ */
+function deriveCredentialRef(serverId) {
+  const normalised = String(serverId)
+    .toUpperCase()
+    .replace(/[^A-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+  const safe = normalised === '' ? 'SERVER' : normalised
+  return `DSH_SERVER_CONNECTOR_${safe}_PASSWORD`
+}
+
+/**
+ * Validate a caller-supplied credential ref against the same grammar.
+ *
+ * A caller may pass its own ref (an environment-variable name, typically), but
+ * an illegal one must be refused here rather than stored: storing it would
+ * break the next startup instead of this request.
+ * @param {unknown} value
+ * @param {RegistryErrorCode} errorCode
+ * @returns {string}
+ */
+function assertCredentialRef(value, errorCode) {
+  const ref = requiredString(value, 'auth.credentialRef', errorCode)
+  if (!CREDENTIAL_REF_PATTERN.test(ref)) {
+    throw new RegistryError(
+      errorCode,
+      `auth.credentialRef ${JSON.stringify(ref)} must be a POSIX identifier ` +
+        `(letters, digits and underscores, not starting with a digit), because DSH credentials rejects ` +
+        `any other ref and the rejection fails the whole startup.`,
+    )
+  }
+  return ref
+}
+
+/**
+ * Read-time recovery for a ref an older build persisted (doc §6.3).
+ *
+ * Before 0.2.1 this plugin derived `server-connector:<id>:password`, which is
+ * outside the grammar. Those records exist on disk in the wild, and refusing
+ * them at load would leave the plugin unable to start — trading a Host crash for
+ * a plugin that never loads. Instead the illegal legacy shape is mapped onto the
+ * derived one, so the record keeps working and the next write persists the fixed
+ * ref.
+ *
+ * Only the exact legacy shape is migrated. Any other illegal ref is still
+ * refused: silently rewriting a ref this plugin never wrote could point at a
+ * different secret.
+ * @param {unknown} value
+ * @param {string} serverId
+ * @param {RegistryErrorCode} errorCode
+ * @returns {string}
+ */
+function migrateCredentialRef(value, serverId, errorCode) {
+  const ref = requiredString(value, 'auth.credentialRef', errorCode)
+  if (CREDENTIAL_REF_PATTERN.test(ref)) return ref
+  if (ref === `server-connector:${serverId}:password`) return deriveCredentialRef(serverId)
+  return assertCredentialRef(ref, errorCode)
+}
+
 /**
  * @param {unknown} value
  * @param {string} serverId
  * @param {RegistryErrorCode} errorCode
+ * @param {{migrate?: boolean}} [options] - `migrate` is set only by the load path.
  * @returns {{kind:'key', privateKeyPath:string}|{kind:'password', credentialRef:string}|{kind:'agent'}}
  */
-function normalizeAuth(value, serverId, errorCode) {
+function normalizeAuth(value, serverId, errorCode, options = {}) {
   if (value === undefined) return { kind: 'agent' }
   if (!isPlainObject(value)) throw new RegistryError(errorCode, 'auth must be an object.')
   const kind = value.kind
@@ -352,12 +431,20 @@ function normalizeAuth(value, serverId, errorCode) {
   }
   if (kind === 'password') {
     assertKnownFields(value, AUTH_FIELDS.password, errorCode, 'auth')
-    // Doc §6.3: the record keeps a reference, never the password itself. The
-    // conventional ref is `server-connector:<id>:password`.
+    // Doc §6.3: the record keeps a reference, never the password itself.
+    //
+    // The ref MUST be a POSIX shell identifier: @deepseek-ai/dsh-credentials
+    // validates every stored ref with /^[A-Za-z_][A-Za-z0-9_]*$/ while loading
+    // credentials.yaml, and a ref outside that grammar throws during
+    // `credentials` activation. Because `credentials` is a required plugin, that
+    // takes the entire Host down at startup — a persisted bad ref bricks DSH
+    // until the file is edited by hand. Derive and validate accordingly.
     const credentialRef =
       value.credentialRef === undefined
-        ? `server-connector:${serverId}:password`
-        : requiredString(value.credentialRef, 'auth.credentialRef', errorCode)
+        ? deriveCredentialRef(serverId)
+        : options.migrate === true
+          ? migrateCredentialRef(value.credentialRef, serverId, errorCode)
+          : assertCredentialRef(value.credentialRef, errorCode)
     return { kind: 'password', credentialRef }
   }
   if (kind === 'agent') {
@@ -455,6 +542,7 @@ function normalizeCustomRules(value, errorCode) {
  *   errorCode: RegistryErrorCode,
  *   label: string,
  *   createdAt?: string,
+ *   migrate?: boolean,
  * }} options
  * @returns {ServerRecord}
  */
@@ -472,7 +560,7 @@ function normalizeRecord(source, options) {
     host: normalizeHost(source.host, errorCode),
     port: normalizePort(source.port, errorCode),
     username: requiredString(source.username, 'username', errorCode),
-    auth: normalizeAuth(source.auth, id, errorCode),
+    auth: normalizeAuth(source.auth, id, errorCode, { migrate: options.migrate === true }),
     hostKeyMode: normalizeHostKeyMode(source.hostKeyMode, errorCode),
     defaultWorkDir: normalizeWorkDir(source.defaultWorkDir, errorCode),
     enabled: normalizeEnabled(source.enabled, errorCode),
@@ -786,6 +874,9 @@ export class Registry {
         id: recordId,
         errorCode: 'INVALID_REGISTRY',
         label: `servers[${index}]`,
+        // Loading is the one path allowed to repair a legacy credential ref;
+        // writes are strict so this plugin can never persist a bad one again.
+        migrate: true,
       })
       if (seenIds.has(record.id)) {
         throw new RegistryError('INVALID_REGISTRY', `${this.#file}: duplicate server id "${record.id}".`)
@@ -798,7 +889,32 @@ export class Registry {
       seenNames.add(nameKey)
       servers.push(record)
     }
-    return { version: REGISTRY_VERSION, servers }
+    const document = { version: REGISTRY_VERSION, servers }
+    // Persist a repaired legacy ref immediately. Without this the migration
+    // lives only in memory: every later read re-runs it, and a copy of the file
+    // taken before the first write would still carry the illegal ref that breaks
+    // the next startup. The rewrite is conditional so a clean file is never
+    // touched (its mtime stays put).
+    if (this.#migrated(text, document)) await this.#save(document)
+    return document
+  }
+
+  /**
+   * Whether the loaded document differs from what is on disk, i.e. whether the
+   * legacy-ref migration actually changed a record and the file must be rewritten.
+   * @param {string} text - the raw file text that was parsed.
+   * @param {RegistryDocument} document - the normalised document.
+   * @returns {boolean}
+   */
+  #migrated(text, document) {
+    for (const record of document.servers) {
+      if (record.auth.kind !== 'password') continue
+      const ref = record.auth.credentialRef
+      // The normalised ref is legal by construction; if the raw text does not
+      // contain it, this record was migrated.
+      if (!text.includes(JSON.stringify(ref))) return true
+    }
+    return false
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-server-connector",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "DSH plugin: SSH execution for servers configured on this machine, with a built-in high-risk command policy (block / confirm / allow).",
   "type": "module",
   "main": "lib/index.js",