mirab 0.0.0 → 0.2.0

package/src/isolation/anchored-fs.ts

@@ -0,0 +1,284 @@
+// All sync mutations are relative to opened directories. Pathname checks alone
+// cannot protect a later write when a directory is replaced during guest I/O.
+import { createRequire } from 'node:module'
+const requireNative = createRequire(import.meta.url)
+const ffi = () => requireNative('bun:ffi') as typeof import('bun:ffi')
+const ptr = (buffer: Buffer) => ffi().ptr(buffer)
+import {
+  closeSync,
+  constants,
+  fchmodSync,
+  fstatSync,
+  openSync,
+  readSync,
+  writeFileSync,
+} from 'node:fs'
+import { createHash, randomBytes } from 'node:crypto'
+import type { Entry } from './session'
+
+const CLOEXEC = process.platform === 'darwin' ? 0x1000000 : 0x80000
+
+function native() {
+  if (process.platform !== 'darwin' && process.platform !== 'linux')
+    throw new Error('anchored VM sync is supported only on macOS and Linux')
+  const errnoSymbol =
+    process.platform === 'darwin' ? '__error' : '__errno_location'
+  const statSymbol =
+    process.platform === 'darwin' && process.arch === 'x64'
+      ? 'fstatat$INODE64'
+      : 'fstatat'
+  const lib = ffi().dlopen(
+    process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : 'libc.so.6',
+    {
+      openat: { args: ['i32', 'ptr', 'i32', 'u32'], returns: 'i32' },
+      mkdirat: { args: ['i32', 'ptr', 'u32'], returns: 'i32' },
+      unlinkat: { args: ['i32', 'ptr', 'i32'], returns: 'i32' },
+      renameat: { args: ['i32', 'ptr', 'i32', 'ptr'], returns: 'i32' },
+      symlinkat: { args: ['ptr', 'i32', 'ptr'], returns: 'i32' },
+      readlinkat: { args: ['i32', 'ptr', 'ptr', 'u64'], returns: 'i64' },
+      [statSymbol]: { args: ['i32', 'ptr', 'ptr', 'i32'], returns: 'i32' },
+      [errnoSymbol]: { args: [], returns: 'ptr' },
+    } as const,
+  )
+  return {
+    ...lib.symbols,
+    metadata: lib.symbols[statSymbol],
+    errno: () =>
+      new Int32Array(
+        ffi().toArrayBuffer(lib.symbols[errnoSymbol]()! as number, 0, 4),
+      )[0],
+  }
+}
+let api: ReturnType<typeof native> | undefined
+const sys = () => (api ??= native())
+const cstr = (s: string) => Buffer.from(s + '\0')
+const check = (n: number | bigint, op: string) => {
+  if (n < 0) throw new Error(`${op} failed (errno ${sys().errno()})`)
+  return Number(n)
+}
+
+export class AnchoredDirectory {
+  constructor(readonly fd: number) {}
+  static open(path: string) {
+    return new AnchoredDirectory(
+      openSync(
+        path,
+        constants.O_RDONLY |
+          constants.O_DIRECTORY |
+          constants.O_NOFOLLOW |
+          CLOEXEC,
+      ),
+    )
+  }
+  close() {
+    closeSync(this.fd)
+  }
+  directory(name: string, create = false) {
+    const p = cstr(name)
+    if (create) {
+      const r = sys().mkdirat(this.fd, ptr(p), 0o700)
+      if (r < 0 && sys().errno() !== 17) check(r, 'mkdirat') // EEXIST
+    }
+    const fd = check(
+      sys().openat(
+        this.fd,
+        ptr(p),
+        constants.O_RDONLY |
+          constants.O_DIRECTORY |
+          constants.O_NOFOLLOW |
+          CLOEXEC,
+        0,
+      ),
+      'openat directory',
+    )
+    return new AnchoredDirectory(fd)
+  }
+  parent(rel: string, create = false) {
+    let at: AnchoredDirectory = this
+    try {
+      for (const part of rel.split('/').slice(0, -1)) {
+        const next = at.directory(part, create)
+        if (at !== this) at.close()
+        at = next
+      }
+      return at
+    } catch (e) {
+      if (at !== this) at.close()
+      throw e
+    }
+  }
+  entry(name: string, rel: string, skipUnsupported = false): Entry | undefined {
+    const p = cstr(name),
+      link = Buffer.alloc(4096)
+    // Inspect without opening a FIFO/device/socket. The stat ABI is fixed for
+    // the supported 64-bit platforms; only mode is read from an oversized buffer.
+    if (!['x64', 'arm64'].includes(process.arch))
+      throw new Error('anchored sync metadata requires x64 or arm64')
+    const info = Buffer.alloc(256)
+    const status = Number(
+      sys().metadata(
+        this.fd,
+        ptr(p),
+        ptr(info),
+        process.platform === 'darwin' ? 0x20 : 0x100, // AT_SYMLINK_NOFOLLOW
+      ),
+    )
+    if (status < 0 && sys().errno() === 2) return undefined
+    check(status, 'fstatat entry')
+    const mode =
+      process.platform === 'darwin'
+        ? info.readUInt16LE(4)
+        : info.readUInt32LE(process.arch === 'x64' ? 24 : 16)
+    if (
+      ![constants.S_IFREG, constants.S_IFDIR, constants.S_IFLNK].includes(
+        mode & constants.S_IFMT,
+      )
+    ) {
+      if (skipUnsupported) return undefined
+      throw new Error('unsupported host file type')
+    }
+    const n = Number(sys().readlinkat(this.fd, ptr(p), ptr(link), link.length))
+    if (n >= 0) {
+      if (n === link.length) throw new Error('link target exceeds sync limit')
+      return { p: rel, k: 'l', m: 0, t: link.subarray(0, n).toString() }
+    }
+    const fd = sys().openat(
+      this.fd,
+      ptr(p),
+      constants.O_RDONLY |
+        constants.O_NOFOLLOW |
+        constants.O_NONBLOCK |
+        CLOEXEC,
+      0,
+    )
+    if (fd < 0 && sys().errno() === 2) return undefined // ENOENT only
+    check(fd, 'openat entry')
+    try {
+      const st = fstatSync(fd)
+      if (st.isDirectory()) return { p: rel, k: 'd', m: st.mode & 0o7777 }
+      if (!st.isFile()) throw new Error('unsupported host file type')
+      const hash = createHash('sha256'),
+        buffer = Buffer.alloc(64 * 1024)
+      let n: number
+      while ((n = readSync(fd, buffer, 0, buffer.length, null)) > 0)
+        hash.update(buffer.subarray(0, n))
+      return {
+        p: rel,
+        k: 'f',
+        m: st.mode & 0o7777,
+        s: st.size,
+        h: hash.digest('hex'),
+      }
+    } finally {
+      closeSync(fd)
+    }
+  }
+  remove(name: string, directory: boolean) {
+    const p = cstr(name)
+    check(
+      sys().unlinkat(
+        this.fd,
+        ptr(p),
+        directory ? (process.platform === 'darwin' ? 0x80 : 0x200) : 0,
+      ),
+      'unlinkat',
+    )
+  }
+  mode(name: string, mode: number, directory: boolean) {
+    const p = cstr(name)
+    const fd = check(
+      sys().openat(
+        this.fd,
+        ptr(p),
+        constants.O_RDONLY |
+          constants.O_NOFOLLOW |
+          CLOEXEC |
+          (directory ? constants.O_DIRECTORY : constants.O_NONBLOCK),
+        0,
+      ),
+      'openat mode',
+    )
+    try {
+      if (!(directory ? fstatSync(fd).isDirectory() : fstatSync(fd).isFile()))
+        throw new Error('host file type changed')
+      fchmodSync(fd, mode)
+    } finally {
+      closeSync(fd)
+    }
+  }
+  /** A regular file's bytes and its entry, hashed from those same bytes;
+   *  undefined when `name` is gone or is anything but a file. */
+  read(name: string, rel: string): { entry: Entry; data: Buffer } | undefined {
+    const p = cstr(name)
+    const fd = sys().openat(
+      this.fd,
+      ptr(p),
+      constants.O_RDONLY |
+        constants.O_NOFOLLOW |
+        constants.O_NONBLOCK |
+        CLOEXEC,
+      0,
+    )
+    if (fd < 0) return undefined
+    try {
+      const st = fstatSync(fd)
+      if (!st.isFile()) return undefined
+      const chunks: Buffer[] = []
+      const buffer = Buffer.alloc(64 * 1024)
+      let n: number
+      while ((n = readSync(fd, buffer, 0, buffer.length, null)) > 0)
+        chunks.push(Buffer.from(buffer.subarray(0, n)))
+      const data = Buffer.concat(chunks)
+      return {
+        entry: {
+          p: rel,
+          k: 'f',
+          m: st.mode & 0o7777,
+          s: data.length,
+          h: createHash('sha256').update(data).digest('hex'),
+        },
+        data,
+      }
+    } finally {
+      closeSync(fd)
+    }
+  }
+  put(name: string, e: Entry, data?: Buffer, replaceDirectory = false) {
+    const temp = cstr(`.mirab-sync-${randomBytes(12).toString('hex')}`),
+      dest = cstr(name)
+    let made = false
+    try {
+      if (e.k === 'f') {
+        const fd = check(
+          sys().openat(
+            this.fd,
+            ptr(temp),
+            constants.O_WRONLY |
+              constants.O_CREAT |
+              constants.O_EXCL |
+              constants.O_NOFOLLOW |
+              CLOEXEC,
+            0o600,
+          ),
+          'openat temp',
+        )
+        made = true
+        try {
+          writeFileSync(fd, data!)
+          fchmodSync(fd, e.m & 0o777)
+        } finally {
+          closeSync(fd)
+        }
+      } else {
+        const target = cstr(e.t!)
+        check(sys().symlinkat(ptr(target), this.fd, ptr(temp)), 'symlinkat')
+        made = true
+      }
+      if (replaceDirectory) this.remove(name, true)
+      check(sys().renameat(this.fd, ptr(temp), this.fd, ptr(dest)), 'renameat')
+      made = false
+    } finally {
+      if (made) sys().unlinkat(this.fd, ptr(temp), 0)
+    }
+  }
+}

