mirab 0.0.0-stage → 0.2.0

package/src/isolation/policy.ts

@@ -0,0 +1,86 @@
+// Isolation policy: which level a run gets, and when it is refused.
+//
+// Levels, strongest first. `none` is never picked automatically: it needs an
+// explicit request and is labelled unisolated everywhere it is shown.
+export const LEVELS = ['vm', 'container', 'host', 'none'] as const
+export type Level = (typeof LEVELS)[number]
+
+export const strength = (level: Level) => LEVELS.length - LEVELS.indexOf(level)
+
+export type RequestSource = 'flag' | 'job' | 'profile' | 'host-default' | 'auto'
+
+export interface PolicyInput {
+  /** `--isolation` on this run. Most specific, wins over everything below. */
+  flag?: Level
+  /** `isolation:` on the workflow job. */
+  job?: Level
+  /** `isolation` in the agent profile. */
+  profile?: Level
+  /** The host default the owner set once in the host config. */
+  hostDefault?: Level
+  /** Owner floor: levels weaker than this are refused, never upgraded. */
+  floor?: Level
+  /** Backends usable on this machine. */
+  available: readonly Level[]
+}
+
+export interface Resolved {
+  level: Level
+  source: RequestSource
+  /** Set when the requested level could not be had and a weaker tier took the run. */
+  fallback?: string
+}
+
+export class IsolationRefused extends Error {}
+
+export function parseLevel(
+  text: string | undefined,
+  where: string,
+): Level | undefined {
+  if (text === undefined) return undefined
+  if ((LEVELS as readonly string[]).includes(text)) return text as Level
+  throw new IsolationRefused(
+    `${where}: unknown isolation "${text}" (use ${LEVELS.join(', ')})`,
+  )
+}
+
+export function resolveIsolation(input: PolicyInput): Resolved {
+  const asked: [Level | undefined, RequestSource][] = [
+    [input.flag, 'flag'],
+    [input.job, 'job'],
+    [input.profile, 'profile'],
+    [input.hostDefault, 'host-default'],
+  ]
+  const hit = asked.find(([level]) => level !== undefined)
+  const floor = input.floor
+  let chosen: Resolved
+  if (hit) {
+    chosen = { level: hit[0]!, source: hit[1] }
+  } else {
+    // Nothing asked: strongest available level that satisfies the floor.
+    const auto = LEVELS.filter((l) => l !== 'none').find((l) =>
+      input.available.includes(l),
+    )
+    if (auto && (!floor || strength(auto) >= strength(floor)))
+      return { level: auto, source: 'auto' }
+    throw new IsolationRefused(
+      floor
+        ? `this host requires isolation "${floor}" or stronger and none is available (available: ${input.available.join(', ') || 'none'})`
+        : `no isolation backend is available on this host (tried vm, container, host)`,
+    )
+  }
+  if (floor && strength(chosen.level) < strength(floor))
+    throw new IsolationRefused(
+      `isolation "${chosen.level}" (from ${chosen.source}) is below this host's floor "${floor}"`,
+    )
+  if (!input.available.includes(chosen.level))
+    throw new IsolationRefused(
+      `isolation "${chosen.level}" (from ${chosen.source}) is not available on this host (available: ${input.available.join(', ') || 'none'})`,
+    )
+  return chosen
+}
+
+export const labelFor = (level: Level, backend: string) =>
+  level === 'none'
+    ? 'unisolated (runs as the runner user)'
+    : `${level} (${backend})`

package/src/isolation/session.ts

