@marcusrbrown/infra 0.9.7 → 0.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcusrbrown/infra",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
   "keywords": [
     "infra",

package/src/commands/mcp.test.ts

@@ -23,12 +23,9 @@
  * //   proc.kill()
  */
 
-import type {CallToolResult} from '@modelcontextprotocol/sdk/types.js'
-
 import {createMcpAction} from '@goke/mcp'
 import {Client} from '@modelcontextprotocol/sdk/client'
 import {InMemoryTransport} from '@modelcontextprotocol/sdk/inMemory.js'
-import {CallToolResultSchema} from '@modelcontextprotocol/sdk/types.js'
 import {afterAll, beforeAll, describe, expect, test} from 'bun:test'
 import {goke} from 'goke'
 
@@ -41,11 +38,20 @@ import {registerUmamiCommands} from './umami'
 
 // ─── Tool name constants ──────────────────────────────────────────────────────
 
-/** Derived from the production MCP_ALLOWLIST — spaces replaced by underscores. */
-const EXPECTED_TOOLS = [...MCP_ALLOWLIST].map(name => name.replaceAll(' ', '_')).sort()
+/**
+ * The MCP tool surface, pinned as an INDEPENDENT literal (deliberately NOT
+ * derived from MCP_ALLOWLIST) so allowlist drift surfaces as a test failure —
+ * per the Tier-1 test bar in packages/cli/AGENTS.md. Five read-only status tools.
+ */
+const EXPECTED_TOOLS = ['cliproxy_status', 'gateway_status', 'keeweb_status', 'status', 'umami_status'].sort()
 
-/** The 9 CLI-only commands that must NOT appear in the MCP tool list. */
+/**
+ * CLI-only commands that must NOT appear in the MCP tool list: the
+ * non-interactive/streaming-only commands plus the source-gated sensitive
+ * commands (mutating or secret-disclosing).
+ */
 const CLI_ONLY_TOOLS = [
+  // Non-interactive / streaming — excluded since before the source-gate change
   'cliproxy_deploy',
   'cliproxy_login',
   'cliproxy_open',
@@ -57,6 +63,13 @@ const CLI_ONLY_TOOLS = [
   'keeweb_open',
   'umami_deploy',
   'umami_logs',
+  // Source-gated sensitive commands (mutating or secret-disclosing)
+  'gateway_backup',
+  'cliproxy_keys_list',
+  'cliproxy_keys_add',
+  'cliproxy_keys_remove',
+  'cliproxy_config_get',
+  'cliproxy_config_set',
 ].sort()
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -73,14 +86,6 @@ function buildTestCli(): ReturnType<typeof goke> {
   return cli
 }
 
-/** Extract all text block content from a CallToolResult, joined by newline. */
-function allText(result: CallToolResult): string {
-  return result.content
-    .filter((block): block is {type: 'text'; text: string} => block.type === 'text')
-    .map(block => block.text)
-    .join('\n')
-}
-
 // ─── Suite ────────────────────────────────────────────────────────────────────
 
 describe('mcp integration (Tier-1, in-process)', () => {
@@ -123,286 +128,11 @@ describe('mcp integration (Tier-1, in-process)', () => {
     expect(names).toEqual(EXPECTED_TOOLS)
   })
 
-  test('cli-only commands are absent from the tool list', async () => {
+  test('source-gated sensitive commands are absent from the MCP tool list', async () => {
     const result = await client.listTools()
     const names = new Set(result.tools.map((t: {name: string}) => t.name))
     for (const excluded of CLI_ONLY_TOOLS) {
       expect(names.has(excluded)).toBe(false)
     }
   })
-
-  // ── Mode B contract: gateway_backup ───────────────────────────────────────
-  //
-  // gateway_backup reads GATEWAY_HOST before attempting any SSH call.
-  // When GATEWAY_HOST is unset the action exits synchronously with a
-  // well-known error message — no network contact is made.
-  // The MCP layer must wrap that failure as an error CallToolResult
-  // (isError: true) rather than throwing, and the content must contain
-  // the exact error message from gatewayBackupAction so we catch contract
-  // regressions if the message ever changes.
-
-  test('gateway_backup wraps missing-GATEWAY_HOST as an error CallToolResult with the known message', async () => {
-    const originalHost = process.env.GATEWAY_HOST
-
-    try {
-      // Delete GATEWAY_HOST to trigger the fast synchronous error path inside
-      // gatewayBackupAction — no SSH or network call is made.
-      delete process.env.GATEWAY_HOST
-
-      const rawResult = await client.callTool(
-        {
-          name: 'gateway_backup',
-          arguments: {},
-        },
-        CallToolResultSchema,
-      )
-
-      const result: CallToolResult = CallToolResultSchema.parse(rawResult)
-
-      // The MCP layer must surface the error as a content block, not a thrown exception.
-      expect(result.isError).toBe(true)
-      expect(result.content.length).toBeGreaterThan(0)
-
-      // The content must carry the exact contract-bearing error string from
-      // gatewayBackupAction. This assertion fails if the error message changes.
-      expect(allText(result)).toContain('Gateway host not set. Export GATEWAY_HOST before running backup.')
-    } finally {
-      if (originalHost === undefined) {
-        delete process.env.GATEWAY_HOST
-      } else {
-        process.env.GATEWAY_HOST = originalHost
-      }
-    }
-  })
-
-  // ── Mode C contract: cliproxy_keys_list ───────────────────────────────────
-  //
-  // Mode C: when a command returns structured data AND prints to stdout,
-  // the CallToolResult must contain BOTH a stdout text block AND a
-  // stringified return-value text block.
-  test('cliproxy_keys_list returns BOTH stdout block AND structured return block (Mode C contract)', async () => {
-    const originalFetch = globalThis.fetch
-    const originalKey = process.env.CLIPROXY_MANAGEMENT_KEY
-
-    try {
-      process.env.CLIPROXY_MANAGEMENT_KEY = 'test-management-key'
-
-      globalThis.fetch = (async (_url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
-        return new Response(JSON.stringify(['fro-bot-test1', 'fro-bot-test2']), {
-          status: 200,
-          headers: {'content-type': 'application/json'},
-        })
-      }) as typeof fetch
-
-      const rawResult = await client.callTool(
-        {
-          name: 'cliproxy_keys_list',
-          arguments: {},
-        },
-        CallToolResultSchema,
-      )
-
-      const result: CallToolResult = CallToolResultSchema.parse(rawResult)
-
-      // Mode C contract: at least 2 content blocks (stdout text + structured return)
-      expect(result.content.length).toBeGreaterThanOrEqual(2)
-
-      const text = allText(result)
-
-      // One block must contain the formatted stdout (key names printed by the action)
-      expect(text).toContain('fro-bot-test1')
-
-      // One block must contain the stringified return value (JSON array of key names)
-      const hasStructuredReturn = result.content.some(block => {
-        if (block.type !== 'text') return false
-        try {
-          const parsed = JSON.parse(block.text) as unknown
-          return Array.isArray(parsed) && parsed.includes('fro-bot-test1') && parsed.includes('fro-bot-test2')
-        } catch {
-          return false
-        }
-      })
-      expect(hasStructuredReturn).toBe(true)
-    } finally {
-      globalThis.fetch = originalFetch
-      if (originalKey === undefined) {
-        delete process.env.CLIPROXY_MANAGEMENT_KEY
-      } else {
-        process.env.CLIPROXY_MANAGEMENT_KEY = originalKey
-      }
-    }
-  })
-
-  // ── Positional-arg routing: cliproxy_keys_add ─────────────────────────────
-  //
-  // The MCP inputSchema for cliproxy_keys_add has a single required property
-  // `key` (derived from the command's positional `<key>` argument). This test
-  // proves that goke routes the MCP argument value through to the action's
-  // positional parameter (apiKeyToAdd) by asserting the key name appears in
-  // the action's output text.
-  //
-  // Verified inputSchema (empirical): { properties: { key: { type: "string",
-  //   description: "Management API key…" }, url: { type: "string" } },
-  //   required: ["key"] }
-
-  test('cliproxy_keys_add routes the positional key argument through MCP', async () => {
-    const originalFetch = globalThis.fetch
-    const originalKey = process.env.CLIPROXY_MANAGEMENT_KEY
-
-    try {
-      process.env.CLIPROXY_MANAGEMENT_KEY = 'test-management-key'
-
-      globalThis.fetch = (async (_url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
-        const method = typeof _init?.method === 'string' ? _init.method.toUpperCase() : 'GET'
-        if (method === 'GET') {
-          // Return empty current key list so the new key is not already present
-          return new Response(JSON.stringify([]), {
-            status: 200,
-            headers: {'content-type': 'application/json'},
-          })
-        }
-
-        // PUT response — the action ignores the body and logs the new count
-        return new Response(JSON.stringify(['tier1-test-key']), {
-          status: 200,
-          headers: {'content-type': 'application/json'},
-        })
-      }) as typeof fetch
-
-      const rawResult = await client.callTool(
-        {
-          name: 'cliproxy_keys_add',
-          // `key` is the positional <key> arg (the API key to add).
-          // Verified from listTools() inputSchema — required property.
-          arguments: {key: 'tier1-test-key'},
-        },
-        CallToolResultSchema,
-      )
-
-      const result: CallToolResult = CallToolResultSchema.parse(rawResult)
-
-      expect(result.isError).not.toBe(true)
-      // The action logs `Added key "tier1-test-key"` — presence proves the
-      // positional arg was correctly routed from the MCP call.
-      expect(allText(result)).toContain('tier1-test-key')
-    } finally {
-      globalThis.fetch = originalFetch
-      if (originalKey === undefined) {
-        delete process.env.CLIPROXY_MANAGEMENT_KEY
-      } else {
-        process.env.CLIPROXY_MANAGEMENT_KEY = originalKey
-      }
-    }
-  })
-
-  // ── Positional-arg routing: cliproxy_keys_remove ──────────────────────────
-  //
-  // The MCP inputSchema for cliproxy_keys_remove has a required property `key`
-  // (derived from the positional `<key>` argument). The action issues a DELETE
-  // request with `?value=<apiKeyToRemove>` and logs the response. The fetch mock
-  // echoes back the query-parameter value so we can assert it was routed correctly.
-  //
-  // Verified inputSchema (empirical): { properties: { key: { type: "string" },
-  //   url: { type: "string" } }, required: ["key"] }
-
-  test('cliproxy_keys_remove routes the positional key argument through MCP', async () => {
-    const originalFetch = globalThis.fetch
-    const originalKey = process.env.CLIPROXY_MANAGEMENT_KEY
-
-    try {
-      process.env.CLIPROXY_MANAGEMENT_KEY = 'test-management-key'
-
-      globalThis.fetch = (async (_url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
-        // The action appends ?value=<apiKeyToRemove> — echo it back in the
-        // response body so the assertion can verify positional routing.
-        const urlStr = typeof _url === 'string' ? _url : _url instanceof URL ? _url.href : (_url as Request).url
-        const url = new URL(urlStr)
-        const removedKey = url.searchParams.get('value') ?? 'unknown'
-        return new Response(JSON.stringify({removed: removedKey}), {
-          status: 200,
-          headers: {'content-type': 'application/json'},
-        })
-      }) as typeof fetch
-
-      const rawResult = await client.callTool(
-        {
-          name: 'cliproxy_keys_remove',
-          // `key` is the positional <key> arg (the API key to remove).
-          // Verified from listTools() inputSchema — required property.
-          arguments: {key: 'tier1-test-remove-key'},
-        },
-        CallToolResultSchema,
-      )
-
-      const result: CallToolResult = CallToolResultSchema.parse(rawResult)
-
-      expect(result.isError).not.toBe(true)
-      // The response includes the echoed ?value= param — proves the positional
-      // arg was routed to the DELETE URL query parameter.
-      expect(allText(result)).toContain('tier1-test-remove-key')
-    } finally {
-      globalThis.fetch = originalFetch
-      if (originalKey === undefined) {
-        delete process.env.CLIPROXY_MANAGEMENT_KEY
-      } else {
-        process.env.CLIPROXY_MANAGEMENT_KEY = originalKey
-      }
-    }
-  })
-
-  // ── Positional-arg routing: cliproxy_config_set ───────────────────────────
-  //
-  // The MCP inputSchema for cliproxy_config_set has two required properties:
-  // `field` and `value` (both positional). The action PUT-s `{value: <parsed>}`
-  // to the field-specific endpoint and logs the response JSON. Returning the
-  // value in the mock response lets us assert both positionals were routed.
-  //
-  // Verified inputSchema (empirical): { properties: { field: { type: "string",
-  //   description: "Positional argument field" }, value: { type: "string",
-  //   description: "Positional argument value" }, url: …, key: … },
-  //   required: ["field","value"] }
-
-  test('cliproxy_config_set routes both positional arguments (field and value) through MCP', async () => {
-    const originalFetch = globalThis.fetch
-    const originalKey = process.env.CLIPROXY_MANAGEMENT_KEY
-
-    try {
-      process.env.CLIPROXY_MANAGEMENT_KEY = 'test-management-key'
-
-      globalThis.fetch = (async (_url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
-        // Echo back the parsed body so we can assert the value was routed.
-        // The action sends {value: <parsedValue>}. We return it as-is.
-        const body = _init?.body
-        const parsed: unknown = body ? JSON.parse(String(body)) : {}
-        return new Response(JSON.stringify(parsed), {
-          status: 200,
-          headers: {'content-type': 'application/json'},
-        })
-      }) as typeof fetch
-
-      const rawResult = await client.callTool(
-        {
-          name: 'cliproxy_config_set',
-          // `field` and `value` are the positional args from `<field> <value>`.
-          // `proxy-url` is a string-type mutable field — no parsing needed.
-          arguments: {field: 'proxy-url', value: 'tier1-test-url'},
-        },
-        CallToolResultSchema,
-      )
-
-      const result: CallToolResult = CallToolResultSchema.parse(rawResult)
-
-      expect(result.isError).not.toBe(true)
-      // The response echoes back {value: "tier1-test-url"} — presence of the
-      // value proves positional routing worked end-to-end.
-      expect(allText(result)).toContain('tier1-test-url')
-    } finally {
-      globalThis.fetch = originalFetch
-      if (originalKey === undefined) {
-        delete process.env.CLIPROXY_MANAGEMENT_KEY
-      } else {
-        process.env.CLIPROXY_MANAGEMENT_KEY = originalKey
-      }
-    }
-  })
 })

package/src/commands/mcp.ts

@@ -4,6 +4,7 @@ import {createMcpAction} from '@goke/mcp'
 /**
  * Commands intentionally excluded from MCP exposure (not in MCP_ALLOWLIST):
  *
+ * Infrastructure / streaming (deferred or not MCP-suitable):
  * - `gateway deploy`   — subprocess streaming (Bun.spawn with stdout: 'inherit'), deferred to MCP v2 (#291)
  * - `cliproxy deploy`  — subprocess streaming, deferred to MCP v2 (#291)
  * - `keeweb deploy`    — subprocess streaming, deferred to MCP v2 (#291)
@@ -15,16 +16,23 @@ import {createMcpAction} from '@goke/mcp'
  * - `keeweb open`      — host-machine side effect (spawns local browser, requires user intent)
  * - `umami deploy`     — intentionally CLI-only: mutates live deployment and requires environment approval
  * - `umami logs`       — intentionally CLI-only: streams logs that may emit sensitive data (DB passwords, app secrets)
+ *
+ * Source-gated sensitive commands (security — CLI-only, never MCP-exposed):
+ * - `gateway backup`       — secret-bearing: writes CA private key material to a tarball; CLI-only
+ * - `cliproxy keys list`   — secret-disclosing: prints live bearer tokens in plaintext; CLI-only
+ * - `cliproxy keys add`    — mutating: creates live bearer tokens on the proxy; CLI-only
+ * - `cliproxy keys remove` — mutating: revokes live bearer tokens on the proxy; CLI-only
+ * - `cliproxy config get`  — secret-disclosing: dumps management config incl. management key; CLI-only
+ * - `cliproxy config set`  — mutating: overwrites CLIProxyAPI runtime config; CLI-only
+ *
+ * A defense-in-depth backstop also denies these in opencode.jsonc `permission`
+ * so that even if MCP_ALLOWLIST were mistakenly re-expanded, opencode's native
+ * tool permission check would block execution. Both layers are enforced by
+ * the `gates every sensitive infra MCP tool` test in conventions.test.ts.
  */
 export const MCP_ALLOWLIST: ReadonlySet<string> = new Set([
   'gateway status',
-  'gateway backup',
   'cliproxy status',
-  'cliproxy keys list',
-  'cliproxy keys add',
-  'cliproxy keys remove',
-  'cliproxy config get',
-  'cliproxy config set',
   'keeweb status',
   'umami status',
   'status',

package/src/conventions.test.ts

@@ -1,11 +1,44 @@
 import {relative, resolve} from 'node:path'
 import {describe, expect, it} from 'bun:test'
 import {parse as parseYaml} from 'yaml'
+import {MCP_ALLOWLIST} from './commands/mcp'
 
 const REPO_ROOT = resolve(import.meta.dir, '../../..')
 const INTERNAL_ORGS = new Set(['marcusrbrown'])
 const ALLOWED_SHELL_SCRIPTS = new Set(['apps/keeweb/deploy.sh'])
 
+// ---------------------------------------------------------------------------
+// MCP drift-guard: sensitive tool set (two-layer security model)
+// ---------------------------------------------------------------------------
+//
+// These 6 commands are source-gated: they are NOT in MCP_ALLOWLIST and are
+// therefore never registered as MCP tools. They remain CLI-only.
+//
+// WHY each is source-gated (primary layer — MCP_ALLOWLIST exclusion):
+//   cliproxy keys add    — mutating: creates live bearer tokens on the proxy
+//   cliproxy keys remove — mutating: revokes live bearer tokens
+//   cliproxy config set  — mutating: overwrites CLIProxyAPI runtime config
+//   gateway backup       — secret-bearing: writes CA private key material to a tarball
+//   cliproxy keys list   — secret-disclosing: prints live bearer tokens in plaintext
+//   cliproxy config get  — secret-disclosing: dumps management config incl. management key
+//
+// Defense-in-depth (secondary layer — opencode.jsonc `permission: deny`):
+// Even if MCP_ALLOWLIST were mistakenly re-expanded, opencode's native tool
+// permission check provides a backstop that denies these tool calls centrally
+// before execution. Both layers must stay in sync; the test below enforces it.
+//
+// A conventions test below asserts every entry (a) is NOT in MCP_ALLOWLIST
+// (source-gated out) and (b) is still denied in opencode.jsonc under the
+// prefixed tool id (defense-in-depth backstop).
+const SENSITIVE_MCP_COMMANDS: readonly string[] = [
+  'cliproxy keys add',
+  'cliproxy keys remove',
+  'cliproxy config set',
+  'gateway backup',
+  'cliproxy keys list',
+  'cliproxy config get',
+]
+
 // Accepted version-comment forms on SHA-pinned `uses:` lines:
 //   # v6.0.2                        (semver tag)
 //   # renovate-changesets@0.2.31    (scoped release tag)
@@ -242,6 +275,53 @@ describe('repo conventions', () => {
     const offenders = files.map(f => relative(REPO_ROOT, f)).filter(f => !ALLOWED_SHELL_SCRIPTS.has(f))
     expect(offenders).toEqual([])
   })
+
+  it('gates every sensitive infra MCP tool in opencode.jsonc', async () => {
+    // Parse opencode.jsonc tolerantly: it uses JSONC syntax (// line comments,
+    // trailing commas). Strategy:
+    //   1. Strip full-line comments — lines whose first non-whitespace is `//`.
+    //      This avoids breaking the `https://` in the $schema string value.
+    //   2. Strip trailing commas before `}` or `]`.
+    //   3. JSON.parse the result.
+    const jsoncText = await Bun.file(resolve(REPO_ROOT, 'opencode.jsonc')).text()
+    const stripped = jsoncText
+      .split('\n')
+      .map(line => (/^\s*\/\//.test(line) ? '' : line))
+      .join('\n')
+      .replaceAll(/,(\s*[}\]])/g, '$1')
+    const opencode = JSON.parse(stripped) as {permission?: Record<string, unknown>}
+
+    // Parse sanity: permission block must be present (catches a broken parse).
+    // opencode permission-checks MCP tool calls via the `permission` map (tool ids
+    // `<server>_<tool>`); we assert the canonical `permission: "deny"` form here.
+    const permission = opencode.permission ?? {}
+    expect(Object.keys(permission).length).toBeGreaterThan(0)
+
+    const violations: string[] = []
+    for (const cmd of SENSITIVE_MCP_COMMANDS) {
+      // (a) Primary gate: the command must NOT be in MCP_ALLOWLIST (source-gated out).
+      //     If someone re-adds it to the allowlist, this catches the regression immediately.
+      if (MCP_ALLOWLIST.has(cmd)) {
+        violations.push(
+          `'${cmd}' is in SENSITIVE_MCP_COMMANDS AND in MCP_ALLOWLIST — source-gate regression: remove it from MCP_ALLOWLIST`,
+        )
+      }
+      // (b) Defense-in-depth backstop: the tool must still be denied in opencode.jsonc.
+      //     This catches the case where MCP_ALLOWLIST is mistakenly re-expanded.
+      //     The infra MCP server converts command names to tool names with underscores,
+      //     and OpenCode prefixes with the server name, giving "infra_<underscored>".
+      const toolId = `infra_${cmd.replaceAll(' ', '_')}`
+      if (permission[toolId] !== 'deny') {
+        violations.push(
+          `${toolId}: not denied in opencode.jsonc permission (found: ${JSON.stringify(permission[toolId])}) — defense-in-depth backstop missing`,
+        )
+      }
+    }
+    expect(
+      violations,
+      `Sensitive infra MCP tools must be source-gated (not in MCP_ALLOWLIST) and denied in opencode.jsonc:\n${violations.join('\n')}`,
+    ).toEqual([])
+  })
 })
 
 // ---------------------------------------------------------------------------