@marcusrbrown/infra 0.10.3 → 0.10.5

package/package.json

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

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

@@ -613,3 +613,143 @@ describe('getGatewayComposeStatus — SSH error redaction', () => {
     expect(result.error).not.toContain(secretHost.toLowerCase())
   })
 })
+
+// ─── SSH identity injection (GATEWAY_SSH_KEY) ─────────────────────────────────
+
+describe('getGatewayComposeStatus — SSH identity injection', () => {
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    originalEnv = {GATEWAY_SSH_KEY: process.env.GATEWAY_SSH_KEY}
+  })
+
+  afterEach(() => {
+    if (originalEnv.GATEWAY_SSH_KEY === undefined) {
+      delete process.env.GATEWAY_SSH_KEY
+    } else {
+      process.env.GATEWAY_SSH_KEY = originalEnv.GATEWAY_SSH_KEY
+    }
+  })
+
+  it('includes -i <path> and IdentitiesOnly=yes in ssh argv when GATEWAY_SSH_KEY is set', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+    process.env.GATEWAY_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    let capturedCmd: string[] = []
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(JSON.stringify([{Name: 'gateway', State: 'running', Health: 'healthy'}])))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getGatewayComposeStatus('gateway.example.com', capturingSpawn)
+
+    const iIdx = capturedCmd.indexOf('-i')
+    expect(iIdx).toBeGreaterThan(-1)
+    expect(capturedCmd[iIdx + 1]).toBeTruthy() // path to temp key file
+
+    const identitiesOnlyIdx = capturedCmd.indexOf('IdentitiesOnly=yes')
+    expect(identitiesOnlyIdx).toBeGreaterThan(-1)
+
+    const destination = capturedCmd.find(arg => arg.includes('@'))
+    expect(destination).toBe('root@gateway.example.com')
+  })
+
+  it('does not include -i or IdentitiesOnly=yes when GATEWAY_SSH_KEY is absent', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+    delete process.env.GATEWAY_SSH_KEY
+
+    let capturedCmd: string[] = []
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(JSON.stringify([{Name: 'gateway', State: 'running', Health: 'healthy'}])))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getGatewayComposeStatus('gateway.example.com', capturingSpawn)
+
+    expect(capturedCmd.indexOf('-i')).toBe(-1)
+    expect(capturedCmd.indexOf('IdentitiesOnly=yes')).toBe(-1)
+  })
+
+  it('cleans up the temp key file after the SSH command completes', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+    const {statSync} = await import('node:fs')
+    process.env.GATEWAY_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    let capturedKeyPath: string | undefined
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      const iIdx = cmd.indexOf('-i')
+      if (iIdx !== -1) capturedKeyPath = cmd[iIdx + 1]
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(JSON.stringify([{Name: 'gateway', State: 'running', Health: 'healthy'}])))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getGatewayComposeStatus('gateway.example.com', capturingSpawn)
+
+    expect(capturedKeyPath).toBeTruthy()
+    const keyPath = capturedKeyPath
+    if (keyPath) {
+      expect(() => statSync(keyPath)).toThrow()
+    }
+  })
+
+  it('cleans up the temp key dir even when spawn throws synchronously', async () => {
+    const {getGatewayComposeStatus} = await import('./status')
+    const {statSync} = await import('node:fs')
+    process.env.GATEWAY_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    let capturedKeyPath: string | undefined
+    const throwingSpawn: SpawnFn = (cmd, _opts) => {
+      const iIdx = cmd.indexOf('-i')
+      if (iIdx !== -1) capturedKeyPath = cmd[iIdx + 1]
+      throw new Error('spawn failed')
+    }
+
+    await expect(getGatewayComposeStatus('gateway.example.com', throwingSpawn)).rejects.toThrow('spawn failed')
+
+    expect(capturedKeyPath).toBeTruthy()
+    if (capturedKeyPath) {
+      expect(() => statSync(capturedKeyPath as string)).toThrow()
+    }
+  })
+})

