Add allow/deny list support for commands in config YAML (#66)

Author: ssh-esh

src/cli.ts

@@ -6,7 +6,7 @@
 
 import { Command } from 'commander'
 import { createRequire } from 'node:module'
-import { defineCommand, defineGroup } from './factory.ts'
+import { defineCommand, defineGroup, hideBlockedCommands } from './factory.js'
 import { loadConfig } from './config/loader.ts'
 import { setResolvedConfig } from './config/store.ts'
 
@@ -67,9 +67,18 @@ if (firstArg === 'cloud') {
   program.addCommand(defineGroup({ name: 'cloud', description: 'Manage Elastic Cloud deployments and serverless projects' }))
 }
 
+// Load config before Commander parses so --help can hide blocked commands.
+// Uses cosmiconfig auto-discovery (the preAction hook re-loads with any
+// --config/--context overrides when an actual command runs).
+const earlyResult = await loadConfig({})
+if (earlyResult.ok) {
+  setResolvedConfig(earlyResult.value)
+  hideBlockedCommands(program, earlyResult.value.commands)
+}
+
 if (process.argv.slice(2).length === 0) {
   program.outputHelp()
   process.exit(0)
 }
 
-program.parseAsync(process.argv)
+await program.parseAsync(process.argv)

src/config/loader.ts

@@ -63,7 +63,9 @@ export function resolveContext (config: ConfigFile, contextName: string): Resolv
   if (ctx.elasticsearch != null) resolved.elasticsearch = ctx.elasticsearch
   if (ctx.kibana != null) resolved.kibana = ctx.kibana
   if (ctx.cloud != null) resolved.cloud = ctx.cloud
-  return { context: resolved }
+  const result: ResolvedConfig = { context: resolved }
+  if (config.commands != null) result.commands = config.commands
+  return result
 }
 
 /** Options accepted by {@link loadConfig}. */

src/config/schema.ts

@@ -50,14 +50,30 @@ export const ContextSchema = z
     { error: 'at least one service block (elasticsearch, kibana, or cloud) is required' }
   )
 
