dsh-server-connector 0.1.0 → 0.2.1

package/lib/policy.js

@@ -278,6 +278,162 @@ export function compareDecisions(a, b) {
   return RANK[a] - RANK[b]
 }
 
+// ------------------------------------------------- custom rules (doc §4.4) --
+
+/** Longest accepted `pattern` source. Past this the rule is almost certainly a paste accident. */
+export const MAX_CUSTOM_PATTERN_LENGTH = 512
+
+/** Most custom rules one server may carry. Bounds both the UI and the regex sweep. */
+export const MAX_CUSTOM_RULES = 50
+
+/**
+ * Shapes that invite catastrophic backtracking: a quantified group whose body is
+ * itself quantified (`(a+)+`, `(a*)*`, `(.*)+`). Conservative on purpose — it
+ * rejects a few harmless forms rather than admitting a ReDoS.
+ */
+const NESTED_QUANTIFIER = /\(\s*[^()]*[+*]\s*\)\s*[+*]/
+
+/** One custom rule as stored on a server record (doc §3.1). */
+/**
+ * @typedef {object} CustomRule
+ * @property {string} id
+ * @property {string} label
+ * @property {string} pattern - regex source, compiled on read
+ * @property {Decision} defaultDecision - `confirm` or `block`; never `allow`
+ * @property {string} description
+ */
+
+/**
+ * A custom rule that failed validation. The route layer turns this into a 400.
+ */
+export class RuleError extends Error {
+  /**
+   * @param {string} code - machine-readable reason
+   * @param {string} message - human-readable, shown in the panel
+   */
+  constructor(code, message) {
+    super(message)
+    this.name = 'RuleError'
+    this.code = code
+  }
+}
+
+/**
+ * Validate and compile one custom rule (doc §4.4.2). Every check runs before the
+ * rule is allowed to touch `servers.json`, so a rule that cannot be honoured is
+ * never stored.
+ *
+ * `samples` is optional: when given, at least one must match, which is the
+ * check that catches "I wrote a regex that never fires".
+ * @param {unknown} value - the rule as it arrived (already id-assigned)
+ * @param {{samples?: string[], takenIds?: Iterable<string>}} [options]
+ * @returns {CustomRule}
+ */
+export function validateCustomRule(value, options = {}) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new RuleError('INVALID_RULE', 'a custom rule must be an object.')
+  }
+  const rule = /** @type {Record<string, unknown>} */ (value)
+  const label = typeof rule.label === 'string' ? rule.label.trim() : ''
+  if (label === '') throw new RuleError('INVALID_RULE', 'label must be a non-empty string.')
+  if (label.length > 80) throw new RuleError('INVALID_RULE', 'label must be at most 80 characters.')
+  const description = typeof rule.description === 'string' ? rule.description.trim() : ''
+  if (description.length > 400) throw new RuleError('INVALID_RULE', 'description must be at most 400 characters.')
+  if (rule.defaultDecision !== 'confirm' && rule.defaultDecision !== 'block') {
+    // `allow` is refused outright: a rule that permits what the engine already
+    // permits buys nothing, and it is the only way to fake a loosening.
+    throw new RuleError('INVALID_RULE', 'defaultDecision must be "confirm" or "block".')
+  }
+  if (typeof rule.pattern !== 'string' || rule.pattern.trim() === '') {
+    throw new RuleError('INVALID_RULE', 'pattern must be a non-empty regex source.')
+  }
+  const pattern = rule.pattern.trim()
+  if (pattern.length > MAX_CUSTOM_PATTERN_LENGTH) {
+    throw new RuleError('INVALID_RULE', `pattern must be at most ${MAX_CUSTOM_PATTERN_LENGTH} characters.`)
+  }
+  if (NESTED_QUANTIFIER.test(pattern)) {
+    throw new RuleError(
+      'INVALID_RULE',
+      'pattern contains a nested quantifier like (a+)+, which can backtrack catastrophically. Rewrite it without the inner repetition.',
+    )
+  }
+  /** @type {RegExp} */
+  let compiled
+  try {
+    compiled = new RegExp(pattern, 'i')
+  } catch (error) {
+    throw new RuleError('INVALID_RULE', `pattern is not a valid regular expression: ${/** @type {Error} */ (error).message}`)
+  }
+  // A pattern that matches the empty string matches every command, which would
+  // block or confirm everything on that server.
+  if (compiled.test('')) {
+    throw new RuleError('INVALID_RULE', 'pattern matches the empty string, so it would match every command.')
+  }
+  const id = typeof rule.id === 'string' ? rule.id.trim() : ''
+  if (id === '') throw new RuleError('INVALID_RULE', 'id must be a non-empty string.')
+  const taken = new Set(options.takenIds ?? [])
+  if (RULES_BY_ID.has(id) || taken.has(id)) {
+    throw new RuleError('DUPLICATE_RULE', `rule id "${id}" is already in use on this server.`)
+  }
+  const samples = Array.isArray(options.samples) ? options.samples.filter((s) => typeof s === 'string' && s.trim() !== '') : []
+  if (samples.length > 0 && !samples.some((sample) => compiled.test(sample))) {
+    throw new RuleError(
+      'RULE_NEVER_MATCHES',
+      'none of the sample commands matched this pattern; it would never fire.',
+    )
+  }
+  return Object.freeze({
+    id,
+    label,
+    pattern,
+    defaultDecision: /** @type {Decision} */ (rule.defaultDecision),
+    description,
+  })
+}
+
+/**
+ * Compile a stored custom rule for matching. A record that fails to compile is
+ * skipped rather than thrown: `servers.json` may predate a stricter validator,
+ * and one bad rule must not take down every command on that server.
+ * @param {CustomRule} rule
+ * @returns {Rule|null}
+ */
+function compileCustomRule(rule) {
+  /** @type {RegExp} */
+  let pattern
+  try {
+    pattern = new RegExp(rule.pattern, 'i')
+  } catch {
+    return null
+  }
+  return Object.freeze({
+    id: rule.id,
+    label: rule.label,
+    defaultDecision: rule.defaultDecision,
+    description: rule.description,
+    pattern,
+    custom: true,
+  })
+}
+
+/**
+ * The rule set that applies to one server: the built-in catalog, then that
+ * server's custom rules (doc §4.2.5). Custom rules enjoy no privilege — they run
+ * through the same match and strictest-wins logic.
+ * @param {ReadonlyArray<CustomRule>|undefined} customRules
+ * @returns {ReadonlyArray<Rule>}
+ */
+export function rulesFor(customRules) {
+  if (!Array.isArray(customRules) || customRules.length === 0) return RULES
+  const extra = []
+  for (const rule of customRules) {
+    if (rule === null || typeof rule !== 'object') continue
+    const compiled = compileCustomRule(/** @type {CustomRule} */ (rule))
+    if (compiled !== null) extra.push(compiled)
+  }
+  return extra.length === 0 ? RULES : [...RULES, ...extra]
+}
+
 /**
  * Split a command line into the subcommands every rule must be checked against.
  *
@@ -300,24 +456,27 @@ export function splitSubcommands(command) {
 /**
  * Separate the two accepted second-argument shapes into overrides plus disabled
  * rule ids:
- * - a server record (`{ policy, disabledRules }`, doc §3.1), or
+ * - a server record (`{ policy, disabledRules, customRules }`, doc §3.1), or
  * - a bare per-rule override map (`{ 'rm-recursive': 'confirm' }`).
  *
  * A third argument may carry `disabledRules` alongside a bare override map.
  * @param {Record<string, unknown>|undefined} serverPolicy
  * @param {string[]|undefined} disabledRules
- * @returns {{overrides: Record<string, unknown>, disabled: Set<string>}}
+ * @returns {{overrides: Record<string, unknown>, disabled: Set<string>, customRules: CustomRule[]}}
  */
 function normalizeServerPolicy(serverPolicy, disabledRules) {
   const disabled = new Set(Array.isArray(disabledRules) ? disabledRules : [])
   if (serverPolicy === undefined || serverPolicy === null) {
-    return { overrides: {}, disabled }
+    return { overrides: {}, disabled, customRules: [] }
   }
   if (typeof serverPolicy !== 'object') throw new TypeError('serverPolicy must be an object')
   if (Array.isArray(serverPolicy.disabledRules)) {
     for (const id of serverPolicy.disabledRules) if (typeof id === 'string') disabled.add(id)
   }
   const fields = /** @type {Record<string, unknown>} */ (serverPolicy)
+  const customRules = Array.isArray(fields.customRules)
+    ? /** @type {CustomRule[]} */ (fields.customRules.filter((rule) => rule !== null && typeof rule === 'object'))
+    : []
   const record = 'policy' in fields || 'disabledRules' in fields
   const policy = fields.policy
   /** @type {Record<string, unknown>} */
@@ -326,7 +485,7 @@ function normalizeServerPolicy(serverPolicy, disabledRules) {
       ? /** @type {Record<string, unknown>} */ (policy)
       : {}
     : fields
-  return { overrides, disabled }
+  return { overrides, disabled, customRules }
 }
 
 /**
@@ -390,10 +549,12 @@ function ruleMatches(rule, command, segments) {
  */
 export function check(command, serverPolicy = {}, disabledRules) {
   const segments = splitSubcommands(command)
-  const { overrides, disabled } = normalizeServerPolicy(serverPolicy, disabledRules)
+  const { overrides, disabled, customRules } = normalizeServerPolicy(serverPolicy, disabledRules)
 
   const matches = []
-  for (const rule of RULES) {
+  // Built-ins first, then this server's custom rules (doc §4.2.5): the custom
+  // set is part of the same sweep, so strictest-wins needs no special case.
+  for (const rule of rulesFor(customRules)) {
     if (disabled.has(rule.id)) continue
     if (!ruleMatches(rule, command, segments)) continue
     matches.push({

package/lib/registry.js

@@ -21,6 +21,8 @@ import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 
+import { MAX_CUSTOM_RULES, RuleError, validateCustomRule } from './policy.js'
+
 /** Schema version written to, and required from, `servers.json`. */
 export const REGISTRY_VERSION = 1
 
@@ -57,8 +59,10 @@ export const DECISION_VALUES = Object.freeze(['allow', 'confirm', 'block'])
  * @property {{kind:'key', privateKeyPath:string}|{kind:'password', credentialRef:string}|{kind:'agent'}} auth
  * @property {'accept-new'|'verify'|'off'} hostKeyMode
  * @property {string|null} defaultWorkDir
+ * @property {boolean} enabled
  * @property {Record<string, 'allow'|'confirm'|'block'>} policy
  * @property {string[]} disabledRules
+ * @property {import('./policy.js').CustomRule[]} customRules
  * @property {string} createdAt
  * @property {string|null} lastConnectedAt
  */
@@ -133,9 +137,11 @@ const CREATE_FIELDS = new Set([
   'username',
   'auth',
   'hostKeyMode',
+  'enabled',
   'defaultWorkDir',
   'policy',
   'disabledRules',
+  'customRules',
 ])
 
 /** Fields an update() call accepts; `id` and `createdAt` are immutable. */
@@ -286,6 +292,22 @@ function normalizeWorkDir(value, errorCode) {
   return trimmed === '' ? null : trimmed
 }
 
+/**
+ * The enable switch (doc §3.1, enable-switch spec).
+ *
+ * Absent means enabled: files written before the switch existed carry no
+ * `enabled` key, and silently disabling every server on load would be a
+ * destructive surprise.
+ * @param {unknown} value
+ * @param {RegistryErrorCode} errorCode
+ * @returns {boolean}
+ */
+function normalizeEnabled(value, errorCode) {
+  if (value === undefined || value === null) return true
+  if (typeof value !== 'boolean') throw new RegistryError(errorCode, 'enabled must be a boolean.')
+  return value
+}
+
 /**
  * @param {unknown} value
  * @param {string} field
@@ -314,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
@@ -330,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') {
@@ -387,6 +496,41 @@ function normalizeDisabledRules(value, errorCode) {
   return ids
 }
 
+/**
+ * Validate the custom-rule list of one record (doc §4.4.2).
+ *
+ * Ids are unique per server and must not collide with a built-in id. The
+ * decision may only be `confirm` or `block` — a rule that permits what the
+ * engine already permits buys nothing.
+ * @param {unknown} value
+ * @param {RegistryErrorCode} errorCode
+ * @returns {import('./policy.js').CustomRule[]}
+ */
+function normalizeCustomRules(value, errorCode) {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) throw new RegistryError(errorCode, 'customRules must be an array of rules.')
+  if (value.length > MAX_CUSTOM_RULES) {
+    throw new RegistryError(errorCode, `customRules may hold at most ${MAX_CUSTOM_RULES} rules.`)
+  }
+  /** @type {import('./policy.js').CustomRule[]} */
+  const rules = []
+  /** @type {string[]} */
+  const seen = []
+  for (const item of value) {
+    /** @type {import('./policy.js').CustomRule} */
+    let rule
+    try {
+      rule = validateCustomRule(item, { takenIds: seen })
+    } catch (error) {
+      if (error instanceof RuleError) throw new RegistryError(errorCode, `customRules: ${error.message}`)
+      throw error
+    }
+    seen.push(rule.id)
+    rules.push(rule)
+  }
+  return rules
+}
+
 /**
  * Validate and canonicalise one complete record. Create, update and load all
  * go through this function, so a stored record and a freshly created one have
@@ -398,6 +542,7 @@ function normalizeDisabledRules(value, errorCode) {
  *   errorCode: RegistryErrorCode,
  *   label: string,
  *   createdAt?: string,
+ *   migrate?: boolean,
  * }} options
  * @returns {ServerRecord}
  */
@@ -415,11 +560,13 @@ 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),
     policy: normalizePolicy(source.policy, errorCode),
     disabledRules: normalizeDisabledRules(source.disabledRules, errorCode),
+    customRules: normalizeCustomRules(source.customRules, errorCode),
     createdAt,
     lastConnectedAt: normalizeOptionalTimestamp(source.lastConnectedAt, 'lastConnectedAt', errorCode),
   }
@@ -727,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}".`)
@@ -739,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
   }
 
   /**