package/src/commands/gateway/status.ts

@@ -5,6 +5,7 @@ import {z} from 'zod'
 
 import {buildKnownHostsArgs} from '../../lib/known-hosts'
 import {redactHost} from '../../lib/redact'
+import {buildIdentityArgs} from '../../lib/ssh-identity'
 // ─── Minimal ctx interface (subset of GokeExecutionContext used by this action) ─
 import {validateGatewayHost} from './host'
 
@@ -103,13 +104,17 @@ export async function getGatewayComposeStatus(
 ): Promise<GatewayStatusResult> {
   validateGatewayHost(host)
 
+  const knownHostsArgs = buildKnownHostsArgs()
+  const {args: identityArgs, cleanup} = buildIdentityArgs(process.env.GATEWAY_SSH_KEY)
+
   const sshCmd = [
     'ssh',
     '-o',
     'BatchMode=yes',
     '-o',
     'StrictHostKeyChecking=yes',
-    ...buildKnownHostsArgs(),
+    ...knownHostsArgs,
+    ...identityArgs,
     `root@${host}`,
     `docker compose --project-directory ${COMPOSE_PROJECT_DIR} ps --format json`,
   ]
@@ -120,13 +125,20 @@ export async function getGatewayComposeStatus(
     ...(process.env.SSH_AUTH_SOCK ? {SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK} : {}),
   }
 
-  const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+  let stdoutText: string
+  let stderrText: string
+  let exitCode: number
 
-  const [stdoutText, stderrText, exitCode] = await Promise.all([
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-    child.exited,
-  ])
+  try {
+    const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+    ;[stdoutText, stderrText, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+  } finally {
+    cleanup()
+  }
 
   if (exitCode !== 0) {
     const redacted = redactHost(stderrText.trim(), host) || 'unknown error'

package/src/commands/umami/status.test.ts

@@ -514,3 +514,120 @@ describe('getUmamiComposeStatus — SSH error redaction', () => {
     expect(result.error).not.toContain(secretHost.toLowerCase())
   })
 })
+
+// ─── SSH identity injection (UMAMI_SSH_KEY) ───────────────────────────────────
+
+describe('getUmamiComposeStatus — SSH identity injection', () => {
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    originalEnv = {UMAMI_SSH_KEY: process.env.UMAMI_SSH_KEY}
+  })
+
+  afterEach(() => {
+    if (originalEnv.UMAMI_SSH_KEY === undefined) {
+      delete process.env.UMAMI_SSH_KEY
+    } else {
+      process.env.UMAMI_SSH_KEY = originalEnv.UMAMI_SSH_KEY
+    }
+  })
+
+  it('includes -i <path> and IdentitiesOnly=yes in ssh argv when UMAMI_SSH_KEY is set', async () => {
+    process.env.UMAMI_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    let capturedCmd: string[] = []
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(JSON.stringify([{Name: 'umami', State: 'running', Health: 'healthy'}])))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getUmamiComposeStatus('metrics.fro.bot', capturingSpawn)
+
+    const iIdx = capturedCmd.indexOf('-i')
+    expect(iIdx).toBeGreaterThan(-1)
+    expect(capturedCmd[iIdx + 1]).toBeTruthy()
+
+    const identitiesOnlyIdx = capturedCmd.indexOf('IdentitiesOnly=yes')
+    expect(identitiesOnlyIdx).toBeGreaterThan(-1)
+
+    const destination = capturedCmd.find(arg => arg.includes('@'))
+    expect(destination).toBe('root@metrics.fro.bot')
+  })
+
+  it('does not include -i or IdentitiesOnly=yes when UMAMI_SSH_KEY is absent', async () => {
+    delete process.env.UMAMI_SSH_KEY
+
+    let capturedCmd: string[] = []
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(JSON.stringify([{Name: 'umami', State: 'running', Health: 'healthy'}])))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getUmamiComposeStatus('metrics.fro.bot', capturingSpawn)
+
+    expect(capturedCmd.indexOf('-i')).toBe(-1)
+    expect(capturedCmd.indexOf('IdentitiesOnly=yes')).toBe(-1)
+  })
+
+  it('cleans up the temp key file after the SSH command completes', async () => {
+    const {statSync} = await import('node:fs')
+    process.env.UMAMI_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    let capturedKeyPath: string | undefined
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      const iIdx = cmd.indexOf('-i')
+      if (iIdx !== -1) capturedKeyPath = cmd[iIdx + 1]
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(JSON.stringify([{Name: 'umami', State: 'running', Health: 'healthy'}])))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getUmamiComposeStatus('metrics.fro.bot', capturingSpawn)
+
+    expect(capturedKeyPath).toBeTruthy()
+    const keyPath = capturedKeyPath
+    if (keyPath) {
+      expect(() => statSync(keyPath)).toThrow()
+    }
+  })
+})

