dsh-server-connector 0.2.0 → 0.2.2

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.2",
   "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",