@marcusrbrown/infra 0.9.18 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcusrbrown/infra",
-  "version": "0.9.18",
+  "version": "0.10.0",
   "description": "Infrastructure management CLI — deploy automation, health checks, and MCP bridge",
   "keywords": [
     "infra",
@@ -31,6 +31,7 @@
   "dependencies": {
     "@clack/prompts": "^1.2.0",
     "@goke/mcp": "^0.0.10",
+    "@marcusrbrown/infra-shared": "workspace:*",
     "goke": "^6.3.2",
     "string-dedent": "^3.0.2",
     "zod": "^4.3.6"

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

@@ -143,9 +143,42 @@ Commands:
     --key [key]                        Environment variable name holding the SSH host. Falls back to UMAMI_DOMAIN when omitted.
 
 
+  vpn status                           Show operational health of the VPN box via SSH and wg show.
+
+    --key [key]                        Environment variable name holding the SSH host. Falls back to VPN_HOST when omitted.
+
+
+  vpn deploy                           Deploy the VPN. Default mode triggers the GitHub Deploy VPN workflow, while --local runs apps/vpn deploy directly with Bun.
+
+    --local                            Run local deployment with Bun using apps/vpn 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-server-key                 Force regeneration of the server WireGuard keypair. WARNING: invalidates all existing client configs. (default: false)
+
+
+  vpn logs                             Stream WireGuard VPN logs via SSH and journalctl.
+
+    --tail [n]                         Number of log lines to tail. (default: 100)
+    --allow-ci                         Allow log streaming in CI environments. Logs may contain sensitive VPN data. (default: false)
+    --key [key]                        Environment variable name holding the SSH host. Falls back to VPN_HOST when omitted.
+
+
+  vpn client add <name>                Add a new VPN client peer. Generates a keypair, assigns a tunnel IP, and writes the client .conf to apps/vpn/clients/.
+
+    --split-tunnel [cidrs]             Comma-separated CIDRs for split-tunnel routing. Defaults to 0.0.0.0/0 (full tunnel).
+    --dns [dns]                        DNS server for the client config.
+    --server-pubkey [key]              Server public key. Falls back to VPN_SERVER_PUBKEY env var.
+    --endpoint [host]                  VPN server endpoint (IP or hostname). Falls back to VPN_HOST env var.
+
+
+  vpn client list                      List all VPN client peers from peers.json.
+
+
+  vpn client remove <name>             Remove a VPN client peer from peers.json. Run \`infra vpn deploy\` to revoke access.
+
+
   status                               Show status of all deployments
 
-    --json                             Output machine-readable JSON with keeweb, cliproxy, gateway, and umami summary objects.
+    --json                             Output machine-readable JSON with keeweb, cliproxy, gateway, umami, and vpn summary objects.
     --verbose                          Include verbose per-app health check details when building the summary rows.
 
 

package/src/cli.ts

@@ -8,6 +8,7 @@ import {registerKeewebCommands} from './commands/keeweb'
 import {registerMcp} from './commands/mcp'
 import {registerStatus} from './commands/status'
 import {registerUmamiCommands} from './commands/umami'
+import {registerVpnCommands} from './commands/vpn'
 
 declare const process: {
   argv: string[]
@@ -22,6 +23,7 @@ registerKeewebCommands(cli)
 registerCliproxyCommands(cli)
 registerGatewayCommands(cli)
 registerUmamiCommands(cli)
+registerVpnCommands(cli)
 registerStatus(cli)
 registerMcp(cli)
 

package/src/commands/mcp.test.ts

@@ -35,15 +35,23 @@ import {registerKeewebCommands} from './keeweb'
 import {MCP_ALLOWLIST, registerMcp} from './mcp'
 import {registerStatus} from './status'
 import {registerUmamiCommands} from './umami'
+import {registerVpnCommands} from './vpn'
 
 // ─── Tool name constants ──────────────────────────────────────────────────────
 
 /**
  * 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.
+ * per the Tier-1 test bar in packages/cli/AGENTS.md. Six read-only status tools.
  */
-const EXPECTED_TOOLS = ['cliproxy_status', 'gateway_status', 'keeweb_status', 'status', 'umami_status'].sort()
+const EXPECTED_TOOLS = [
+  'cliproxy_status',
+  'gateway_status',
+  'keeweb_status',
+  'status',
+  'umami_status',
+  'vpn_status',
+].sort()
 
 /**
  * CLI-only commands that must NOT appear in the MCP tool list: the
@@ -70,6 +78,12 @@ const CLI_ONLY_TOOLS = [
   'cliproxy_keys_remove',
   'cliproxy_config_get',
   'cliproxy_config_set',
+  // VPN: mutating / sensitive / log-streaming — CLI-only
+  'vpn_deploy',
+  'vpn_logs',
+  'vpn_client_add',
+  'vpn_client_list',
+  'vpn_client_remove',
 ].sort()
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -81,6 +95,7 @@ function buildTestCli(): ReturnType<typeof goke> {
   registerCliproxyCommands(cli)
   registerGatewayCommands(cli)
   registerUmamiCommands(cli)
+  registerVpnCommands(cli)
   registerStatus(cli)
   registerMcp(cli)
   return cli

package/src/commands/mcp.ts

@@ -24,6 +24,11 @@ import {createMcpAction} from '@goke/mcp'
  * - `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
+ * - `vpn deploy`           — mutating: deploys WireGuard config to live VPN box; CLI-only
+ * - `vpn logs`             — sensitive: streams journalctl logs that may reveal peer IPs/traffic; CLI-only
+ * - `vpn client add`       — mutating: generates keypair + appends peer + triggers redeploy; CLI-only
+ * - `vpn client list`      — sensitive: lists peer public keys and tunnel IPs; CLI-only
+ * - `vpn client remove`    — mutating: removes peer + triggers redeploy; 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
@@ -35,6 +40,7 @@ export const MCP_ALLOWLIST: ReadonlySet<string> = new Set([
   'cliproxy status',
   'keeweb status',
   'umami status',
+  'vpn status',
   'status',
 ])
 

package/src/commands/status.test.ts

@@ -40,12 +40,22 @@ const healthyUmami: StatusSummary = {
   usageStats: '—',
 }
 
+const healthyVpn: StatusSummary = {
+  app: 'vpn',
+  http: 'OK: wg0 up, pubkey:TESTKEY== 1 peer(s)',
+  lastDeploy: '—',
+  version: '—',
+  contentHash: '—',
+  usageStats: '—',
+}
+
 function makeDeps(overrides?: Partial<Parameters<typeof registerStatus>[1]>): Parameters<typeof registerStatus>[1] {
   return {
     getKeewebStatusSummary: async () => healthyKeeweb,
     getCliproxyStatusSummary: async () => healthyCliproxy,
     getGatewayStatusSummary: async () => healthyGateway,
     getUmamiStatusSummary: async () => healthyUmami,
+    getVpnStatusSummary: async () => healthyVpn,
     ...overrides,
   }
 }
@@ -63,6 +73,40 @@ describe('top-level status command (Tier-2 ctx capture)', () => {
     expect(expectCapturedToInclude(captured, '| cliproxy | OK | — | v1.2.3 | — | 12 req / 0 fail |')).toBe(true)
     expect(expectCapturedToInclude(captured, '| gateway | OK: gateway:running/healthy | — | — | — | — |')).toBe(true)
     expect(expectCapturedToInclude(captured, '| umami | OK: umami:running/healthy | — | — | — | — |')).toBe(true)
+    expect(expectCapturedToInclude(captured, '| vpn | OK: wg0 up, pubkey:TESTKEY== 1 peer(s) | — | — | — | — |')).toBe(
+      true,
+    )
+  })
+
+  it('includes a vpn row sourced from getVpnStatusSummary()', async () => {
+    const {ctx, captured} = createCapturedCtx()
+
+    await unifiedStatusAction({}, ctx, makeDeps())
+
+    // The vpn row must appear in the table output
+    expect(expectCapturedToInclude(captured, '| vpn |')).toBe(true)
+  })
+
+  it('shows an error row for vpn when getVpnStatusSummary rejects', async () => {
+    const {ctx, captured} = createCapturedCtx()
+
+    await unifiedStatusAction(
+      {},
+      ctx,
+      makeDeps({
+        getVpnStatusSummary: async () => {
+          throw new Error('VPN_HOST not set')
+        },
+      }),
+    )
+
+    expect(
+      expectCapturedToInclude(
+        captured,
+        '| vpn | ❌ VPN_HOST not set | ❌ VPN_HOST not set | ❌ VPN_HOST not set | ❌ VPN_HOST not set | ❌ VPN_HOST not set |',
+      ),
+    ).toBe(true)
+    expect(captured.stderr.join('')).toContain('vpn status check failed: VPN_HOST not set')
   })
 
   it('shows an error row when umami is unreachable and keeps the other results', async () => {
@@ -127,12 +171,14 @@ describe('top-level status command (Tier-2 ctx capture)', () => {
       cliproxy: {version: string}
       gateway: {http: string}
       umami: {http: string}
+      vpn: {http: string}
     }
 
     expect(parsed.keeweb.http).toBe('OK')
     expect(parsed.cliproxy.version).toBe('v1.2.3')
     expect(parsed.gateway.http).toBe('OK: gateway:running/healthy')
     expect(parsed.umami.http).toBe('OK: umami:running/healthy')
+    expect(parsed.vpn.http).toBe('OK: wg0 up, pubkey:TESTKEY== 1 peer(s)')
   })
 
   it('does not write to global console (output is captured via ctx)', async () => {

package/src/commands/status.ts

@@ -8,13 +8,14 @@ import {getCliproxyStatusSummary} from './cliproxy/status'
 import {getGatewayStatusSummary} from './gateway'
 import {getKeewebStatusSummary} from './keeweb/status'
 import {getUmamiStatusSummary} from './umami'
+import {getVpnStatusSummary} from './vpn'
 
 declare const process: {
   env: Record<string, string | undefined>
 }
 
 export interface StatusSummary {
-  app: 'keeweb' | 'cliproxy' | 'gateway' | 'umami'
+  app: 'keeweb' | 'cliproxy' | 'gateway' | 'umami' | 'vpn'
   http: string
   lastDeploy: string
   version: string
@@ -29,6 +30,7 @@ interface StatusDependencies {
   getCliproxyStatusSummary: (baseUrl: string, key: string, verbose: boolean) => Promise<StatusSummary>
   getGatewayStatusSummary: (host: string) => Promise<StatusSummary>
   getUmamiStatusSummary: (host: string) => Promise<StatusSummary>
+  getVpnStatusSummary: (host: string) => Promise<StatusSummary>
 }
 
 const DEFAULT_CLIPROXY_URL = 'https://cliproxy.fro.bot'
@@ -66,6 +68,7 @@ function toJsonPayload(rows: StatusSummary[]): Record<AppName, StatusSummary> {
     cliproxy: rows.find(row => row.app === 'cliproxy') ?? errorSummary('cliproxy', 'missing result'),
     gateway: rows.find(row => row.app === 'gateway') ?? errorSummary('gateway', 'missing result'),
     umami: rows.find(row => row.app === 'umami') ?? errorSummary('umami', 'missing result'),
+    vpn: rows.find(row => row.app === 'vpn') ?? errorSummary('vpn', 'missing result'),
   }
 }
 
@@ -82,6 +85,7 @@ export async function unifiedStatusAction(
     getCliproxyStatusSummary,
     getGatewayStatusSummary,
     getUmamiStatusSummary,
+    getVpnStatusSummary,
   },
 ): Promise<void> {
   const verbose = options.verbose === true
@@ -89,15 +93,17 @@ export async function unifiedStatusAction(
   const cliproxyKey = process.env.CLIPROXY_MANAGEMENT_KEY ?? ''
   const gatewayHost = process.env.GATEWAY_HOST ?? ''
   const umamiHost = process.env.UMAMI_DOMAIN ?? ''
+  const vpnHost = process.env.VPN_HOST ?? ''
 
   const results = await Promise.allSettled([
     dependencies.getKeewebStatusSummary(verbose),
     dependencies.getCliproxyStatusSummary(cliproxyBaseUrl, cliproxyKey, verbose),
     dependencies.getGatewayStatusSummary(gatewayHost),
     dependencies.getUmamiStatusSummary(umamiHost),
+    dependencies.getVpnStatusSummary(vpnHost),
   ])
 
-  const appNames: AppName[] = ['keeweb', 'cliproxy', 'gateway', 'umami']
+  const appNames: AppName[] = ['keeweb', 'cliproxy', 'gateway', 'umami', 'vpn']
   const rows: StatusSummary[] = results.map((result, index) => {
     const app = appNames[index] ?? 'keeweb'
     if (result.status === 'fulfilled') {
@@ -127,13 +133,16 @@ export function registerStatus(
     getCliproxyStatusSummary,
     getGatewayStatusSummary,
     getUmamiStatusSummary,
+    getVpnStatusSummary,
   },
 ): void {
   cli
     .command('status', 'Show status of all deployments')
     .option(
       '--json',
-      z.boolean().describe('Output machine-readable JSON with keeweb, cliproxy, gateway, and umami summary objects.'),
+      z
+        .boolean()
+        .describe('Output machine-readable JSON with keeweb, cliproxy, gateway, umami, and vpn summary objects.'),
     )
     .option(
       '--verbose',

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

@@ -0,0 +1,379 @@
+import {mkdirSync, mkdtempSync, rmSync, writeFileSync} from 'node:fs'
+import {readFile} from 'node:fs/promises'
+import {tmpdir} from 'node:os'
+import {join, resolve} from 'node:path'
+import {afterEach, beforeEach, describe, expect, it} from 'bun:test'
+
+import {vpnClientAdd, vpnClientList, vpnClientRemove, type KeypairGenFn} from './client'
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeKeypairGen(privateKey: string, publicKey: string): KeypairGenFn {
+  return async () => ({privateKey, publicKey})
+}
+
+function makePeersJson(peers: {name: string; publicKey: string; tunnelIp: string}[]): string {
+  return `${JSON.stringify({peers}, null, 2)}\n`
+}
+
+// ─── generateKeypair ─────────────────────────────────────────────────────────
+
+describe('generateKeypair', () => {
+  it('returns an object with privateKey and publicKey strings via injected keypairGen', async () => {
+    // Use dependency injection — never depends on host `wg` binary.
+    const mockPrivateKey = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA='
+    const mockPublicKey = 'BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB='
+    const keypairGen = makeKeypairGen(mockPrivateKey, mockPublicKey)
+
+    // vpnClientAdd uses keypairGen internally; test the injected path directly
+    // by calling the mock and asserting the returned shape
+    const keypair = await keypairGen()
+
+    expect(typeof keypair.privateKey).toBe('string')
+    expect(typeof keypair.publicKey).toBe('string')
+    expect(keypair.privateKey).toBe(mockPrivateKey)
+    expect(keypair.publicKey).toBe(mockPublicKey)
+  })
+
+  it('vpnClientAdd uses the injected keypairGen — no dependency on host wg binary', async () => {
+    // This test verifies that vpnClientAdd correctly uses the injected keypairGen
+    // and returns the keypair values from it (not from a real wg invocation).
+    const {mkdtempSync: mkdtemp, mkdirSync, writeFileSync: writeFile, rmSync: rm} = await import('node:fs')
+    const {tmpdir} = await import('node:os')
+    const {join: joinPath} = await import('node:path')
+
+    const tmpDir = mkdtemp(joinPath(tmpdir(), 'vpn-keypair-test-'))
+    const peersJsonPath = joinPath(tmpDir, 'peers.json')
+    const clientsDir = joinPath(tmpDir, 'clients')
+    mkdirSync(clientsDir, {recursive: true})
+    writeFile(peersJsonPath, `${JSON.stringify({peers: []}, null, 2)}\n`)
+
+    try {
+      const injectedPrivateKey = 'INJECTEDPRIVATEKEYVALUE1234567890123456789='
+      const injectedPublicKey = 'INJECTEDPUBLICKEYVALUE12345678901234567890='
+      const keypairGen = makeKeypairGen(injectedPrivateKey, injectedPublicKey)
+
+      const result = await vpnClientAdd('testdevice', {
+        peersJsonPath,
+        clientsDir,
+        serverPublicKey: 'SERVERPUBKEY==',
+        endpoint: '1.2.3.4',
+        keypairGen,
+      })
+
+      // The result must use the injected keypair values
+      expect(result.tunnelIp).toBe('10.8.0.2')
+
+      // Client .conf must contain the injected private key
+      const {readFile} = await import('node:fs/promises')
+      const confContent = await readFile(result.confPath, 'utf-8')
+      expect(confContent).toContain(injectedPrivateKey)
+
+      // peers.json must contain the injected public key
+      const peersContent = await readFile(peersJsonPath, 'utf-8')
+      expect(peersContent).toContain(injectedPublicKey)
+      expect(peersContent).not.toContain(injectedPrivateKey)
+    } finally {
+      rm(tmpDir, {recursive: true, force: true})
+    }
+  })
+})
+
+// ─── vpnClientAdd ─────────────────────────────────────────────────────────────
+
+describe('vpnClientAdd', () => {
+  let tmpDir: string
+  let peersJsonPath: string
+  let clientsDir: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'vpn-client-test-'))
+    peersJsonPath = join(tmpDir, 'peers.json')
+    clientsDir = join(tmpDir, 'clients')
+    mkdirSync(clientsDir, {recursive: true})
+
+    // Start with empty peers.json
+    writeFileSync(peersJsonPath, makePeersJson([]))
+  })
+
+  afterEach(() => {
+    rmSync(tmpDir, {recursive: true, force: true})
+  })
+
+  it('generates a keypair, assigns next IP, appends public key to peers.json, writes client .conf', async () => {
+    const keypairGen = makeKeypairGen('PRIVATEKEYVALUE==', 'PUBLICKEYVALUE==')
+
+    const result = await vpnClientAdd('laptop', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen,
+    })
+
+    // Check result
+    expect(result.tunnelIp).toBe('10.8.0.2')
+    expect(result.confPath).toBe(join(clientsDir, 'laptop.conf'))
+
+    // Check peers.json was updated with PUBLIC key only
+    const peersContent = await readFile(peersJsonPath, 'utf-8')
+    const peersData = JSON.parse(peersContent) as {peers: {name: string; publicKey: string; tunnelIp: string}[]}
+    expect(peersData.peers).toHaveLength(1)
+    expect(peersData.peers[0]?.name).toBe('laptop')
+    expect(peersData.peers[0]?.publicKey).toBe('PUBLICKEYVALUE==')
+    expect(peersData.peers[0]?.tunnelIp).toBe('10.8.0.2')
+
+    // Check client .conf was written with PRIVATE key
+    const confContent = await readFile(result.confPath, 'utf-8')
+    expect(confContent).toContain('PRIVATEKEYVALUE==')
+    expect(confContent).toContain('SERVERPUBKEY==')
+    expect(confContent).toContain('1.2.3.4:51820')
+    expect(confContent).toContain('10.8.0.2/32')
+    expect(confContent).toContain('AllowedIPs = 0.0.0.0/0')
+  })
+
+  it('assigns sequential IPs for multiple clients', async () => {
+    const keypairGen1 = makeKeypairGen('PRIV1==', 'PUB1==')
+    const keypairGen2 = makeKeypairGen('PRIV2==', 'PUB2==')
+
+    await vpnClientAdd('laptop', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen: keypairGen1,
+    })
+
+    const result2 = await vpnClientAdd('phone', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen: keypairGen2,
+    })
+
+    expect(result2.tunnelIp).toBe('10.8.0.3')
+  })
+
+  it('supports split-tunnel via allowedIps option', async () => {
+    const keypairGen = makeKeypairGen('PRIV==', 'PUB==')
+
+    const result = await vpnClientAdd('laptop', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen,
+      allowedIps: '10.0.0.0/8,192.168.0.0/16',
+    })
+
+    const confContent = await readFile(result.confPath, 'utf-8')
+    expect(confContent).toContain('AllowedIPs = 10.0.0.0/8,192.168.0.0/16')
+  })
+
+  it('throws when a peer with the same name already exists', async () => {
+    const keypairGen = makeKeypairGen('PRIV==', 'PUB==')
+
+    await vpnClientAdd('laptop', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen,
+    })
+
+    await expect(
+      vpnClientAdd('laptop', {
+        peersJsonPath,
+        clientsDir,
+        serverPublicKey: 'SERVERPUBKEY==',
+        endpoint: '1.2.3.4',
+        keypairGen,
+      }),
+    ).rejects.toThrow('already exists')
+  })
+
+  it('refuses to write client .conf outside the clients directory', async () => {
+    const keypairGen = makeKeypairGen('PRIV==', 'PUB==')
+
+    // Attempt path traversal: name with ../ to escape clients dir
+    await expect(
+      vpnClientAdd('../evil', {
+        peersJsonPath,
+        clientsDir,
+        serverPublicKey: 'SERVERPUBKEY==',
+        endpoint: '1.2.3.4',
+        keypairGen,
+      }),
+    ).rejects.toThrow()
+  })
+
+  it('client .conf contains private key but peers.json contains only public key', async () => {
+    const keypairGen = makeKeypairGen('SECRETPRIVATEKEY==', 'PUBLICKEY==')
+
+    const result = await vpnClientAdd('laptop', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen,
+    })
+
+    // peers.json must NOT contain the private key
+    const peersContent = await readFile(peersJsonPath, 'utf-8')
+    expect(peersContent).not.toContain('SECRETPRIVATEKEY==')
+    expect(peersContent).toContain('PUBLICKEY==')
+
+    // client .conf must contain the private key
+    const confContent = await readFile(result.confPath, 'utf-8')
+    expect(confContent).toContain('SECRETPRIVATEKEY==')
+  })
+})
+
+// ─── vpnClientList ────────────────────────────────────────────────────────────
+
+describe('vpnClientList', () => {
+  let tmpDir: string
+  let peersJsonPath: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'vpn-client-test-'))
+    peersJsonPath = join(tmpDir, 'peers.json')
+  })
+
+  afterEach(() => {
+    rmSync(tmpDir, {recursive: true, force: true})
+  })
+
+  it('returns empty array when no peers', async () => {
+    writeFileSync(peersJsonPath, makePeersJson([]))
+
+    const peers = await vpnClientList(peersJsonPath)
+
+    expect(peers).toHaveLength(0)
+  })
+
+  it('returns all peers with name, publicKey, tunnelIp', async () => {
+    writeFileSync(
+      peersJsonPath,
+      makePeersJson([
+        {name: 'laptop', publicKey: 'PUB1==', tunnelIp: '10.8.0.2'},
+        {name: 'phone', publicKey: 'PUB2==', tunnelIp: '10.8.0.3'},
+      ]),
+    )
+
+    const peers = await vpnClientList(peersJsonPath)
+
+    expect(peers).toHaveLength(2)
+    expect(peers[0]?.name).toBe('laptop')
+    expect(peers[0]?.publicKey).toBe('PUB1==')
+    expect(peers[0]?.tunnelIp).toBe('10.8.0.2')
+    expect(peers[1]?.name).toBe('phone')
+  })
+})
+
+// ─── vpnClientRemove ──────────────────────────────────────────────────────────
+
+describe('vpnClientRemove', () => {
+  let tmpDir: string
+  let peersJsonPath: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'vpn-client-test-'))
+    peersJsonPath = join(tmpDir, 'peers.json')
+  })
+
+  afterEach(() => {
+    rmSync(tmpDir, {recursive: true, force: true})
+  })
+
+  it('removes a peer from peers.json', async () => {
+    writeFileSync(
+      peersJsonPath,
+      makePeersJson([
+        {name: 'laptop', publicKey: 'PUB1==', tunnelIp: '10.8.0.2'},
+        {name: 'phone', publicKey: 'PUB2==', tunnelIp: '10.8.0.3'},
+      ]),
+    )
+
+    await vpnClientRemove('laptop', peersJsonPath)
+
+    const peersContent = await readFile(peersJsonPath, 'utf-8')
+    const peersData = JSON.parse(peersContent) as {peers: {name: string}[]}
+    expect(peersData.peers).toHaveLength(1)
+    expect(peersData.peers[0]?.name).toBe('phone')
+  })
+
+  it('throws when removing a non-existent peer', async () => {
+    writeFileSync(peersJsonPath, makePeersJson([]))
+
+    await expect(vpnClientRemove('nonexistent', peersJsonPath)).rejects.toThrow('not found')
+  })
+
+  it('after remove, list reflects the removal', async () => {
+    writeFileSync(
+      peersJsonPath,
+      makePeersJson([
+        {name: 'laptop', publicKey: 'PUB1==', tunnelIp: '10.8.0.2'},
+        {name: 'phone', publicKey: 'PUB2==', tunnelIp: '10.8.0.3'},
+      ]),
+    )
+
+    await vpnClientRemove('laptop', peersJsonPath)
+    const peers = await vpnClientList(peersJsonPath)
+
+    expect(peers).toHaveLength(1)
+    expect(peers[0]?.name).toBe('phone')
+  })
+})
+
+// ─── Write-guard: client .conf must stay in clients/ ─────────────────────────
+
+describe('write-guard: client .conf path safety', () => {
+  let tmpDir: string
+  let peersJsonPath: string
+  let clientsDir: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'vpn-client-test-'))
+    peersJsonPath = join(tmpDir, 'peers.json')
+    clientsDir = join(tmpDir, 'clients')
+    mkdirSync(clientsDir, {recursive: true})
+    writeFileSync(peersJsonPath, makePeersJson([]))
+  })
+
+  afterEach(() => {
+    rmSync(tmpDir, {recursive: true, force: true})
+  })
+
+  it('resolves the output path under clientsDir', async () => {
+    const keypairGen = makeKeypairGen('PRIV==', 'PUB==')
+
+    const result = await vpnClientAdd('mydevice', {
+      peersJsonPath,
+      clientsDir,
+      serverPublicKey: 'SERVERPUBKEY==',
+      endpoint: '1.2.3.4',
+      keypairGen,
+    })
+
+    // The resolved path must be under clientsDir
+    const resolvedClientsDir = resolve(clientsDir)
+    expect(result.confPath.startsWith(resolvedClientsDir)).toBe(true)
+  })
+
+  it('rejects a name that would escape the clients directory via path traversal', async () => {
+    const keypairGen = makeKeypairGen('PRIV==', 'PUB==')
+
+    // Path traversal attempt
+    await expect(
+      vpnClientAdd('../../etc/passwd', {
+        peersJsonPath,
+        clientsDir,
+        serverPublicKey: 'SERVERPUBKEY==',
+        endpoint: '1.2.3.4',
+        keypairGen,
+      }),
+    ).rejects.toThrow()
+  })
+})