mirab 0.0.0 → 0.2.0

package/src/isolation/sync.ts

@@ -0,0 +1,329 @@
+// Working-directory sync for `mirab spawn --vm`. Stock Firecracker has no
+// virtio-fs, so the guest works on a copy of the directory (an ext4 drive) and
+// its changes come back to the host at exit and on demand (`mirab sync <id>`).
+//
+// The rule, per path, three-way against the baseline (the tree as it was copied
+// into the guest, or as of the last sync):
+// - the guest changed it and the host still matches the baseline: applied;
+// - the host changed it too: the host copy is kept and the guest's version is
+//   saved under `conflictDir`, never merged and never silently dropped;
+// - only the host changed it: untouched.
+// The guest is untrusted: its paths are validated, nothing is written through a
+// symlink or outside the root, and file bytes must match the hash it listed.
+import { createHash } from 'node:crypto'
+import { AnchoredDirectory } from './anchored-fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import type { Entry, GuestFiles } from './session'
+
+export type Manifest = Map<string, Entry>
+export type RecoveryLocation = { directory: string; note: string }
+
+export interface SyncResult {
+  written: string[]
+  deleted: string[]
+  conflicts: { path: string; reason: string; saved?: string }[]
+  /** What the agent changed about itself (its definition, `.env`): saved
+   *  aside, never applied, for the person to review. */
+  held: { path: string; reason: string; saved?: string }[]
+  rejected: { path: string; reason: string }[]
+  /** Final VM sync only: private retained workspace and recovery note. */
+  recovery?: RecoveryLocation
+}
+
+/** The host side of the guest agent's `list` op: same walk, same fields. */
+export async function hostManifest(root: string): Promise<Manifest> {
+  const out: Manifest = new Map(),
+    anchored = AnchoredDirectory.open(root)
+  const walk = async (
+    directory: AnchoredDirectory,
+    path: string,
+    prefix: string,
+  ) => {
+    for (const name of (await readdir(path)).sort()) {
+      const rel = prefix ? `${prefix}/${name}` : name
+      const e = directory.entry(name, rel, true)
+      if (!e) continue
+      out.set(rel, e)
+      if (e.k === 'd') {
+        const child = directory.directory(name)
+        try {
+          await walk(child, join(path, name), rel)
+        } finally {
+          child.close()
+        }
+      }
+    }
+  }
+  try {
+    await walk(anchored, root, '')
+  } finally {
+    anchored.close()
+  }
+  return out
+}
+
+/** Equal for sync purposes: kind, content or link target, and permission bits. */
+export function sameEntry(a?: Entry, b?: Entry) {
+  if (!a || !b) return a === b
+  if (a.k !== b.k) return false
+  if (a.k === 'l') return a.t === b.t
+  if ((a.m & 0o777) !== (b.m & 0o777)) return false
+  return a.k === 'd' || a.h === b.h
+}
+
+export function validPath(p: unknown): p is string {
+  return (
+    typeof p === 'string' &&
+    p.length > 0 &&
+    p.length < 4096 &&
+    !p.startsWith('/') &&
+    !p.includes('\0') &&
+    p.split('/').every((c) => c !== '' && c !== '.' && c !== '..')
+  )
+}
+
+function validEntry(e: Entry) {
+  if (!validPath(e.p) || !Number.isInteger(e.m) || e.m < 0 || e.m > 0o7777)
+    return false
+  if (e.k === 'f')
+    return (
+      Number.isSafeInteger(e.s) &&
+      e.s! >= 0 &&
+      typeof e.h === 'string' &&
+      /^[0-9a-f]{64}$/.test(e.h)
+    )
+  if (e.k === 'l')
+    return typeof e.t === 'string' && e.t.length > 0 && !e.t.includes('\0')
+  return e.k === 'd'
+}
+
+/** What an agent is, and what it may reach: its definition (`agent/`: the
+ *  manifest's domains, packages and tools, its instructions) and the
+ *  project's `.env` (which secrets it names). A VM's change to these never
+ *  lands on its own: it would be the agent widening itself for its next
+ *  session. Held aside for the person instead. */
+export function selfDefinition(path: string) {
+  // Case-folded: on a Mac's disk Agent/ and .ENV are agent/ and .env. Every
+  // .env file, since tools read .env.local and the like too.
+  const first = path.split('/')[0].normalize('NFC').toLowerCase()
+  return first === 'agent' || first.startsWith('.env')
+}
+
+/** Guest Git state is never adopted as trusted host repository metadata. */
+export function protectedMetadata(path: string) {
+  return path.split('/').some((part) => part.toLowerCase() === '.git')
+}
+
+export interface SyncOptions {
+  /** Host directory the guest's copy came from. */
+  root: string
+  /** Where the guest sees it. */
+  guestRoot: string
+  files: GuestFiles
+  /** Updated only for applied/resolved changes; conflicts stay pending. */
+  baseline: Manifest
+  /** Conflicting bytes and adjacent metadata are saved outside the root. */
+  conflictDir: string
+  /** Refuse a sync that would copy more than this many bytes. */
+  maxBytes?: number
+}
+
+export async function syncBack(o: SyncOptions): Promise<SyncResult> {
+  const result: SyncResult = {
+    written: [],
+    deleted: [],
+    conflicts: [],
+    held: [],
+    rejected: [],
+  }
+  const guest: Manifest = new Map()
+  for (const e of await o.files.list(o.guestRoot)) {
+    // mke2fs puts lost+found at the root of the copy; it was never the user's.
+    if (
+      !o.baseline.has('lost+found') &&
+      (e.p === 'lost+found' || e.p?.startsWith?.('lost+found/'))
+    )
+      continue
+    if (!validEntry(e)) {
+      result.rejected.push({
+        path: String(e.p),
+        reason: 'invalid entry from the guest',
+      })
+      continue
+    }
+    guest.set(e.p, e)
+  }
+  const changed = [...new Set([...o.baseline.keys(), ...guest.keys()])].filter(
+    (p) => {
+      if (sameEntry(o.baseline.get(p), guest.get(p))) return false
+      if (!validPath(p) || protectedMetadata(p)) {
+        result.rejected.push({
+          path: p,
+          reason:
+            'host Git metadata is protected; retained in the guest workspace',
+        })
+        return false
+      }
+      return true
+    },
+  )
+  const bytes = changed.reduce((n, p) => {
+    const e = guest.get(p)
+    return n + (e?.k === 'f' ? (e.s ?? 0) : 0)
+  }, 0)
+  if (!Number.isSafeInteger(bytes) || bytes > (o.maxBytes ?? 2 * 1024 ** 3))
+    throw new Error(`sync would copy ${bytes} bytes; refusing`)
+  // Deletions deepest first, then creations and updates parents first.
+  const deletions = changed
+    .filter((p) => !guest.has(p))
+    .sort()
+    .reverse()
+  const updates = changed.filter((p) => guest.has(p)).sort()
+
+  const root = AnchoredDirectory.open(o.root)
+  const fetch = async (rel: string, after: Entry) => {
+    const data = await o.files.read(`${o.guestRoot}/${rel}`)
+    if (
+      data.length !== after.s ||
+      createHash('sha256').update(data).digest('hex') !== after.h
+    )
+      throw new Error('guest file changed while syncing')
+    return data
+  }
+  const conflict = (
+    rel: string,
+    reason: string,
+    after?: Entry,
+    data?: Buffer,
+    into: SyncResult['conflicts'] = result.conflicts,
+  ) => {
+    let saved: string | undefined
+    if (after?.k === 'f' && data) {
+      // The private recovery root is host-owned. Child paths use the same
+      // anchored primitives as normal sync, never a guest-provided pathname.
+      mkdirSync(o.conflictDir, { recursive: true, mode: 0o700 })
+      const recovery = AnchoredDirectory.open(o.conflictDir)
+      let parent: AnchoredDirectory | undefined
+      try {
+        parent = recovery.parent(rel, true)
+        parent.put(rel.split('/').at(-1)!, { ...after, m: 0o600 }, data)
+        saved = join(o.conflictDir, rel)
+      } finally {
+        if (parent && parent !== recovery) parent.close()
+        recovery.close()
+      }
+    }
+    // Never materialize a conflicting link/directory/deletion in recovery.
+    // Store its exact entry as private JSON, with a host-chosen hashed name.
+    const metadataDir = o.conflictDir + '.metadata'
+    mkdirSync(metadataDir, { recursive: true, mode: 0o700 })
+    const metadata = AnchoredDirectory.open(metadataDir)
+    const name = createHash('sha256').update(rel).digest('hex') + '.json'
+    try {
+      metadata.put(
+        name,
+        { p: name, k: 'f', m: 0o600 },
+        Buffer.from(
+          JSON.stringify({ path: rel, reason, entry: after ?? null }) + '\n',
+        ),
+      )
+      saved ??= join(metadataDir, name)
+    } finally {
+      metadata.close()
+    }
+    into.push({ path: rel, reason, ...(saved ? { saved } : {}) })
+  }
+  try {
+    for (const rel of [...deletions, ...updates]) {
+      const before = o.baseline.get(rel),
+        after = guest.get(rel)
+      let parent: AnchoredDirectory | undefined
+      try {
+        // Finish asynchronous guest retrieval before opening/checking the host
+        // destination. All host validation and mutation below are synchronous
+        // and relative to directory descriptors, including temp and rename.
+        const data = after?.k === 'f' ? await fetch(rel, after) : undefined
+        // The agent's change to itself: saved aside, never applied; the
+        // baseline stays, so it is still pending next time.
+        if (selfDefinition(rel)) {
+          conflict(
+            rel,
+            'the agent changed its own definition; held for you to review',
+            after,
+            data,
+            result.held,
+          )
+          continue
+        }
+        try {
+          parent = root.parent(rel)
+        } catch {
+          conflict(rel, 'a parent is not a directory on the host', after, data)
+          continue
+        }
+        const name = rel.split('/').at(-1)!
+        const current = parent.entry(name, rel)
+        if (sameEntry(current, after)) {
+          setBaseline(o.baseline, rel, after)
+          continue
+        }
+        if (!sameEntry(current, before)) {
+          conflict(rel, 'changed on the host and in the guest', after, data)
+          continue
+        }
+        if (!after) {
+          parent.remove(name, current!.k === 'd')
+          result.deleted.push(rel)
+        } else if (after.k === 'd') {
+          if (current && current.k !== 'd') parent.remove(name, false)
+          const directory = parent.directory(name, true)
+          directory.close()
+          parent.mode(name, after.m & 0o777, true)
+          result.written.push(rel)
+        } else if (
+          after.k === 'f' &&
+          current?.k === 'f' &&
+          current.h === after.h
+        ) {
+          parent.mode(name, after.m & 0o777, false)
+          result.written.push(rel)
+        } else {
+          parent.put(name, after, data, current?.k === 'd')
+          result.written.push(rel)
+        }
+        setBaseline(o.baseline, rel, after)
+      } catch (e) {
+        result.conflicts.push({
+          path: rel,
+          reason: `not applied: ${(e as Error).message}`,
+        })
+      } finally {
+        if (parent && parent !== root) parent.close()
+      }
+    }
+  } finally {
+    root.close()
+  }
+  return result
+}
+
+function setBaseline(m: Manifest, rel: string, e?: Entry) {
+  if (e) m.set(rel, e)
+  else m.delete(rel)
+}
+
+export function describeSync(r: SyncResult) {
+  const parts = [
+    `${r.written.length} written`,
+    `${r.deleted.length} deleted`,
+    `${r.conflicts.length} conflicts`,
+  ]
+  if (r.held.length)
+    parts.push(
+      `${r.held.length} held (the agent changed its own definition: ${r.held.map((h) => h.saved ?? h.path).join(', ')})`,
+    )
+  if (r.rejected.length) parts.push(`${r.rejected.length} rejected`)
+  return parts.join(', ')
+}