package/src/commands/umami/status.ts

@@ -5,6 +5,7 @@ import {z} from 'zod'
 
 import {buildKnownHostsArgs} from '../../lib/known-hosts'
 import {redactHost} from '../../lib/redact'
+import {buildIdentityArgs} from '../../lib/ssh-identity'
 import {validateUmamiHost} from './host'
 
 declare const process: {
@@ -97,13 +98,17 @@ function defaultSpawn(
 export async function getUmamiComposeStatus(host: string, spawn: SpawnFn = defaultSpawn): Promise<UmamiStatusResult> {
   validateUmamiHost(host)
 
+  const knownHostsArgs = buildKnownHostsArgs()
+  const {args: identityArgs, cleanup} = buildIdentityArgs(process.env.UMAMI_SSH_KEY)
+
   const sshCmd = [
     'ssh',
     '-o',
     'BatchMode=yes',
     '-o',
     'StrictHostKeyChecking=yes',
-    ...buildKnownHostsArgs(),
+    ...knownHostsArgs,
+    ...identityArgs,
     `root@${host}`,
     `docker compose --project-directory ${COMPOSE_PROJECT_DIR} ps --format json`,
   ]
@@ -114,13 +119,20 @@ export async function getUmamiComposeStatus(host: string, spawn: SpawnFn = defau
     ...(process.env.SSH_AUTH_SOCK ? {SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK} : {}),
   }
 
-  const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+  let stdoutText: string
+  let stderrText: string
+  let exitCode: number
 
-  const [stdoutText, stderrText, exitCode] = await Promise.all([
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-    child.exited,
-  ])
+  try {
+    const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+    ;[stdoutText, stderrText, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+  } finally {
+    cleanup()
+  }
 
   if (exitCode !== 0) {
     return {

package/src/commands/vpn/shared.test.ts

@@ -1,4 +1,4 @@
-import {describe, expect, it} from 'bun:test'
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
 
 import {getVpnStatusSummary, parseWgShowOutput, type WgShowResult} from './shared'
 
@@ -332,3 +332,123 @@ describe('WgShowResult type', () => {
     expect(result.peerCount).toBe(2)
   })
 })
+
+// ─── SSH identity injection (VPN_SSH_KEY) ─────────────────────────────────────
+
+describe('getVpnWgStatus — SSH identity injection', () => {
+  let originalEnv: Record<string, string | undefined>
+
+  beforeEach(() => {
+    originalEnv = {VPN_SSH_KEY: process.env.VPN_SSH_KEY}
+  })
+
+  afterEach(() => {
+    if (originalEnv.VPN_SSH_KEY === undefined) {
+      delete process.env.VPN_SSH_KEY
+    } else {
+      process.env.VPN_SSH_KEY = originalEnv.VPN_SSH_KEY
+    }
+  })
+
+  it('includes -i <path> and IdentitiesOnly=yes in ssh argv when VPN_SSH_KEY is set', async () => {
+    const {getVpnWgStatus} = await import('./shared')
+    process.env.VPN_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    const wgOutput = 'interface: wg0\n  public key: key==\n  private key: (hidden)\n  listening port: 51820\n'
+    let capturedCmd: string[] = []
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(wgOutput))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getVpnWgStatus('1.2.3.4', capturingSpawn)
+
+    const iIdx = capturedCmd.indexOf('-i')
+    expect(iIdx).toBeGreaterThan(-1)
+    expect(capturedCmd[iIdx + 1]).toBeTruthy()
+
+    const identitiesOnlyIdx = capturedCmd.indexOf('IdentitiesOnly=yes')
+    expect(identitiesOnlyIdx).toBeGreaterThan(-1)
+  })
+
+  it('does not include -i or IdentitiesOnly=yes when VPN_SSH_KEY is absent', async () => {
+    const {getVpnWgStatus} = await import('./shared')
+    delete process.env.VPN_SSH_KEY
+
+    const wgOutput = 'interface: wg0\n  public key: key==\n  private key: (hidden)\n  listening port: 51820\n'
+    let capturedCmd: string[] = []
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      capturedCmd = cmd
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(wgOutput))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getVpnWgStatus('1.2.3.4', capturingSpawn)
+
+    expect(capturedCmd.indexOf('-i')).toBe(-1)
+    expect(capturedCmd.indexOf('IdentitiesOnly=yes')).toBe(-1)
+  })
+
+  it('cleans up the temp key file after the SSH command completes', async () => {
+    const {getVpnWgStatus} = await import('./shared')
+    const {statSync} = await import('node:fs')
+    process.env.VPN_SSH_KEY = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+
+    const wgOutput = 'interface: wg0\n  public key: key==\n  private key: (hidden)\n  listening port: 51820\n'
+    let capturedKeyPath: string | undefined
+    const capturingSpawn: SpawnFn = (cmd, _opts) => {
+      const iIdx = cmd.indexOf('-i')
+      if (iIdx !== -1) capturedKeyPath = cmd[iIdx + 1]
+      const enc = new TextEncoder()
+      return {
+        stdout: new ReadableStream({
+          start(c) {
+            c.enqueue(enc.encode(wgOutput))
+            c.close()
+          },
+        }),
+        stderr: new ReadableStream({
+          start(c) {
+            c.close()
+          },
+        }),
+        exited: Promise.resolve(0),
+      }
+    }
+
+    await getVpnWgStatus('1.2.3.4', capturingSpawn)
+
+    expect(capturedKeyPath).toBeTruthy()
+    const keyPath = capturedKeyPath
+    if (keyPath) {
+      expect(() => statSync(keyPath)).toThrow()
+    }
+  })
+})

package/src/commands/vpn/shared.ts

@@ -2,6 +2,7 @@ import type {StatusSummary} from '../status'
 
 import {buildKnownHostsArgs} from '../../lib/known-hosts'
 import {redactHost} from '../../lib/redact'
+import {buildIdentityArgs} from '../../lib/ssh-identity'
 import {validateVpnHost} from './host'
 
 declare const process: {
@@ -79,13 +80,17 @@ export interface VpnStatusResult {
 export async function getVpnWgStatus(host: string, spawn: SpawnFn = defaultSpawn): Promise<VpnStatusResult> {
   validateVpnHost(host)
 
+  const knownHostsArgs = buildKnownHostsArgs()
+  const {args: identityArgs, cleanup} = buildIdentityArgs(process.env.VPN_SSH_KEY)
+
   const sshCmd = [
     'ssh',
     '-o',
     'BatchMode=yes',
     '-o',
     'StrictHostKeyChecking=yes',
-    ...buildKnownHostsArgs(),
+    ...knownHostsArgs,
+    ...identityArgs,
     `ubuntu@${host}`,
     'sudo wg show wg0',
   ]
@@ -96,13 +101,20 @@ export async function getVpnWgStatus(host: string, spawn: SpawnFn = defaultSpawn
     ...(process.env.SSH_AUTH_SOCK ? {SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK} : {}),
   }
 
-  const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
-
-  const [stdoutText, stderrText, exitCode] = await Promise.all([
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-    child.exited,
-  ])
+  let stdoutText: string
+  let stderrText: string
+  let exitCode: number
+
+  try {
+    const child = spawn(sshCmd, {env, stdout: 'pipe', stderr: 'pipe'})
+    ;[stdoutText, stderrText, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+  } finally {
+    cleanup()
+  }
 
   if (exitCode !== 0) {
     const redacted = redactHost(stderrText.trim(), host) || 'unknown error'

package/src/lib/ssh-identity.test.ts

@@ -0,0 +1,134 @@
+import {readFileSync, statSync} from 'node:fs'
+import {describe, expect, it} from 'bun:test'
+
+import {buildIdentityArgs, materializeIdentityFile} from './ssh-identity'
+
+// ─── materializeIdentityFile ──────────────────────────────────────────────────
+
+describe('materializeIdentityFile', () => {
+  it('writes the key to a temp file and returns a path', () => {
+    const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {path, cleanup} = materializeIdentityFile(key)
+
+    try {
+      expect(path).toBeTruthy()
+      const stat = statSync(path)
+      expect(stat.isFile()).toBe(true)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('writes the file with mode 0600', () => {
+    const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {path, cleanup} = materializeIdentityFile(key)
+
+    try {
+      const stat = statSync(path)
+      const mode = stat.mode & 0o777
+      expect(mode).toBe(0o600)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('ensures the key file ends with a newline', () => {
+    const keyWithoutNewline = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----'
+    const {path, cleanup} = materializeIdentityFile(keyWithoutNewline)
+
+    try {
+      const text = readFileSync(path, 'utf8')
+      expect(text.endsWith('\n')).toBe(true)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('does not double-add a newline when key already ends with one', () => {
+    const keyWithNewline = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {path, cleanup} = materializeIdentityFile(keyWithNewline)
+
+    try {
+      const text = readFileSync(path, 'utf8')
+      expect(text.endsWith('\n\n')).toBe(false)
+      expect(text.endsWith('\n')).toBe(true)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('cleanup removes the temp file and directory', () => {
+    const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {path, cleanup} = materializeIdentityFile(key)
+    const dir = path.slice(0, path.lastIndexOf('/'))
+
+    cleanup()
+
+    // Both the key file and its containing temp dir must be gone.
+    expect(() => statSync(path)).toThrow()
+    expect(() => statSync(dir)).toThrow()
+  })
+
+  it('cleanup is idempotent (calling twice does not throw)', () => {
+    const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {cleanup} = materializeIdentityFile(key)
+
+    cleanup()
+    expect(() => cleanup()).not.toThrow()
+  })
+})
+
+// ─── buildIdentityArgs ────────────────────────────────────────────────────────
+
+describe('buildIdentityArgs', () => {
+  it('returns [-i, <path>, -o, IdentitiesOnly=yes] when a key is provided', () => {
+    const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {args, cleanup} = buildIdentityArgs(key)
+
+    try {
+      expect(args).toHaveLength(4)
+      expect(args[0]).toBe('-i')
+      expect(args[1]).toBeTruthy() // path to temp file
+      expect(args[2]).toBe('-o')
+      expect(args[3]).toBe('IdentitiesOnly=yes')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('returns empty args and a no-op cleanup when key is empty string', () => {
+    const {args, cleanup} = buildIdentityArgs('')
+
+    expect(args).toHaveLength(0)
+    expect(() => cleanup()).not.toThrow()
+  })
+
+  it('returns empty args and a no-op cleanup when key is whitespace-only', () => {
+    const {args, cleanup} = buildIdentityArgs('   \n  ')
+
+    expect(args).toHaveLength(0)
+    expect(() => cleanup()).not.toThrow()
+  })
+
+  it('returns empty args and a no-op cleanup when key is undefined', () => {
+    const {args, cleanup} = buildIdentityArgs(undefined)
+
+    expect(args).toHaveLength(0)
+    expect(() => cleanup()).not.toThrow()
+  })
+
+  it('the -i path points to a real 0600 file', () => {
+    const key = '-----BEGIN OPENSSH PRIVATE KEY-----\nfakekey\n-----END OPENSSH PRIVATE KEY-----\n'
+    const {args, cleanup} = buildIdentityArgs(key)
+
+    try {
+      const keyPath = args[1]
+      expect(keyPath).toBeTruthy()
+      const stat = statSync(keyPath as string)
+      const mode = stat.mode & 0o777
+      expect(mode).toBe(0o600)
+    } finally {
+      cleanup()
+    }
+  })
+})

package/src/lib/ssh-identity.ts

@@ -0,0 +1,76 @@
+import {chmodSync, mkdtempSync, rmSync, writeFileSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+
+/**
+ * A materialized private-key file plus a best-effort cleanup callback.
+ * The cleanup removes the temp directory containing the key file.
+ */
+export interface MaterializedIdentity {
+  path: string
+  cleanup: () => void
+}
+
+// NOTE: This intentionally duplicates the key-materialization logic in
+// packages/shared/server/droplet-helpers.ts. The published CLI must not depend
+// on @marcusrbrown/infra-shared (that dep breaks npm install for external users).
+
+/**
+ * Writes a private key to a 0600 temp file (with a guaranteed single trailing
+ * newline) and returns its path plus an idempotent best-effort cleanup callback.
+ *
+ * The trailing newline guards against env/secret injection stripping it
+ * (OpenSSH rejects keys without it). Empty/whitespace-key guards live in
+ * `buildIdentityArgs`; this function materializes whatever key bytes it receives.
+ */
+export function materializeIdentityFile(privateKey: string): MaterializedIdentity {
+  const dir = mkdtempSync(join(tmpdir(), 'infra-ssh-key-'))
+  const path = join(dir, 'id')
+
+  const cleanup = (): void => {
+    try {
+      rmSync(dir, {recursive: true, force: true})
+    } catch {
+      // Best-effort: a missing temp dir (already cleaned) is fine.
+    }
+  }
+
+  try {
+    const contents = privateKey.endsWith('\n') ? privateKey : `${privateKey}\n`
+    writeFileSync(path, contents, {mode: 0o600})
+    chmodSync(path, 0o600)
+  } catch (error) {
+    // Don't leave a partial 0600 key (or its temp dir) behind on write failure.
+    cleanup()
+    throw error
+  }
+
+  return {path, cleanup}
+}
+
+/**
+ * Result of `buildIdentityArgs` — the SSH argv fragment plus a cleanup callback.
+ * When the key is absent/empty, `args` is empty and `cleanup` is a no-op.
+ */
+export interface IdentityArgs {
+  /** SSH argv fragment: `['-i', '<path>', '-o', 'IdentitiesOnly=yes']` or `[]`. */
+  args: string[]
+  /** Removes the temp key file. Idempotent and safe to call multiple times. */
+  cleanup: () => void
+}
+
+/**
+ * Builds the `-i <keyfile> -o IdentitiesOnly=yes` SSH argv fragment from an
+ * optional private key string.
+ *
+ * When `privateKey` is absent, empty, or whitespace-only, returns empty args
+ * and a no-op cleanup so callers fall back to ssh-agent behaviour unchanged.
+ */
+export function buildIdentityArgs(privateKey: string | undefined): IdentityArgs {
+  if (!privateKey?.trim()) {
+    return {args: [], cleanup: () => undefined}
+  }
+
+  const {path, cleanup} = materializeIdentityFile(privateKey)
+  return {args: ['-i', path, '-o', 'IdentitiesOnly=yes'], cleanup}
+}