package/src/isolation/colima.ts

@@ -0,0 +1,159 @@
+// macOS `container` level: OCI containers inside Colima's Linux VM (Lima,
+// vmType vz, virtiofs mounts, Docker runtime). The Mac is separated from jobs
+// by Colima's VM, and jobs from each other by the same hardened container
+// flags and egress policy as on Linux (that policy runs inside Colima's VM).
+// mirab only detects Colima; installing or starting it is the owner's call.
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+export const COLIMA_INSTALL =
+  'brew install colima docker && colima start --vm-type vz --mount-type virtiofs'
+
+export interface ColimaMount {
+  location: string
+  writable: boolean
+}
+
+export type ColimaState =
+  | {
+      running: true
+      /** `unix://…/docker.sock`, passed to docker as `--host`. */
+      socket: string
+      vmType: string
+      arch: string
+      mountType: string
+      mounts: ColimaMount[]
+    }
+  | { running: false; reason: string; fix: string }
+
+export interface ColimaProbe {
+  /** stdout of `colima status --json`, or undefined if it failed or is not installed. */
+  status(): string | undefined
+  installed(): boolean
+  /** ~/.colima/default/colima.yaml, if present. */
+  config(): string | undefined
+  home: string
+  exists(path: string): boolean
+}
+
+export const systemColimaProbe = (profile = 'default'): ColimaProbe => ({
+  installed: () => {
+    try {
+      execFileSync('colima', ['version'], { stdio: 'ignore', timeout: 5000 })
+      return true
+    } catch {
+      return false
+    }
+  },
+  status: () => {
+    try {
+      return execFileSync('colima', ['status', '--json', '-p', profile], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 10_000,
+      })
+    } catch {
+      return undefined
+    }
+  },
+  config: () => {
+    try {
+      return readFileSync(
+        join(homedir(), '.colima', profile, 'colima.yaml'),
+        'utf8',
+      )
+    } catch {
+      return undefined
+    }
+  },
+  home: homedir(),
+  exists: existsSync,
+})
+
+/** The `mounts:` list of colima.yaml; an empty list means Colima's default ($HOME, writable). */
+export function colimaMounts(yaml: string | undefined, home: string) {
+  let raw: unknown
+  try {
+    raw = yaml ? (globalThis as any).Bun?.YAML?.parse(yaml)?.mounts : undefined
+  } catch {
+    raw = undefined
+  }
+  const list = Array.isArray(raw) ? raw : []
+  if (!list.length) return [{ location: home, writable: true }]
+  return list
+    .filter((m) => m && typeof m.location === 'string')
+    .map((m) => ({
+      location: resolve(m.location.replace(/^~(?=$|\/)/, home)),
+      writable: m.writable === true,
+    }))
+}
+
+export function detectColima(p: ColimaProbe): ColimaState {
+  if (!p.installed())
+    return {
+      running: false,
+      reason: 'Colima is not installed',
+      fix: `Needs Sami: ${COLIMA_INSTALL}`,
+    }
+  const out = p.status()
+  let s: Record<string, unknown> | undefined
+  try {
+    s = out ? JSON.parse(out) : undefined
+  } catch {
+    s = undefined
+  }
+  if (!s)
+    return {
+      running: false,
+      reason: 'Colima is not running',
+      fix: 'colima start --vm-type vz --mount-type virtiofs',
+    }
+  const socket = String(s.docker_socket ?? '')
+  if (s.runtime !== 'docker' || !socket.startsWith('unix://'))
+    return {
+      running: false,
+      reason: `Colima runs the ${String(s.runtime)} runtime; mirab needs docker`,
+      fix: 'colima start --runtime docker (a new profile; the runtime of an existing VM cannot change)',
+    }
+  if (!p.exists(socket.slice('unix://'.length)))
+    return {
+      running: false,
+      reason: `Colima's docker socket ${socket} is missing`,
+      fix: 'colima restart',
+    }
+  const driver = String(s.driver ?? '')
+  return {
+    running: true,
+    socket,
+    vmType: /virtualization/i.test(driver)
+      ? 'vz'
+      : /qemu/i.test(driver)
+        ? 'qemu'
+        : driver || 'unknown',
+    arch: String(s.arch ?? 'unknown'),
+    mountType: String(s.mount_type ?? 'unknown'),
+    mounts: colimaMounts(p.config(), p.home),
+  }
+}
+
+/** The mount that makes `path` visible in Colima's VM, if any (and writable when asked). */
+export function colimaMountFor(
+  path: string,
+  mounts: ColimaMount[],
+  writable: boolean,
+) {
+  const abs = resolve(path)
+  return mounts.find(
+    (m) =>
+      (abs === m.location || abs.startsWith(m.location + '/')) &&
+      (!writable || m.writable),
+  )
+}
+
+export function colimaStatusLine(c: ColimaState) {
+  return c.running
+    ? `colima: running (${c.vmType}, ${c.arch}, ${c.mountType} mounts: ${c.mounts.map((m) => `${m.location}${m.writable ? '' : ' ro'}`).join(', ')})`
+    : `colima: unavailable (${c.reason}); ${c.fix}`
+}