package/src/isolation/vz-network-setup.ts

@@ -0,0 +1,247 @@
+// `sudo mirab vm network setup`: the one-time owner step that gives macOS `vz`
+// guests filtered egress, from the released binary instead of a loose script.
+//
+// VZ NAT (vmnet shared mode) puts guests on a host bridge (192.168.64.0/24 by
+// default) and NATs them out of the Mac, which also reaches the Mac itself,
+// its LAN, the tailnet and link-local. Only pf (root) can deny that. Setup:
+//   1. writes the pf anchor: guests may use the vmnet DNS forwarder on the
+//      gateway and DHCP, and nothing else in 10/8, 172.16/12, 192.168/16,
+//      100.64/10, 169.254/16, 127/8 or multicast; the internet passes;
+//   2. checks it with `pfctl -n` before anything loads it;
+//   3. loads it under com.apple/mirab-vz (stock pf.conf already evaluates
+//      anchor "com.apple/*", so pf.conf is not edited) from a LaunchDaemon
+//      that runs only /sbin/pfctl, so it survives reboots;
+//   4. writes the root-owned marker vzNetworkState reads (never pfctl) to
+//      decide that a VM may get a NAT device.
+import { execFileSync } from 'node:child_process'
+import {
+  chmodSync,
+  chownSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname } from 'node:path'
+import { VZ_LAN_DENIED, VZ_NETWORK_MARKER } from './vz'
+
+export const VZ_ANCHOR = 'com.apple/mirab-vz'
+export const VZ_ANCHOR_FILE = '/etc/pf.anchors/mirab-vz'
+export const VZ_DAEMON_LABEL = 'gg.mirab.vz-net'
+export const VZ_DAEMON_PLIST = `/Library/LaunchDaemons/${VZ_DAEMON_LABEL}.plist`
+const VMNET_PLIST =
+  '/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist'
+
+/** Everything a guest must never reach through VZ NAT. */
+export const DENIED_RANGES = [
+  '10.0.0.0/8',
+  '172.16.0.0/12',
+  '192.168.0.0/16',
+  '100.64.0.0/10', // the tailnet
+  '169.254.0.0/16',
+  '127.0.0.0/8',
+  '224.0.0.0/4',
+]
+
+export interface VmnetNetwork {
+  gateway: string
+  subnet: string
+}
+
+/** 255.255.255.0 → 24. Refuses a mask that isn't contiguous ones then zeros. */
+export function maskPrefix(mask: string): number {
+  const octets = mask.split('.').map(Number)
+  if (
+    octets.length !== 4 ||
+    octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)
+  )
+    throw new Error(`not a netmask: ${mask}`)
+  const bits = octets.map((o) => o.toString(2).padStart(8, '0')).join('')
+  if (!/^1*0*$/.test(bits)) throw new Error(`not a contiguous netmask: ${mask}`)
+  return bits.indexOf('0') === -1 ? 32 : bits.indexOf('0')
+}
+
+export interface VzNetworkFile {
+  path: string
+  mode: number
+  content: string
+}
+
+/** The three files setup writes, in the order it writes them. */
+export function vzNetworkFiles(net: VmnetNetwork): VzNetworkFile[] {
+  const { gateway: gw, subnet } = net
+  return [
+    {
+      path: VZ_ANCHOR_FILE,
+      mode: 0o644,
+      content: `# mirab vz guests (vmnet shared network ${subnet}): internet yes, LAN/host/metadata no.
+pass in quick inet proto { tcp udp } from ${subnet} to ${gw} port 53
+pass in quick inet proto udp from any port 68 to any port 67
+block drop in quick inet from ${subnet} to { ${DENIED_RANGES.join(' ')} }
+`,
+    },
+    {
+      path: VZ_DAEMON_PLIST,
+      mode: 0o644,
+      content: `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${VZ_DAEMON_LABEL}</string>
+  <key>ProgramArguments</key><array>
+    <string>/sbin/pfctl</string><string>-E</string>
+    <string>-a</string><string>${VZ_ANCHOR}</string>
+    <string>-f</string><string>${VZ_ANCHOR_FILE}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+</dict></plist>
+`,
+    },
+    {
+      path: VZ_NETWORK_MARKER,
+      mode: 0o644,
+      content:
+        JSON.stringify({
+          version: 1,
+          network: VZ_LAN_DENIED,
+          gateway: gw,
+          subnet,
+          anchor: VZ_ANCHOR,
+        }) + '\n',
+    },
+  ]
+}
+
+/** What setup and remove touch on the machine; tests pass their own. */
+export interface VzSetupSystem {
+  isRoot(): boolean
+  platform: NodeJS.Platform
+  /** vmnet's configured shared network, if the owner changed it. */
+  readDefault(key: 'Shared_Net_Address' | 'Shared_Net_Mask'): string | undefined
+  /** Runs a command; throws when it fails. */
+  run(argv: string[]): void
+  /** Exit status of a command, for checks that may fail. */
+  succeeds(argv: string[]): boolean
+  /** Atomically installs a root:wheel file with this mode. */
+  install(file: VzNetworkFile): void
+  remove(path: string): void
+}
+
+export const realVzSystem: VzSetupSystem = {
+  isRoot: () => process.getuid?.() === 0,
+  platform: process.platform,
+  readDefault(key) {
+    try {
+      return execFileSync('/usr/bin/defaults', ['read', VMNET_PLIST, key], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim()
+    } catch {
+      return undefined
+    }
+  },
+  run(argv) {
+    execFileSync(argv[0]!, argv.slice(1), { stdio: 'inherit' })
+  },
+  succeeds(argv) {
+    try {
+      execFileSync(argv[0]!, argv.slice(1), { stdio: 'ignore' })
+      return true
+    } catch {
+      return false
+    }
+  },
+  install({ path, mode, content }) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o755 })
+    const tmp = `${path}.new`
+    writeFileSync(tmp, content, { mode })
+    chmodSync(tmp, mode)
+    chownSync(tmp, 0, 0)
+    renameSync(tmp, path)
+  },
+  remove(path) {
+    rmSync(path, { force: true })
+  },
+}
+
+export function vmnetNetwork(sys: VzSetupSystem): VmnetNetwork {
+  const gateway = sys.readDefault('Shared_Net_Address') ?? '192.168.64.1'
+  const mask = sys.readDefault('Shared_Net_Mask') ?? '255.255.255.0'
+  return { gateway, subnet: `${gateway}/${maskPrefix(mask)}` }
+}
+
+function precheck(sys: VzSetupSystem, dryRun: boolean, verb: string) {
+  if (sys.platform !== 'darwin')
+    throw new Error(
+      'mirab vm network is for macOS vz guests; Firecracker hosts are set up separately',
+    )
+  if (!dryRun && !sys.isRoot())
+    throw new Error(
+      `run with sudo: sudo ~/.mirab/bin/mirab vm network ${verb} (or add --dry-run to see what it does)`,
+    )
+}
+
+const loaded = (sys: VzSetupSystem) =>
+  sys.succeeds(['/bin/launchctl', 'print', `system/${VZ_DAEMON_LABEL}`])
+
+/** Installs the filter, or prints what it would do. Safe to run again. */
+export function setupVzNetwork(
+  opts: { dryRun?: boolean; log?: (line: string) => void },
+  sys: VzSetupSystem = realVzSystem,
+) {
+  const dryRun = !!opts.dryRun
+  const log = opts.log ?? console.log
+  precheck(sys, dryRun, 'setup')
+  const net = vmnetNetwork(sys)
+  const [anchor, daemon, marker] = vzNetworkFiles(net)
+  const step = (what: string, act: () => void) =>
+    dryRun ? log(`+ ${what}`) : act()
+  const write = (f: VzNetworkFile) => {
+    if (dryRun) log(`--- ${f.path} (${f.mode.toString(8)})\n${f.content}`)
+    else sys.install(f)
+  }
+
+  write(anchor!)
+  // A broken anchor must never reach the running firewall.
+  step(`pfctl -n -a ${VZ_ANCHOR} -f ${VZ_ANCHOR_FILE}`, () =>
+    sys.run(['/sbin/pfctl', '-n', '-a', VZ_ANCHOR, '-f', VZ_ANCHOR_FILE]),
+  )
+  write(daemon!)
+  if (!dryRun && loaded(sys))
+    // Already installed: rerun the daemon so the new anchor is loaded now.
+    sys.run(['/bin/launchctl', 'kickstart', '-k', `system/${VZ_DAEMON_LABEL}`])
+  else
+    step(`launchctl bootstrap system ${VZ_DAEMON_PLIST}`, () =>
+      sys.run(['/bin/launchctl', 'bootstrap', 'system', VZ_DAEMON_PLIST]),
+    )
+  // Last: mirab trusts the marker, so it appears only once the filter is live.
+  write(marker!)
+  log(
+    `${dryRun ? 'would install' : 'installed'}: mirab vz network filter (anchor ${VZ_ANCHOR}, guests on ${net.subnet}). Check with: mirab vm network status`,
+  )
+}
+
+/** Undoes setup: the marker first, so no VM is offered NAT without the filter. */
+export function removeVzNetwork(
+  opts: { dryRun?: boolean; log?: (line: string) => void },
+  sys: VzSetupSystem = realVzSystem,
+) {
+  const dryRun = !!opts.dryRun
+  const log = opts.log ?? console.log
+  precheck(sys, dryRun, 'remove')
+  const step = (what: string, act: () => void) =>
+    dryRun ? log(`+ ${what}`) : act()
+  step(`rm ${VZ_NETWORK_MARKER}`, () => sys.remove(VZ_NETWORK_MARKER))
+  if (dryRun) log(`+ launchctl bootout system/${VZ_DAEMON_LABEL}`)
+  else if (loaded(sys))
+    sys.run(['/bin/launchctl', 'bootout', `system/${VZ_DAEMON_LABEL}`])
+  step(`pfctl -a ${VZ_ANCHOR} -F all`, () =>
+    sys.succeeds(['/sbin/pfctl', '-a', VZ_ANCHOR, '-F', 'all']),
+  )
+  step(`rm ${VZ_DAEMON_PLIST} ${VZ_ANCHOR_FILE}`, () => {
+    sys.remove(VZ_DAEMON_PLIST)
+    sys.remove(VZ_ANCHOR_FILE)
+  })
+  log(
+    `${dryRun ? 'would remove' : 'removed'}: mirab vz network filter; vz VMs get no network until setup runs again`,
+  )
+}