@gemus/mcp-proxy 0.1.6 → 0.1.8

package/src/__tests__/startup.test.ts

@@ -0,0 +1,558 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  assertGemusKey,
+  createFatalReporter,
+  safeEndpointLabel,
+  sanitizeStartupError,
+  startProxy,
+} from '../startup.mjs'
+
+const PROXY_PATH = path.resolve(
+  process.cwd(),
+  'packages/gemus-mcp-proxy/src/proxy.mjs',
+)
+const PROXY_RUNTIME_LOADER_PATH = path.resolve(
+  process.cwd(),
+  'packages/gemus-mcp-proxy/src/__tests__/fixtures/proxy-runtime-loader.mjs',
+)
+const PROXY_RUNTIME_LOADER_URL = pathToFileURL(PROXY_RUNTIME_LOADER_PATH).href
+
+async function readFileOrEmpty(file: string) {
+  try {
+    return await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return ''
+    throw error
+  }
+}
+
+async function runProxy(
+  envOverrides: NodeJS.ProcessEnv,
+  {
+    closeStdinAfterMs = 600,
+    input,
+  }: {
+    closeStdinAfterMs?: number
+    input?: Record<string, unknown>
+  } = {},
+) {
+  const env = { ...process.env, ...envOverrides }
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) delete env[key]
+  }
+
+  return await new Promise<{
+    code: number | null
+    signal: NodeJS.Signals | null
+    stdout: string
+    stderr: string
+  }>((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      ['--no-warnings', '--experimental-loader', PROXY_RUNTIME_LOADER_URL, PROXY_PATH],
+      {
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    )
+    let stdout = ''
+    let stderr = ''
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => { stdout += chunk })
+    child.stderr.on('data', (chunk) => { stderr += chunk })
+    child.on('error', reject)
+    if (input) child.stdin.write(`${JSON.stringify(input)}\n`)
+
+    const closeTimer = setTimeout(() => child.stdin.end(), closeStdinAfterMs)
+    const killTimer = setTimeout(() => child.kill(), 5_000)
+    child.on('close', (code, signal) => {
+      clearTimeout(closeTimer)
+      clearTimeout(killTimer)
+      resolve({ code, signal, stdout, stderr })
+    })
+  })
+}
+
+describe('assertGemusKey', () => {
+  it('rejects a missing GEMUS_KEY with actionable restart guidance', () => {
+    expect(() => assertGemusKey('')).toThrow(
+      'GEMUS_KEY is required. Set it in your user environment and restart Codex.',
+    )
+  })
+})
+
+describe('sanitizeStartupError', () => {
+  it('keeps the missing-key diagnostic readable when the configured secret is empty', () => {
+    expect(
+      sanitizeStartupError(
+        new Error('GEMUS_KEY is required. Set it in your user environment and restart Codex.'),
+        { secret: '' },
+      ),
+    ).toBe(
+      'Gemus MCP proxy failed to start: GEMUS_KEY is required. Set it in your user environment and restart Codex.',
+    )
+  })
+
+  it('redacts the exact configured secret regardless of its shape', () => {
+    const secret = 'arbitrary-secret-without-known-prefix'
+    const output = sanitizeStartupError(new Error(`upstream rejected ${secret}`), { secret })
+
+    expect(output).toBe('Gemus MCP proxy failed to start: upstream rejected [REDACTED]')
+    expect(output).not.toContain(secret)
+  })
+
+  it.each([
+    ['mak_ token', 'request rejected mak_AbC123-._~+/=', 'request rejected [REDACTED]'],
+    ['Bearer token', 'Authorization: Bearer opaque-token', 'Authorization: Bearer [REDACTED]'],
+    ['authorization header', 'Authorization: opaque-token', 'Authorization: [REDACTED]'],
+    ['API key header', 'X-API-Key=opaque-token', 'X-API-Key=[REDACTED]'],
+  ])('redacts a %s while preserving non-sensitive context', (_label, input, expected) => {
+    const output = sanitizeStartupError(new Error(input), { secret: 'different-secret' })
+
+    expect(output).toBe(`Gemus MCP proxy failed to start: ${expected}`)
+    expect(output).toContain('request rejected'.includes(expected) ? 'request rejected' : expected.split(/[:=]/)[0])
+  })
+
+  it('removes URL userinfo, query, and fragment without hiding the safe endpoint context', () => {
+    const output = sanitizeStartupError(
+      new Error(
+        'connect ECONNREFUSED https://alice:p%40ss@example.test/api/mcp?token=query-secret#fragment-secret',
+      ),
+      { secret: 'unrelated-secret' },
+    )
+
+    expect(output).toBe(
+      'Gemus MCP proxy failed to start: connect ECONNREFUSED https://example.test/api/mcp',
+    )
+    expect(output).not.toMatch(/alice|p%40ss|query-secret|fragment-secret/)
+  })
+
+  it.each(['ftp', 'ws'])(
+    'sanitizes a credential-bearing %s URL while preserving its safe endpoint',
+    (scheme) => {
+      const output = sanitizeStartupError(
+        new Error(
+          `connect failed ${scheme}://alice:password@example.test/api/mcp?token=query-secret#fragment-secret`,
+        ),
+        { secret: 'unrelated-secret' },
+      )
+
+      expect(output).toBe(
+        `Gemus MCP proxy failed to start: connect failed ${scheme}://example.test/api/mcp`,
+      )
+      expect(output).not.toMatch(
+        /alice|password|query-secret|fragment-secret/,
+      )
+    },
+  )
+
+  it.each([
+    [
+      'quoted authorization',
+      'request failed Authorization: "Basic opaque credential" status=401',
+      'request failed Authorization: "Basic [REDACTED]" status=401',
+    ],
+    [
+      'JSON authorization',
+      'request failed {"authorization":"Bearer opaque-token"} status=401',
+      'request failed {"authorization":"Bearer [REDACTED]"} status=401',
+    ],
+    [
+      'quoted API key',
+      "request failed X-API-Key='opaque credential' status=401",
+      "request failed X-API-Key='[REDACTED]' status=401",
+    ],
+  ])('redacts %s values without consuming adjacent context', (_label, input, expected) => {
+    expect(sanitizeStartupError(new Error(input), { secret: '' })).toBe(
+      `Gemus MCP proxy failed to start: ${expected}`,
+    )
+  })
+})
+
+describe('safeEndpointLabel', () => {
+  it('returns only URL origin and path', () => {
+    expect(
+      safeEndpointLabel(
+        'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+      ),
+    ).toBe('https://example.test/api/mcp')
+  })
+})
+
+describe('createFatalReporter', () => {
+  it('writes one synchronous diagnostic when optional logging throws or fatal repeats', () => {
+    const writeStderr = vi.fn()
+    const writeLog = vi.fn(() => { throw new Error('unwritable log') })
+    const reportFatal = createFatalReporter({
+      secret: 'exact-secret',
+      writeStderr,
+      writeLog,
+    })
+
+    reportFatal(new Error('first failure exact-secret'))
+    reportFatal(new Error('second failure exact-secret'))
+
+    expect(writeStderr).toHaveBeenCalledTimes(1)
+    expect(writeStderr).toHaveBeenCalledWith(
+      'Gemus MCP proxy failed to start: first failure [REDACTED]\n',
+    )
+    expect(writeLog).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('startProxy', () => {
+  it('starts upstream before stdio and invokes the success callback last', async () => {
+    const events: string[] = []
+    const upstream = { start: vi.fn(async () => { events.push('upstream') }) }
+    const stdio = { start: vi.fn(async () => { events.push('stdio') }) }
+
+    await startProxy({
+      key: 'configured',
+      upstream,
+      stdio,
+      onStarted: () => { events.push('started') },
+    })
+
+    expect(events).toEqual(['upstream', 'stdio', 'started'])
+  })
+
+  it('does not construct startup work when GEMUS_KEY is missing', async () => {
+    const upstream = { start: vi.fn() }
+    const stdio = { start: vi.fn() }
+
+    await expect(
+      startProxy({ key: '', upstream, stdio, onStarted: vi.fn() }),
+    ).rejects.toThrow('GEMUS_KEY is required')
+    expect(upstream.start).not.toHaveBeenCalled()
+    expect(stdio.start).not.toHaveBeenCalled()
+  })
+
+  it('propagates an upstream startup error without starting stdio', async () => {
+    const error = new Error('upstream failed')
+    const upstream = { start: vi.fn().mockRejectedValue(error) }
+    const stdio = { start: vi.fn() }
+
+    await expect(
+      startProxy({ key: 'configured', upstream, stdio, onStarted: vi.fn() }),
+    ).rejects.toBe(error)
+    expect(stdio.start).not.toHaveBeenCalled()
+  })
+
+  it('propagates a stdio startup error without invoking the success callback', async () => {
+    const error = new Error('stdio failed')
+    const upstream = { start: vi.fn().mockResolvedValue(undefined) }
+    const stdio = { start: vi.fn().mockRejectedValue(error) }
+    const onStarted = vi.fn()
+
+    await expect(
+      startProxy({ key: 'configured', upstream, stdio, onStarted }),
+    ).rejects.toBe(error)
+    expect(onStarted).not.toHaveBeenCalled()
+  })
+})
+
+describe('createShutdownCoordinator', () => {
+  it('runs cleanup once and preserves a fatal exit requested during graceful close', async () => {
+    let releaseCleanup!: () => void
+    const cleanup = vi.fn(() => new Promise<void>((resolve) => {
+      releaseCleanup = resolve
+    }))
+    const exit = vi.fn()
+    const startup = await import('../startup.mjs') as typeof import('../startup.mjs') & {
+      createShutdownCoordinator?: (options: {
+        cleanup: () => Promise<void>
+        exit: (code: number) => void
+      }) => (code?: number) => Promise<void>
+    }
+
+    expect(startup.createShutdownCoordinator).toBeTypeOf('function')
+    const shutdown = startup.createShutdownCoordinator!({ cleanup, exit })
+    const graceful = shutdown(0)
+    const fatal = shutdown(1)
+
+    expect(cleanup).toHaveBeenCalledTimes(1)
+    expect(exit).not.toHaveBeenCalled()
+    releaseCleanup()
+    await Promise.all([graceful, fatal])
+
+    expect(exit).toHaveBeenCalledTimes(1)
+    expect(exit).toHaveBeenCalledWith(1)
+  })
+})
+
+describe('proxy process startup', () => {
+  it('fails before runtime construction when GEMUS_KEY is missing', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-startup-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: undefined,
+        GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: logPath,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+      })
+      const log = await readFileOrEmpty(logPath)
+      const constructionLog = await readFileOrEmpty(constructionLogPath)
+      const lines = log.trim().split(/\r?\n/)
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stdout).toBe('')
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: GEMUS_KEY is required. Set it in your user environment and restart Codex.\n',
+      )
+      expect(lines).toHaveLength(1)
+      expect(lines[0]).toContain('GEMUS_KEY is required')
+      expect(log).not.toMatch(/HOOK-SERVER|STARTED|alice|password|query-secret|fragment-secret/)
+      expect(constructionLog).toBe('')
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('logs a successful endpoint using only origin and path', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-started-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'configured-key',
+        GEMUS_URL: 'http://alice:password@127.0.0.1:1/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: logPath,
+      })
+      const log = await readFile(logPath, 'utf8')
+      const started = log.split(/\r?\n/).find((line) => line.includes('STARTED'))
+
+      expect(result.code).toBe(0)
+      expect(started).toContain('http://127.0.0.1:1/api/mcp')
+      expect(started).not.toMatch(/alice|password|query-secret|fragment-secret|userinfo|search|hash/)
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps exit code 1 when stdio onclose races with a startup error', async () => {
+    const secret = 'arbitrary-secret'
+    const result = await runProxy({
+      GEMUS_KEY: secret,
+      GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+      PROXY_LOG: undefined,
+      PROXY_TEST_STDIO_START_FAILURE: '1',
+    })
+
+    expect(result.code).toBe(1)
+    expect(result.signal).toBeNull()
+    expect(result.stderr).toContain('Gemus MCP proxy failed to start: stdio failed')
+    expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+    expect(result.stderr).toContain('https://example.test/api/mcp')
+    expect(result.stderr).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+    )
+  })
+
+  it('exits non-zero when the first upstream initialize send fails', async () => {
+    const secret = 'arbitrary-secret'
+    const result = await runProxy(
+      {
+        GEMUS_KEY: secret,
+        GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: undefined,
+        PROXY_TEST_FORWARD_STDIN: '1',
+        PROXY_TEST_UPSTREAM_INITIALIZE_FAILURE: '1',
+      },
+      {
+        input: {
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2025-06-18',
+            capabilities: {},
+            clientInfo: { name: 'startup-test', version: '1.0.0' },
+          },
+        },
+      },
+    )
+
+    expect(result.code).toBe(1)
+    expect(result.signal).toBeNull()
+    expect(result.stderr).toBe(
+      'Gemus MCP proxy failed to start: initialize fetch failed Authorization: Bearer [REDACTED] at https://example.test/api/mcp\n',
+    )
+    expect(result.stderr).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+    )
+  })
+
+  it.each(['ftp', 'ws'])(
+    'sanitizes a credential-bearing %s endpoint in a real initialize failure',
+    async (scheme) => {
+      const secret = 'arbitrary-secret'
+      const endpoint = `${scheme}://alice:password@example.test/api/mcp?token=query-secret#fragment-secret`
+      const result = await runProxy(
+        {
+          GEMUS_KEY: secret,
+          GEMUS_URL: endpoint,
+          PROXY_LOG: undefined,
+          PROXY_TEST_FORWARD_STDIN: '1',
+          PROXY_TEST_UPSTREAM_INITIALIZE_FAILURE: '1',
+        },
+        {
+          input: {
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+              protocolVersion: '2025-06-18',
+              capabilities: {},
+              clientInfo: { name: 'startup-test', version: '1.0.0' },
+            },
+          },
+        },
+      )
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        `Gemus MCP proxy failed to start: initialize fetch failed Authorization: Bearer [REDACTED] at ${scheme}://example.test/api/mcp\n`,
+      )
+      expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+      expect(result.stderr).not.toContain(endpoint)
+      expect(result.stderr).not.toMatch(
+        /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+      )
+    },
+  )
+
+  it('routes an asynchronous hook listen error through one sanitized fatal shutdown', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-hook-listen-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    const secret = 'arbitrary-secret'
+    const endpoint =
+      'ws://alice:password@example.test/api/mcp?token=query-secret#fragment-secret'
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: secret,
+        GEMUS_URL: endpoint,
+        PROXY_LOG: logPath,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+        PROXY_TEST_HOOK_LISTEN_FAILURE: '1',
+      })
+      const log = await readFileOrEmpty(logPath)
+      const constructionLog = await readFileOrEmpty(constructionLogPath)
+      const fatalLines = log
+        .split(/\r?\n/)
+        .filter((line) => line.includes(' FATAL '))
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: hook listen failed Authorization: Bearer [REDACTED] at ws://example.test/api/mcp\n',
+      )
+      expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+      expect(fatalLines).toHaveLength(1)
+      expect(log).not.toContain('STARTED')
+      expect(constructionLog.match(/hook-server-close/g)).toHaveLength(1)
+      for (const output of [result.stderr, log]) {
+        expect(output).not.toContain(endpoint)
+        expect(output).not.toMatch(
+          /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+        )
+      }
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('ignores a hook error emitted after graceful shutdown begins', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-hook-close-'))
+    const logPath = path.join(tempRoot, 'proxy.log')
+    const constructionLogPath = path.join(tempRoot, 'construction.log')
+    const endpoint =
+      'ws://alice:password@example.test/api/mcp?token=query-secret#fragment-secret'
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'arbitrary-secret',
+        GEMUS_URL: endpoint,
+        PROXY_LOG: logPath,
+        PROXY_TEST_CONSTRUCTION_LOG: constructionLogPath,
+        PROXY_TEST_HOOK_ERROR_AFTER_CLOSE: '1',
+      })
+      const log = await readFileOrEmpty(logPath)
+      const constructionLog = await readFileOrEmpty(constructionLogPath)
+
+      expect(result.code).toBe(0)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe('')
+      expect(log).not.toContain(' FATAL ')
+      expect(log).not.toContain(endpoint)
+      expect(log).not.toMatch(
+        /arbitrary-secret|alice|password|query-secret|fragment-secret/,
+      )
+      expect(constructionLog.match(/hook-server-close/g)).toHaveLength(1)
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('sanitizes a synchronous construction failure outside transport start', async () => {
+    const result = await runProxy({
+      GEMUS_KEY: 'arbitrary-secret',
+      GEMUS_URL: 'https://alice:password@[broken/api/mcp?token=query-secret#fragment-secret',
+      PROXY_LOG: undefined,
+    })
+
+    expect(result.code).toBe(1)
+    expect(result.signal).toBeNull()
+    expect(result.stderr).toBe('Gemus MCP proxy failed to start: Invalid URL\n')
+    expect(result.stderr.trim().split(/\r?\n/)).toHaveLength(1)
+    expect(result.stderr).not.toMatch(
+      /arbitrary-secret|alice|password|query-secret|fragment-secret|ERR_INVALID_URL/,
+    )
+  })
+
+  it('keeps the missing-key diagnostic singular when PROXY_LOG is unwritable', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-unwritable-log-'))
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: undefined,
+        PROXY_LOG: tempRoot,
+      })
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: GEMUS_KEY is required. Set it in your user environment and restart Codex.\n',
+      )
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps a later startup diagnostic singular when PROXY_LOG is unwritable', async () => {
+    const tempRoot = await mkdtemp(path.join(tmpdir(), 'gemus-proxy-unwritable-log-'))
+    try {
+      const result = await runProxy({
+        GEMUS_KEY: 'arbitrary-secret',
+        GEMUS_URL: 'https://alice:password@example.test/api/mcp?token=query-secret#fragment-secret',
+        PROXY_LOG: tempRoot,
+        PROXY_TEST_STDIO_START_FAILURE: '1',
+      })
+
+      expect(result.code).toBe(1)
+      expect(result.signal).toBeNull()
+      expect(result.stderr).toBe(
+        'Gemus MCP proxy failed to start: stdio failed Authorization: Bearer [REDACTED] at https://example.test/api/mcp\n',
+      )
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true })
+    }
+  })
+})