dsh-server-connector 0.1.0 → 0.2.0

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
@@ -387,6 +409,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
@@ -418,8 +475,10 @@ function normalizeRecord(source, options) {
     auth: normalizeAuth(source.auth, id, errorCode),
     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),
   }