package/src/isolation/container.ts

@@ -0,0 +1,189 @@
+// `container` level, OCI implementation (Docker or Podman). Same guest agent,
+// same exec contract, the job directory bind-mounted at /workspace. Other
+// container technologies (FreeBSD jails) slot in as another backend name.
+import { spawn, execFileSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { userInfo } from 'node:os'
+import {
+  guestExec,
+  guestPut,
+  type Channel,
+  type Isolation,
+  type Opener,
+} from './session'
+
+export interface OciConfig {
+  /** `docker` or `podman` (anything with the same CLI). */
+  engine: string
+  image: string
+  /** Static linux guest agent binary, mounted read-only into the container. */
+  agent: string
+  memory: string
+  cpus: string
+  pids: number
+  egress: 'auto' | 'block' | 'allow'
+  /** Engine endpoint (`docker --host`), e.g. Colima's socket on macOS. */
+  host?: string
+  /** Where the engine runs, for labels: `Colima vz VM`. */
+  where?: string
+}
+
+/** Global engine flags that pick the endpoint; empty for the local default. */
+const endpoint = (host?: string) => (host ? ['--host', host] : [])
+
+export const EGRESS_NETWORK = 'mirab-egress'
+
+function egressNetworkReady(engine: string, host?: string) {
+  try {
+    execFileSync(
+      engine,
+      [...endpoint(host), 'network', 'inspect', EGRESS_NETWORK],
+      {
+        stdio: 'ignore',
+      },
+    )
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Network the container joins: the filtered bridge, or none. `allow` without setup is an error. */
+export function containerNetwork(
+  mode: OciConfig['egress'],
+  ready: boolean,
+  setup = NETWORK_SETUP,
+) {
+  if (mode === 'block' || (!ready && mode === 'auto')) return 'none'
+  if (!ready)
+    throw new Error(
+      `egress is set to allow but the ${EGRESS_NETWORK} network is not set up. Needs Sami: ${setup}`,
+    )
+  return EGRESS_NETWORK
+}
+
+export const GUEST_WORK = '/workspace'
+export const NETWORK_SETUP = 'sudo scripts/vm-network-setup.sh'
+/** The same script, run inside Colima's VM, where the containers' network lives. */
+export const COLIMA_NETWORK_SETUP =
+  'colima ssh -- sudo sh -s up < scripts/vm-network-setup.sh'
+
+export function ociAvailable(engine: string, agent: string, host?: string) {
+  try {
+    execFileSync(
+      engine,
+      [...endpoint(host), 'version', '--format', '{{.Server.Version}}'],
+      {
+        stdio: 'ignore',
+        timeout: 5000,
+      },
+    )
+    execFileSync('test', ['-x', agent])
+    return true
+  } catch {
+    return false
+  }
+}
+
+function execChannel(engine: string, name: string, host?: string): Channel {
+  const child = spawn(
+    engine,
+    [...endpoint(host), 'exec', '-i', name, '/mirab-guest-agent', '--stdio'],
+    {
+      stdio: ['pipe', 'pipe', 'ignore'],
+    },
+  )
+  let closeCb: (e?: Error) => void = () => {}
+  child.on('close', () => closeCb())
+  child.on('error', (e) => closeCb(e))
+  return {
+    write: (d) => void child.stdin!.write(d),
+    onData: (cb) => child.stdout!.on('data', cb),
+    onClose: (cb) => (closeCb = cb),
+    // Closing stdin is EOF to the agent, which then kills the step's group.
+    close: () => {
+      child.stdin!.end()
+      setTimeout(() => child.kill('SIGKILL'), 2000).unref()
+    },
+  }
+}
+
+export function startOci(
+  cfg: OciConfig,
+  work: string,
+  log: (line: string) => void = () => {},
+): Isolation {
+  const name = 'mirab-' + randomBytes(6).toString('hex'),
+    me = userInfo()
+  const setup = cfg.where ? COLIMA_NETWORK_SETUP : NETWORK_SETUP
+  const network = containerNetwork(
+    cfg.egress,
+    cfg.egress !== 'block' && egressNetworkReady(cfg.engine, cfg.host),
+    setup,
+  )
+  log(
+    network === 'none'
+      ? `container network: none, egress blocked (enable with: ${setup})`
+      : `container network: ${network}, egress allowed, LAN/host/metadata denied`,
+  )
+  execFileSync(
+    cfg.engine,
+    [
+      ...endpoint(cfg.host),
+      'run',
+      '-d',
+      '--rm',
+      '--name',
+      name,
+      // Hardening: no capabilities, no privilege gain, immutable root, bounded.
+      '--cap-drop',
+      'ALL',
+      '--security-opt',
+      'no-new-privileges',
+      '--read-only',
+      '--tmpfs',
+      '/tmp:rw,nosuid,size=512m',
+      '--pids-limit',
+      String(cfg.pids),
+      '--memory',
+      cfg.memory,
+      '--cpus',
+      cfg.cpus,
+      // No network unless the filtered mirab-egress bridge exists (set up by
+      // scripts/vm-network-setup.sh); never the default bridge.
+      '--network',
+      network,
+      '--user',
+      `${me.uid}:${me.gid}`,
+      '-v',
+      `${cfg.agent}:/mirab-guest-agent:ro`,
+      '-v',
+      `${work}:${GUEST_WORK}`,
+      '-w',
+      GUEST_WORK,
+      cfg.image,
+      'sleep',
+      'infinity',
+    ],
+    { stdio: 'ignore' },
+  )
+  const open: Opener = async () => execChannel(cfg.engine, name, cfg.host)
+  const inWork = (p: string) => p === work || p.startsWith(work + '/')
+  const guest = (p: string) =>
+    inWork(p) ? GUEST_WORK + p.slice(work.length) : p
+  return {
+    level: 'container',
+    backend: 'oci:' + cfg.engine + (cfg.where ? '@colima' : ''),
+    label: `container (${cfg.engine}${cfg.where ? ` in ${cfg.where}` : ''})`,
+    guestPath: guest,
+    put: (p, content, mode) => guestPut(open, guest(p), content, mode),
+    exec: (argv, o) => guestExec(open, argv, o),
+    close: async () => {
+      try {
+        execFileSync(cfg.engine, [...endpoint(cfg.host), 'rm', '-f', name], {
+          stdio: 'ignore',
+        })
+      } catch {}
+    },
+  }
+}