@@ -0,0 +1,385 @@
+// One exec contract for every isolation backend (see guest-agent/src/main.rs).
+// A backend only has to open a byte channel to the guest agent; the runner and
+// spawn code talk to `Isolation` and never branch on the backend.
+import type { Level } from './policy'
+import shared from './guest-protocol.json'
+
+/** The guest-agent wire protocol this CLI speaks; guest-agent/src/main.rs reads the same file. */
+export const GUEST_PROTOCOL: number = shared.protocol
+/** Where the guest image is rebuilt from; printed with every mismatch. */
+export const REBUILD_HINT =
+  process.platform === 'darwin'
+    ? 'Rebuild the guest image from a mirab checkout at this version: `scripts/build-vm-guest.sh <dir>` (docs/VM.md)'
+    : 'Rebuild the guest image from a mirab checkout at this version: `bun run vm:image` (docs/VM.md)'
+
+export interface Channel {
+  write(data: Uint8Array): void
+  onData(cb: (chunk: Buffer) => void): void
+  onClose(cb: (error?: Error) => void): void
+  close(): void
+}
+
+export interface ExecOptions {
+  cwd: string
+  env: Record<string, string>
+  timeoutMs: number
+  signal: AbortSignal
+  /** One call per output line (stdout and stderr), already de-framed. */
+  onLine: (line: string) => Promise<void>
+}
+
+export interface Isolation {
+  readonly level: Level
+  readonly backend: string
+  /** What `mirab status` and job logs print. */
+  readonly label: string
+  /** Host path of the job work directory -> where the guest sees it. */
+  guestPath(hostPath: string): string
+  put(
+    hostPath: string,
+    content: string | Uint8Array,
+    mode?: number,
+  ): Promise<void>
+  /** Run a step; resolves with its exit code (124 timeout, 130 cancelled). */
+  exec(argv: string[], options: ExecOptions): Promise<number>
+  /** Interactive program on a guest pty (spawn --vm). */
+  pty?(request: PtyRequest): Promise<PtyHandle>
+  /** Read the guest file tree (working-directory sync); backends without a copy omit it. */
+  files?: GuestFiles
+  /** Messages the guest initiates toward the host on a vsock port (hooks). */
+  onGuestMessage?(port: number, handler: (message: any) => void): void
+  /** Serve the VM's guest-to-host `port` (e.g. the station's egress): `serve`
+   *  listens on the socket path given, which belongs to this VM alone. */
+  onGuestConnect?(
+    port: number,
+    serve: (socketPath: string) => Promise<import('node:net').Server>,
+  ): Promise<void>
+  /** Stop the backend; preserve its workspace for recovery after incomplete sync. */
+  close(options?: {
+    preserveWorkspace?: boolean
+    /** Keep this VM's root disk (its own copy) at this path once it has
+     *  stopped: how an agent's image is built and updated. */
+    keepRoot?: string
+  }): Promise<void>
+}
+
+/** One entry under a sync root, the same shape the guest agent's `list` op returns. */
+export interface Entry {
+  /** Path relative to the root, `/`-separated. */
+  p: string
+  /** `f` regular file, `d` directory, `l` symlink. */
+  k: 'f' | 'd' | 'l'
+  /** Permission bits (0 for symlinks). */
+  m: number
+  s?: number
+  /** sha256 hex of the content (files). */
+  h?: string
+  /** Link target (symlinks). */
+  t?: string
+}
+
+export interface GuestFiles {
+  list(root: string): Promise<Entry[]>
+  read(path: string): Promise<Buffer>
+}
+
+export interface PtyRequest {
+  argv: string[]
+  env: Record<string, string>
+  cwd: string
+  cols: number
+  rows: number
+}
+
+export interface PtyHandle {
+  write(data: Uint8Array | string): void
+  resize(cols: number, rows: number): void
+  onData(cb: (data: Buffer) => void): void
+  onExit(cb: (code: number) => void): void
+  /** Drop the connection: the guest hangs up the session. */
+  close(): void
+}
+
+export type Opener = () => Promise<Channel>
+
+const MAX_LINE = 32768
+
+function frame(value: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(value))
+  const head = Buffer.alloc(4)
+  head.writeUInt32BE(body.length)
+  return Buffer.concat([head, body])
+}
+
+type Reply =
+  | { t: 'out' | 'err'; d: string }
+  | { t: 'entries'; e: Entry[] }
+  | { t: 'exit'; code: number; timed_out: boolean }
+  | { t: 'ok'; protocol?: number; agent?: string }
+  | { t: 'error'; message: string }
+
+/** Send one request and stream replies until `done` returns a value. */
+function converse<T>(
+  open: Opener,
+  request: unknown,
+  signal: AbortSignal | undefined,
+  onReply: (r: Reply) => T | undefined | Promise<T | undefined>,
+): Promise<T> {
+  return new Promise<T>(async (resolve, reject) => {
+    let ch: Channel
+    try {
+      ch = await open()
+    } catch (e) {
+      return reject(e)
+    }
+    let buf = Buffer.alloc(0),
+      finished = false,
+      chain = Promise.resolve()
+    const end = (fn: () => void) => {
+      if (finished) return
+      finished = true
+      signal?.removeEventListener('abort', abort)
+      fn()
+      ch.close()
+    }
+    const abort = () => ch.close() // guest kills the step when the connection drops
+    signal?.addEventListener('abort', abort, { once: true })
+    ch.onData((chunk) => {
+      buf = Buffer.concat([buf, chunk])
+      while (buf.length >= 4 && buf.length >= 4 + buf.readUInt32BE(0)) {
+        const n = buf.readUInt32BE(0)
+        const reply = JSON.parse(buf.subarray(4, 4 + n).toString()) as Reply
+        buf = buf.subarray(4 + n)
+        chain = chain.then(async () => {
+          if (finished) return
+          try {
+            const out = await onReply(reply)
+            if (out !== undefined) end(() => resolve(out))
+          } catch (e) {
+            end(() => reject(e))
+          }
+        })
+      }
+    })
+    ch.onClose((error) => {
+      chain = chain.then(() =>
+        end(() => reject(error ?? new Error('guest connection closed early'))),
+      )
+    })
+    ch.write(frame(request))
+  })
+}
+
+export interface GuestHello {
+  /** 1 for agents that predate the handshake (their ping reply has no number). */
+  protocol: number
+  agent?: string
+}
+
+export async function guestPing(open: Opener): Promise<GuestHello> {
+  return converse<GuestHello>(open, { op: 'ping' }, undefined, (r) =>
+    r.t === 'ok'
+      ? {
+          protocol: typeof r.protocol === 'number' ? r.protocol : 1,
+          agent: r.agent,
+        }
+      : undefined,
+  )
+}
+
+export class GuestProtocolError extends Error {}
+
+/** Refuse a guest agent that speaks another protocol, at connect time and
+ *  with the fix, instead of failing mid-session on an op it lacks. */
+export function checkGuestProtocol(hello: GuestHello, image: string) {
+  if (hello.protocol === GUEST_PROTOCOL) return
+  const agent = `mirab-guest-agent ${hello.agent ?? '(no version, before 0.2.0)'}`
+  throw new GuestProtocolError(
+    hello.protocol < GUEST_PROTOCOL
+      ? `The guest image ${image} is outdated: its ${agent} speaks protocol ${hello.protocol}, this mirab needs ${GUEST_PROTOCOL}. ${REBUILD_HINT}.`
+      : `The guest image ${image} is newer than this mirab: its ${agent} speaks protocol ${hello.protocol}, this mirab speaks ${GUEST_PROTOCOL}. Update mirab, or ${REBUILD_HINT.charAt(0).toLowerCase() + REBUILD_HINT.slice(1)}.`,
+  )
+}
+
+export async function guestPut(
+  open: Opener,
+  path: string,
+  content: string | Uint8Array,
+  mode = 0o600,
+) {
+  await converse<true>(
+    open,
+    { op: 'put', path, mode, content: Buffer.from(content).toString('base64') },
+    undefined,
+    (r) => {
+      if (r.t === 'error') throw new Error(r.message)
+      return r.t === 'ok' ? true : undefined
+    },
+  )
+}
+
+export function guestFiles(open: Opener): GuestFiles {
+  return {
+    async list(root) {
+      const all: Entry[] = []
+      await converse<true>(open, { op: 'list', root }, undefined, (r) => {
+        if (r.t === 'error') throw new Error(r.message)
+        if (r.t === 'entries') all.push(...r.e)
+        return r.t === 'ok' ? true : undefined
+      })
+      return all
+    },
+    async read(path) {
+      const parts: Buffer[] = []
+      await converse<true>(open, { op: 'get', path }, undefined, (r) => {
+        if (r.t === 'error') throw new Error(r.message)
+        if (r.t === 'out') parts.push(Buffer.from(r.d, 'base64'))
+        return r.t === 'ok' ? true : undefined
+      })
+      return Buffer.concat(parts)
+    },
+  }
+}
+
+export async function guestExec(
+  open: Opener,
+  argv: string[],
+  o: ExecOptions,
+): Promise<number> {
+  if (o.signal.aborted) return 130
+  const pending = { out: '', err: '' },
+    decoders = { out: new TextDecoder(), err: new TextDecoder() }
+  let failure: Error | undefined
+  const feed = async (which: 'out' | 'err', data: Buffer) => {
+    pending[which] += decoders[which].decode(data, { stream: true })
+    let at: number
+    while ((at = pending[which].indexOf('\n')) >= 0) {
+      if (at > MAX_LINE) return tooLong(which)
+      await o.onLine(pending[which].slice(0, at).replace(/\r$/, ''))
+      pending[which] = pending[which].slice(at + 1)
+    }
+    if (pending[which].length > MAX_LINE) tooLong(which)
+  }
+  // Same rule as host steps: never emit the tail of an oversized line, it could
+  // be half of a secret split across chunks.
+  const tooLong = (which: 'out' | 'err') => {
+    failure = new Error('output line exceeds 32 KiB')
+    pending[which] = ''
+    ctl.abort()
+  }
+  const ctl = new AbortController(),
+    relay = () => ctl.abort()
+  o.signal.addEventListener('abort', relay, { once: true })
+  try {
+    const code = await converse<number>(
+      open,
+      { op: 'exec', argv, env: o.env, cwd: o.cwd, timeout_ms: o.timeoutMs },
+      ctl.signal,
+      async (r) => {
+        if (failure) return undefined
+        if (r.t === 'out' || r.t === 'err') {
+          await feed(r.t, Buffer.from(r.d, 'base64'))
+          return undefined
+        }
+        if (r.t === 'error') throw new Error(r.message)
+        if (r.t === 'exit') {
+          for (const w of ['out', 'err'] as const) {
+            pending[w] += decoders[w].decode()
+            if (pending[w]) await o.onLine(pending[w])
+          }
+          if (r.timed_out)
+            await o.onLine(
+              `[mirab: step timeout after ${o.timeoutMs / 60000} minutes]`,
+            )
+          return r.code
+        }
+        return undefined
+      },
+    ).catch((e) => {
+      if (failure) throw failure
+      if (o.signal.aborted) return 130
+      throw e
+    })
+    if (failure) throw failure
+    return code
+  } finally {
+    o.signal.removeEventListener('abort', relay)
+  }
+}
+
+export async function guestPty(
+  open: Opener,
+  request: PtyRequest,
+): Promise<PtyHandle> {
+  const ch = await open()
+  // Every onData listener sees every byte (a detached session has two: the
+  // output log and the quiet detector). Output that arrives before the first
+  // listener is held for it, and an exit that comes before onExit is replayed.
+  let buf = Buffer.alloc(0),
+    exitCode: number | undefined,
+    pending: Buffer[] | undefined = []
+  const dataCbs: ((d: Buffer) => void)[] = [],
+    exitCbs: ((code: number) => void)[] = []
+  const emit = (d: Buffer) => {
+    if (pending) pending.push(d)
+    else for (const cb of dataCbs) cb(d)
+  }
+  const done = (code: number) => {
+    if (exitCode !== undefined) return
+    exitCode = code
+    for (const cb of exitCbs) cb(code)
+  }
+  ch.onData((chunk) => {
+    buf = Buffer.concat([buf, chunk])
+    while (buf.length >= 4 && buf.length >= 4 + buf.readUInt32BE(0)) {
+      const n = buf.readUInt32BE(0)
+      const r = JSON.parse(buf.subarray(4, 4 + n).toString()) as Reply
+      buf = buf.subarray(4 + n)
+      if (r.t === 'out') emit(Buffer.from(r.d, 'base64'))
+      else if (r.t === 'exit') done(r.code)
+      else if (r.t === 'error') {
+        emit(Buffer.from(`mirab: ${r.message}\r\n`))
+        done(127)
+      }
+    }
+  })
+  ch.onClose(() => done(129))
+  ch.write(frame({ op: 'pty', ...request }))
+  return {
+    write: (d) =>
+      ch.write(frame({ t: 'in', d: Buffer.from(d).toString('base64') })),
+    resize: (cols, rows) => ch.write(frame({ t: 'resize', cols, rows })),
+    onData: (cb) => {
+      dataCbs.push(cb)
+      if (!pending) return
+      const held = pending
+      pending = undefined
+      for (const d of held) cb(d)
+    },
+    onExit: (cb) => {
+      exitCbs.push(cb)
+      if (exitCode !== undefined) cb(exitCode)
+    },
+    close: () => ch.close(),
+  }
+}
+
+/** Read one length-prefixed JSON message from a connection the guest opened. */
+export function readOneMessage(stream: {
+  on(event: 'data', cb: (c: Buffer) => void): unknown
+}): Promise<any> {
+  return new Promise((resolve, reject) => {
+    let buf = Buffer.alloc(0)
+    stream.on('data', (chunk) => {
+      buf = Buffer.concat([buf, chunk])
+      if (buf.length >= 4 && buf.length >= 4 + buf.readUInt32BE(0))
+        try {
+          resolve(
+            JSON.parse(buf.subarray(4, 4 + buf.readUInt32BE(0)).toString()),
+          )
+        } catch (e) {
+          reject(e)
+        }
+    })
+  })
+}