+/**
+ * Policy controlling which commands are permitted to run.
+ * Only one of `allowed` or `blocked` may be present.
+ * Entries may use a trailing wildcard (e.g. `elasticsearch.*`) to match a namespace.
+ */
+export const CommandPolicySchema = z
+  .looseObject({
+    allowed: z.array(z.string().min(1)).min(1).optional(),
+    blocked: z.array(z.string().min(1)).min(1).optional(),
+  })
+  .refine(
+    (p) => !(p.allowed != null && p.blocked != null),
+    { error: 'commands: "allowed" and "blocked" are mutually exclusive' },
+  )
+
 /** The root configuration file structure. */
 export const ConfigFileSchema = z
   .looseObject({
     current_context: z.string().min(1),
     contexts: z.record(z.string(), ContextSchema).refine(
       (map) => Object.keys(map).length > 0,
-      { error: 'contexts must contain at least one entry' }
-    )
+      { error: 'contexts must contain at least one entry' },
+    ),
+    commands: CommandPolicySchema.optional(),
   })
   .refine(
     (cfg) => cfg.current_context in cfg.contexts,

src/config/store.ts

@@ -33,3 +33,8 @@ export function setResolvedConfig (config: ResolvedConfig): void {
 export function getResolvedConfig (): ResolvedConfig | undefined {
   return _config
 }
+
+/** Resets the store to its initial state. Intended for test cleanup only. */
+export function _testResetConfig(): void {
+  _config = undefined
+}

src/config/types.ts

@@ -8,7 +8,8 @@ import type {
   AuthSchema,
   ServiceBlockSchema,
   ContextSchema,
-  ConfigFileSchema
+  ConfigFileSchema,
+  CommandPolicySchema,
 } from './schema.ts'
 
 /**
@@ -35,7 +36,10 @@ export type Context = z.infer<typeof ContextSchema>
 /** The root configuration file structure. */
 export type ConfigFile = z.infer<typeof ConfigFileSchema>
 
-/** The active context after resolution -- only its configured service blocks, no extras. */
+/** Policy controlling which commands are permitted to run. */
+export type CommandPolicy = z.infer<typeof CommandPolicySchema>
+
+/** The active context after resolution — only its configured service blocks, no extras. */
 export interface ResolvedContext {
   elasticsearch?: ServiceBlock
   kibana?: ServiceBlock
@@ -45,4 +49,6 @@ export interface ResolvedContext {
 /** Typed configuration object passed to command handlers after loading and context resolution. */
 export interface ResolvedConfig {
   context: ResolvedContext
+  /** Optional command allow/deny policy from the config file. */
+  commands?: CommandPolicy
 }

src/factory.ts

@@ -7,7 +7,7 @@ import { Command } from 'commander'
 import { z } from 'zod'
 import { readFileSync } from 'node:fs'
 import assert from 'node:assert/strict'
-import type { ResolvedConfig } from './config/types.ts'
+import type { ResolvedConfig, CommandPolicy } from './config/types.ts'
 import { getResolvedConfig } from './config/store.ts'
 import { extractSchemaArgs, validateSchemaArgs } from './lib/schema-args.ts'
 import type { SchemaArgDefinition } from './lib/schema-args.ts'
@@ -177,6 +177,61 @@ export function _testSetStdinReader (fn: () => string): () => void {
   return () => { stdinReader = prev }
 }
 
+/**
+ * Returns true if `commandDotPath` is permitted under the given policy.
+ *
+ * Matching rules:
+ * - No policy (or empty policy) → always allowed
+ * - `allowed` list → command must match at least one entry
+ * - `blocked` list → command must NOT match any entry
+ * - Entries ending with `.*` match any command whose dot-path starts with the prefix and a `.`
+ *   (e.g. `elasticsearch.*` matches `elasticsearch.search` and `elasticsearch.indices.get`
+ *    but NOT `elasticsearch` itself)
+ * - All other entries are exact matches
+ */
+export function isCommandAllowed(commandDotPath: string, policy: CommandPolicy | undefined): boolean {
+  if (policy == null) return true
+
+  function matches(pattern: string): boolean {
+    if (pattern.endsWith('.*')) {
+      const prefix = pattern.slice(0, -2)
+      return commandDotPath === prefix + '.' + commandDotPath.slice(prefix.length + 1) &&
+        commandDotPath.startsWith(prefix + '.')
+    }
+    return commandDotPath === pattern
+  }
+
+  if (policy.allowed != null) return policy.allowed.some(matches)
+  if (policy.blocked != null) return !policy.blocked.some(matches)
+  return true
+}
+
+// Commander checks `_hidden` to exclude commands from --help, but the
+// property isn't in the public typings —
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function setHidden(cmd: OpaqueCommandHandle, value: boolean): void { (cmd as unknown as any)._hidden = value }
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isHidden(cmd: OpaqueCommandHandle): boolean { return (cmd as unknown as any)._hidden === true }
+
+/**
+ * Walk the command tree and hide any commands the policy blocks.
+ * Groups where every child is hidden are hidden too.
+ * Call on the root program so dot-paths like `es.cat.health` are built correctly.
+ */
+export function hideBlockedCommands(root: OpaqueCommandHandle, policy: CommandPolicy | undefined, prefix = ''): void {
+  if (policy == null) return
+  for (const child of root.commands as OpaqueCommandHandle[]) {
+    const path = prefix ? `${prefix}.${child.name()}` : child.name()
+    const subs = child.commands as OpaqueCommandHandle[]
+    if (subs.length > 0) {
+      hideBlockedCommands(child, policy, path)
+      if (subs.every(isHidden)) setHidden(child, true)
+    } else {
+      setHidden(child, !isCommandAllowed(path, policy))
+    }
+  }
+}
+
 /** converts a kebab-case option name to camelCase to match Commander's opts() keys */
 function camelCase (s: string): string {
   return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
@@ -531,6 +586,27 @@ export function defineCommand<T extends z.ZodType> (config: CommandConfig<T>): O
     }
 
     const resolvedConfig = getResolvedConfig()
+
+    // enforce command policy before any other work
+    if (resolvedConfig?.commands != null) {
+      // commandPath returns e.g. "elastic elasticsearch search"; strip root program name and dot-join
+      const parts = commandPath(cmd).split(' ')
+      // if mounted under a root program (e.g. "elastic"), strip that first segment
+      const dotPath = (parts.length > 1 ? parts.slice(1) : parts).join('.')
+      if (!isCommandAllowed(dotPath, resolvedConfig.commands)) {
+        if (jsonFormat === true) {
+          process.stdout.write(JSON.stringify({
+            error: {
+              code: 'command_blocked',
+              message: `command "${dotPath}" is not allowed by the current policy`,
+            },
+          }) + '\n')
+          throw Object.assign(new Error('command_blocked'), { exitCode: 1 })
+        }
+        return cmd.error(`command "${dotPath}" is not allowed by the current policy`)
+      }
+    }
+
     const parsed: ParsedResult<z.infer<T>> = {
       options,
       ...(resolvedConfig != null ? { config: resolvedConfig } : {})

test/config/loader.test.ts

@@ -240,3 +240,96 @@ describe('loadConfig -- --config-file override', () => {
     assert.ok(!result.ok, 'loadConfig should fail for a nonexistent explicit config path')
   })
 })
+
+// ---------------------------------------------------------------------------
+// T019 — commands policy threading through loadConfig and resolveContext
+// ---------------------------------------------------------------------------
+
+describe('T019: commands policy in ResolvedConfig', () => {
+  let tmpDir: string
+  after(async () => rm(tmpDir, { recursive: true }))
+  before(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'elastic-cli-policy-'))
+  })
+
+  it('resolveContext includes commands policy when present', () => {
+    const config: ConfigFile = {
+      ...VALID_CONFIG_OBJECT,
+      commands: { allowed: ['ping', 'elasticsearch.search'] },
+    }
+    const resolved = resolveContext(config, 'local')
+    assert.deepEqual(resolved.commands, { allowed: ['ping', 'elasticsearch.search'] })
+  })
+
+  it('resolveContext omits commands when not present in config', () => {
+    const resolved = resolveContext(VALID_CONFIG_OBJECT, 'local')
+    assert.equal(resolved.commands, undefined)
+  })
+
+  it('loadConfig threads allowed list into ResolvedConfig', async () => {
+    const yaml = `
+current_context: local
+contexts:
+  local:
+    elasticsearch:
+      url: http://localhost:9200
+      auth:
+        api_key: key1
+commands:
+  allowed:
+    - ping
+    - elasticsearch.search
+`.trimStart()
+    const configPath = join(tmpDir, 'allowed.yml')
+    await writeFile(configPath, yaml)
+    const result = await loadConfig({ configPath })
+    assert.ok(result.ok)
+    if (!result.ok) return
+    assert.deepEqual(result.value.commands, { allowed: ['ping', 'elasticsearch.search'] })
+  })
+
+  it('loadConfig threads blocked list into ResolvedConfig', async () => {
+    const yaml = `
+current_context: local
+contexts:
+  local:
+    elasticsearch:
+      url: http://localhost:9200
+      auth:
+        api_key: key1
+commands:
+  blocked:
+    - elasticsearch.bulk
+    - config.*
+`.trimStart()
+    const configPath = join(tmpDir, 'blocked.yml')
+    await writeFile(configPath, yaml)
+    const result = await loadConfig({ configPath })
+    assert.ok(result.ok)
+    if (!result.ok) return
+    assert.deepEqual(result.value.commands, { blocked: ['elasticsearch.bulk', 'config.*'] })
+  })
+
+  it('loadConfig returns error for config with both allowed and blocked', async () => {
+    const yaml = `
+current_context: local
+contexts:
+  local:
+    elasticsearch:
+      url: http://localhost:9200
+      auth:
+        api_key: key1
+commands:
+  allowed:
+    - ping
+  blocked:
+    - elasticsearch.bulk
+`.trimStart()
+    const configPath = join(tmpDir, 'both.yml')
+    await writeFile(configPath, yaml)
+    const result = await loadConfig({ configPath })
+    assert.ok(!result.ok, 'should fail when both allowed and blocked are present')
+    if (result.ok) return
+    assert.match(result.error.message, /mutually exclusive/)
+  })
+})