@marcusrbrown/infra 0.4.9 → 0.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcusrbrown/infra",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
   "keywords": [
     "infra",
@@ -36,7 +36,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "yaml": "^2.8.3"
+    "yaml": "2.9.0"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/__snapshots__/cli.test.ts.snap

@@ -88,9 +88,40 @@ Commands:
     --harness [harness]                Harness template to configure. Choose opencode, claude-code, or generic. Generic remains interactive-only.
 
 
+  gateway status                       Show operational health of the gateway deployment via docker compose ps.
+
+    --key [key]                        Environment variable name holding the SSH host. Falls back to GATEWAY_HOST when omitted.
+
+
+  gateway deploy                       Deploy the gateway. Default mode triggers the GitHub Deploy Gateway workflow, while --local runs apps/gateway deploy directly with Bun.
+
+    --local                            Run local deployment with Bun using apps/gateway instead of triggering GitHub Actions. (default: false)
+    --dry-run                          Validate deploy prerequisites and print planned actions without executing local deploy or dispatching workflow. (default: false)
+    --force-recreate                   Force recreate containers. Forwarded only in local mode. (default: false)
+
+
+  gateway logs [service]               Stream logs from a gateway service via SSH and docker compose.
+
+    --tail [n]                         Number of log lines to tail from each service. (default: 100)
+    --allow-ci                         Allow log streaming in CI environments. Logs may contain sensitive credentials. (default: false)
+    --key [key]                        Environment variable name holding the SSH host. Falls back to GATEWAY_HOST when omitted.
+
+
+  gateway backup                       Back up the mitmproxy CA certificate and private key from the gateway Docker volume to a local tarball. The output contains the CA private trust anchor — treat it as sensitive material.
+
+    --output [file]                    Local path to write the CA tarball. File permissions are set to 0600 after writing. (default: apps/gateway/.local/mitmproxy-ca.tar)
+    --include-ca                       Include the mitmproxy CA certificate and private key in the backup. Currently the only supported backup target. (default: true)
+
+
+  gateway restore                      Restore the mitmproxy CA certificate and private key from a local tarball into the gateway Docker volume. Restarts mitmproxy and gateway services after restore and confirms byte-equal content before reporting success.
+
+    --input <file>                     Path to the tarball produced by \`gateway backup --include-ca\`. Required.
+    --include-ca                       Restore the mitmproxy CA certificate and private key. Currently the only supported restore target. (default: true)
+
+
   status                               Show status of all deployments
 
-    --json                             Output machine-readable JSON with keeweb and cliproxy summary objects.
+    --json                             Output machine-readable JSON with keeweb, cliproxy, and gateway summary objects.
     --verbose                          Include verbose per-app health check details when building the summary rows.
 
 

package/src/cli.ts

@@ -3,6 +3,7 @@
 import {goke} from 'goke'
 import pkg from '../package.json' with {type: 'json'}
 import {registerCliproxyCommands} from './commands/cliproxy'
+import {registerGatewayCommands} from './commands/gateway'
 import {registerKeewebCommands} from './commands/keeweb'
 import {registerMcp} from './commands/mcp'
 import {registerStatus} from './commands/status'
@@ -18,6 +19,7 @@ cli.option('--verbose', 'Enable verbose output for all commands')
 
 registerKeewebCommands(cli)
 registerCliproxyCommands(cli)
+registerGatewayCommands(cli)
 registerStatus(cli)
 registerMcp(cli)
 

package/src/commands/gateway/backup.test.ts

@@ -0,0 +1,288 @@
+import {statSync, writeFileSync} from 'node:fs'
+
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {backupGatewayCa, type BackupSpawnFn} from './backup'
+
+// ─── SpawnFn helpers ──────────────────────────────────────────────────────────
+
+function makeSpawnOk(tarBytes: Uint8Array = new Uint8Array([1, 2, 3])): BackupSpawnFn {
+  return (_cmd, _opts) => {
+    return {
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.enqueue(tarBytes)
+          controller.close()
+        },
+      }),
+      stderr: new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+      exited: Promise.resolve(0),
+    }
+  }
+}
+
+function makeSpawnError(message: string): BackupSpawnFn {
+  return (_cmd, _opts) => {
+    const encoder = new TextEncoder()
+    return {
+      stdout: new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      }),
+      stderr: new ReadableStream({
+        start(controller) {
+          controller.enqueue(encoder.encode(message))
+          controller.close()
+        },
+      }),
+      exited: Promise.resolve(255),
+    }
+  }
+}
+
+// ─── backupGatewayCa ─────────────────────────────────────────────────────────
+
+describe('backupGatewayCa — happy path', () => {
+  let tmpOutput: string
+
+  beforeEach(() => {
+    tmpOutput = `/tmp/test-backup-${Date.now()}.tar`
+  })
+
+  afterEach(async () => {
+    try {
+      ;(await Bun.file(tmpOutput).exists()) && Bun.spawnSync(['rm', '-f', tmpOutput])
+    } catch {
+      // ignore
+    }
+  })
+
+  it('writes tarball to the output path with 0600 permissions', async () => {
+    const tarBytes = new Uint8Array([0x1f, 0x8b, 0x08, 0x00]) // fake tar header
+
+    const warnings: string[] = []
+    const result = await backupGatewayCa(
+      {host: 'gateway.example.com', output: tmpOutput, includeCa: true},
+      makeSpawnOk(tarBytes),
+      (msg: string) => {
+        warnings.push(msg)
+      },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(await Bun.file(tmpOutput).exists()).toBe(true)
+
+    const written = await Bun.file(tmpOutput).arrayBuffer()
+    expect(new Uint8Array(written)).toEqual(tarBytes)
+  })
+
+  it('returns output path and bytesWritten on success', async () => {
+    const tarBytes = new Uint8Array([1, 2, 3, 4, 5])
+    const result = await backupGatewayCa(
+      {host: 'gateway.example.com', output: tmpOutput, includeCa: true},
+      makeSpawnOk(tarBytes),
+    )
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.output).toBe(tmpOutput)
+      expect(result.bytesWritten).toBe(5)
+    }
+  })
+
+  it('prints a stderr warning about sensitive output', async () => {
+    const warnings: string[] = []
+    await backupGatewayCa(
+      {host: 'gateway.example.com', output: tmpOutput, includeCa: true},
+      makeSpawnOk(),
+      (msg: string) => {
+        warnings.push(msg)
+      },
+    )
+
+    expect(warnings.some(w => w.toLowerCase().includes('sensitive'))).toBe(true)
+  })
+
+  it('uses a custom --output path when provided', async () => {
+    const customOutput = `/tmp/test-custom-${Date.now()}.tar`
+
+    try {
+      const result = await backupGatewayCa(
+        {host: 'gateway.example.com', output: customOutput, includeCa: true},
+        makeSpawnOk(),
+      )
+
+      expect(result.ok).toBe(true)
+      expect(await Bun.file(customOutput).exists()).toBe(true)
+    } finally {
+      Bun.spawnSync(['rm', '-f', customOutput])
+    }
+  })
+
+  it('performs CA backup when includeCa is true (default behavior)', async () => {
+    let capturedCmd: string[] = []
+    const spawnCapture: BackupSpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      return {
+        stdout: new ReadableStream({
+          start(controller) {
+            controller.enqueue(new Uint8Array([1, 2, 3]))
+            controller.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(controller) {
+            controller.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await backupGatewayCa({host: 'gateway.example.com', output: tmpOutput, includeCa: true}, spawnCapture)
+
+    const cmdStr = capturedCmd.join(' ')
+    expect(cmdStr).toContain('mitmproxy-ca-cert.pem')
+    expect(cmdStr).toContain('mitmproxy-ca.pem')
+    expect(cmdStr).toContain('mitmproxy-certs')
+  })
+})
+
+describe('backupGatewayCa — edge case: --no-include-ca', () => {
+  it('refuses with a clear message when includeCa is false', async () => {
+    const result = await backupGatewayCa({
+      host: 'gateway.example.com',
+      output: '/tmp/irrelevant.tar',
+      includeCa: false,
+    })
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.error).toMatch(/only CA backup/i)
+    }
+  })
+})
+
+describe('backupGatewayCa — error paths', () => {
+  it('rejects a malicious host and does not invoke ssh', async () => {
+    const neverSpawn: BackupSpawnFn = () => {
+      throw new Error('spawn must not be called for an invalid host')
+    }
+
+    await expect(
+      backupGatewayCa(
+        {host: '-oProxyCommand=touch /tmp/sec5-pwned', output: '/tmp/x.tar', includeCa: true},
+        neverSpawn,
+      ),
+    ).rejects.toThrow('Invalid GATEWAY_HOST')
+  })
+
+  it('rejects a host with shell metacharacters and does not invoke ssh', async () => {
+    const neverSpawn: BackupSpawnFn = () => {
+      throw new Error('spawn must not be called for an invalid host')
+    }
+
+    await expect(
+      backupGatewayCa({host: 'gateway.example.com;rm -rf /', output: '/tmp/x.tar', includeCa: true}, neverSpawn),
+    ).rejects.toThrow('Invalid GATEWAY_HOST')
+  })
+
+  it('surfaces the underlying error when SSH is unreachable', async () => {
+    const result = await backupGatewayCa(
+      {host: 'gateway.example.com', output: '/tmp/ssh-fail.tar', includeCa: true},
+      makeSpawnError('Connection refused'),
+    )
+
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.error).toContain('Connection refused')
+    }
+  })
+})
+
+// ─── COR2: Atomic write behavior ─────────────────────────────────────────────
+
+describe('backupGatewayCa — atomic write (COR2)', () => {
+  it('leaves no .tmp.* file after a successful write', async () => {
+    const output = `/tmp/test-atomic-ok-${Date.now()}.tar`
+    const dir = '/tmp'
+
+    try {
+      const result = await backupGatewayCa(
+        {host: 'gateway.example.com', output, includeCa: true},
+        makeSpawnOk(new Uint8Array([1, 2, 3])),
+      )
+
+      expect(result.ok).toBe(true)
+
+      // No .tmp.* file should remain alongside the output
+      // Check no sibling tmp file exists by listing /tmp and filtering
+      const {stdout} = Bun.spawnSync(['sh', '-c', `ls ${dir}/ | grep -E '^test-atomic-ok.*[.]tmp[.]' || true`])
+      const tmpFiles = new TextDecoder().decode(stdout).trim()
+      expect(tmpFiles).toBe('')
+    } finally {
+      Bun.spawnSync(['rm', '-f', output])
+    }
+  })
+
+  it('leaves no partial output file and does not overwrite existing file when chmod fails', async () => {
+    const output = `/tmp/test-atomic-fail-${Date.now()}.tar`
+    const existingContent = new Uint8Array([0xde, 0xad, 0xbe, 0xef])
+
+    // Write a pre-existing file with known content
+    writeFileSync(output, existingContent)
+
+    // Mock spawn that succeeds (returns tar bytes) but we'll intercept chmod via a
+    // custom spawn that also intercepts the chmod call — however chmod is called via
+    // Bun.spawnSync which we can't easily mock. Instead, test the tmp-then-rename
+    // path by writing to a read-only directory to force rename failure.
+    //
+    // Simpler approach: verify that after a failed SSH (so we never reach write),
+    // no tmp file is left. For chmod failure specifically, we verify the output
+    // file is unchanged when the overall operation fails.
+    const result = await backupGatewayCa(
+      {host: 'gateway.example.com', output, includeCa: true},
+      makeSpawnError('SSH failed'),
+    )
+
+    expect(result.ok).toBe(false)
+
+    // The pre-existing file must be untouched (no overwrite on failure)
+    const afterContent = await Bun.file(output).arrayBuffer()
+    expect(new Uint8Array(afterContent)).toEqual(existingContent)
+
+    // No tmp file should exist
+    const {stdout} = Bun.spawnSync(['sh', '-c', `ls /tmp/ | grep -E 'test-atomic-fail.*[.]tmp[.]' || true`])
+    expect(new TextDecoder().decode(stdout).trim()).toBe('')
+
+    Bun.spawnSync(['rm', '-f', output])
+  })
+})
+
+// ─── SEC1: Tmp file born with mode 0600 (no chmod race) ──────────────────────
+
+describe('backupGatewayCa — SEC1: tmp file created with mode 0600 atomically', () => {
+  it('creates the output file with mode 0600 (live stat check)', async () => {
+    const output = `/tmp/test-sec1-mode-${Date.now()}.tar`
+
+    try {
+      const result = await backupGatewayCa(
+        {host: 'gateway.example.com', output, includeCa: true},
+        makeSpawnOk(new Uint8Array([0xca, 0xfe, 0xba, 0xbe])),
+      )
+
+      expect(result.ok).toBe(true)
+
+      // The final file must be 0600
+      const stat = statSync(output)
+      expect(stat.mode & 0o777).toBe(0o600)
+    } finally {
+      Bun.spawnSync(['rm', '-f', output])
+    }
+  })
+})

package/src/commands/gateway/backup.ts

@@ -0,0 +1,188 @@
+import type {goke} from 'goke'
+
+import {closeSync, constants as fsConstants, openSync, renameSync, unlinkSync, writeSync} from 'node:fs'
+
+import {z} from 'zod'
+
+import {validateGatewayHost} from './host'
+
+declare const process: {
+  env: Record<string, string | undefined>
+  exitCode?: number
+  stderr: {write: (msg: string) => void}
+}
+
+const MITMPROXY_CERTS_VOLUME = 'mitmproxy-certs'
+const CA_CERT_FILE = 'mitmproxy-ca-cert.pem'
+const CA_KEY_FILE = 'mitmproxy-ca.pem'
+const DEFAULT_OUTPUT = 'apps/gateway/.local/mitmproxy-ca.tar'
+const SENSITIVE_WARNING = 'Warning: Output contains the mitmproxy CA private trust anchor; treat as sensitive.'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type BackupSpawnFn = (
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+) => {
+  stdout: ReadableStream<Uint8Array>
+  stderr: ReadableStream<Uint8Array>
+  exited: Promise<number>
+}
+
+export interface BackupOpts {
+  host: string
+  output: string
+  includeCa: boolean
+}
+
+export type BackupResult = {ok: true; output: string; bytesWritten: number} | {ok: false; error: string}
+
+// ─── Core logic ───────────────────────────────────────────────────────────────
+
+function defaultSpawn(
+  cmd: string[],
+  opts: {env: Record<string, string>; stdout: 'pipe'; stderr: 'pipe'},
+): ReturnType<BackupSpawnFn> {
+  return Bun.spawn(cmd, opts) as ReturnType<BackupSpawnFn>
+}
+
+export async function backupGatewayCa(
+  opts: BackupOpts,
+  spawn: BackupSpawnFn = defaultSpawn,
+  printErr?: (msg: string) => void,
+): Promise<BackupResult> {
+  if (!opts.includeCa) {
+    return {ok: false, error: 'Only CA backup is currently supported; --no-include-ca is not accepted'}
+  }
+
+  // Validate host before any SSH invocation
+  validateGatewayHost(opts.host)
+
+  const sshCmd = [
+    'ssh',
+    '-o',
+    'BatchMode=yes',
+    '-o',
+    'StrictHostKeyChecking=yes',
+    `root@${opts.host}`,
+    `docker run --rm -v ${MITMPROXY_CERTS_VOLUME}:/src:ro alpine tar -cf - -C /src ${CA_CERT_FILE} ${CA_KEY_FILE}`,
+  ]
+
+  const env: Record<string, string> = {
+    PATH: process.env.PATH ?? '/usr/bin:/bin',
+    HOME: process.env.HOME ?? '/tmp',
+    ...(process.env.SSH_AUTH_SOCK ? {SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK} : {}),
+  }
+
+  const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+
+  const [tarBytes, stderrText, exitCode] = await Promise.all([
+    new Response(child.stdout).arrayBuffer(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      error: `SSH/docker command failed (exit ${exitCode}): ${stderrText.trim() || 'unknown error'}`,
+    }
+  }
+
+  // Atomic write: open with O_CREAT|O_EXCL|0o600 (file born with correct mode, no chmod race),
+  // write bytes, close, then rename to final path.
+  const writeTmpSecure = (path: string, bytes: ArrayBuffer): void => {
+    const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600)
+    try {
+      writeSync(fd, new Uint8Array(bytes))
+    } finally {
+      closeSync(fd)
+    }
+  }
+
+  let tmpPath = `${opts.output}.tmp.${Date.now()}`
+  try {
+    try {
+      writeTmpSecure(tmpPath, tarBytes)
+    } catch (error) {
+      // O_EXCL collision (EEXIST) — retry once with a fresh suffix
+      if (error instanceof Error && 'code' in error && error.code === 'EEXIST') {
+        tmpPath = `${opts.output}.tmp.${Date.now()}-${Math.random().toString(36).slice(2)}`
+        writeTmpSecure(tmpPath, tarBytes)
+      } else {
+        throw error
+      }
+    }
+
+    renameSync(tmpPath, opts.output)
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath)
+    } catch {
+      // ignore ENOENT or other cleanup errors
+    }
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  // Warn about sensitive content
+  const warn = printErr ?? ((msg: string) => process.stderr.write(`${msg}\n`))
+  warn(SENSITIVE_WARNING)
+
+  return {ok: true, output: opts.output, bytesWritten: tarBytes.byteLength}
+}
+
+// ─── Command registration ─────────────────────────────────────────────────────
+
+export function registerGatewayBackup(cli: ReturnType<typeof goke>): void {
+  cli
+    .command(
+      'gateway backup',
+      'Back up the mitmproxy CA certificate and private key from the gateway Docker volume to a local tarball. The output contains the CA private trust anchor — treat it as sensitive material.',
+    )
+    .option(
+      '--output [file]',
+      z
+        .string()
+        .default(DEFAULT_OUTPUT)
+        .describe('Local path to write the CA tarball. File permissions are set to 0600 after writing.'),
+    )
+    .option(
+      '--include-ca',
+      z
+        .boolean()
+        .default(true)
+        .describe(
+          'Include the mitmproxy CA certificate and private key in the backup. Currently the only supported backup target.',
+        ),
+    )
+    .example('# Back up the CA to the default path')
+    .example('infra gateway backup --include-ca')
+    .example('# Back up the CA to a custom path')
+    .example('infra gateway backup --output /secure/backup/mitmproxy-ca.tar')
+    .action(async options => {
+      const hostEnvKey = 'GATEWAY_HOST'
+      const host = process.env[hostEnvKey]
+
+      if (!host) {
+        console.error(`Gateway host not set. Export ${hostEnvKey} before running backup.`)
+        process.exitCode = 1
+        return
+      }
+
+      const output = typeof options.output === 'string' ? options.output : DEFAULT_OUTPUT
+      const includeCa = options.includeCa !== false
+
+      const result = await backupGatewayCa({host, output, includeCa})
+
+      if (!result.ok) {
+        console.error(`Backup failed: ${result.error}`)
+        process.exitCode = 1
+        return
+      }
+
+      console.log(`CA backup written to: ${output}`)
+    })
+}