@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/machine.ts

@@ -0,0 +1,483 @@
+/**
+ * The public entry point: a {@link Machine} runs bash snippets under a policy,
+ * with behavior definitions, hooks and a trace event stream.
+ *
+ * ```ts
+ * const m = new Machine({ cwd, policy: { mode: 'workspace-write', workspaceRoot: cwd } })
+ * m.on((e) => console.log(e.type))
+ * const r = await m.run('ls | wc -l')
+ * ```
+ */
+
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type * as A from './parser/ast.ts'
+import { parse, lineColumn } from './parser/parser.ts'
+import { known, type AValue } from './analysis/value.ts'
+import { BehaviorRegistry, basename } from './behaviors/registry.ts'
+import { defaultBehaviors } from './behaviors/index.ts'
+import type { BehaviorResult, Invocation, ScriptInfo } from './behaviors/types.ts'
+import type { Effect } from './policy/effects.ts'
+import { checkCommandName, checkEffects, checkExecEffects, defaultPolicy, type Policy, type PolicyFinding } from './policy/policy.ts'
+import { asPossible, viaSuffix, withVia } from './policy/effects.ts'
+import type { CommandContext, HookDecision, Hooks, TraceEvent, TraceListener } from './trace/events.ts'
+import { defaultSpawn, type SpawnFn } from './vm/external.ts'
+import { defaultFdPassing, type FdPassing } from './vm/fifo.ts'
+import { Interpreter, type Assessment, type ExecIntent, type Runtime } from './vm/interp.ts'
+import { Capture, FdTable, HostStream, type Channel, type ChannelKind, type DataListener } from './vm/io.ts'
+import { AbortRun, Proc, type Job } from './vm/proc.ts'
+import { initShellVars, newVar, ShellState } from './vm/state.ts'
+import { analyzeScript, type AnalysisReport, type AnalyzeOptions } from './analysis/analyze.ts'
+
+export interface MachineOptions {
+  /** Initial working directory (default: process.cwd()). */
+  cwd?: string
+  /** Environment (default: process.env). */
+  env?: Record<string, string | undefined>
+  /** Sandbox policy (default: workspace-write rooted at cwd). */
+  policy?: Policy
+  behaviors?: BehaviorRegistry
+  hooks?: Hooks
+  /** Host stdin (default: empty). */
+  stdin?: AsyncIterable<Uint8Array | string>
+  /** Host stdout/stderr sinks. Default: captured and returned by `run`. */
+  stdout?: (chunk: Uint8Array) => void | Promise<void>
+  stderr?: (chunk: Uint8Array) => void | Promise<void>
+  /** Spawn function for external commands (wrap it to confine children). */
+  spawn?: SpawnFn
+  /** Report `data` events for every channel (pipes, redirections, captures). Default false. */
+  traceData?: boolean
+  /**
+   * What to do with background jobs still running when the script ends:
+   * `detach` (like bash: leave them running), `wait`, or `kill`. Default `wait`.
+   */
+  background?: 'detach' | 'wait' | 'kill'
+  /**
+   * Deny commands whose policy verdict is `unknown` (effects not provably
+   * allowed). Default false: unknown effects are allowed (the OS sandbox
+   * still confines them) but reported.
+   */
+  denyUnknown?: boolean
+  /** Status of a denied command (default 126). */
+  deniedStatus?: number
+  /** Abort the whole run on the first denial instead of failing the command. */
+  abortOnDeny?: boolean
+  /** Dry run: never execute external commands; report their predicted effects instead. */
+  dryRun?: boolean
+  /** `$0` (default `mash`). */
+  arg0?: string
+  /**
+   * Run nested `bash -c`, `bash file` and bash/sh shebang scripts inside the
+   * VM so their commands are traced and checked individually (default true).
+   */
+  inlineScripts?: boolean
+  /**
+   * Emulate `xargs` and `find -exec/-delete` inside the VM so every command
+   * they run is traced and checked individually (default true).
+   */
+  emulate?: boolean
+  /**
+   * How process substitutions and other `/dev/fd/N` arguments naming VM fds
+   * reach external commands. `devfd`: an extra stdio slot, passed as
+   * `/dev/fd/K` (works on macOS, where the child can open a socket by that
+   * name). `fifo`: a named FIFO in a private temp dir, passed by path (needed
+   * on Linux, where opening `/dev/fd/K` on a socket fails with ENXIO).
+   * Default: the `MASH_PROCSUBST` environment variable (`fifo`|`devfd`), else
+   * `devfd` on macOS and `fifo` elsewhere.
+   */
+  procSubst?: FdPassing
+}
+
+export interface RunOptions {
+  /** Positional parameters ($1...). */
+  args?: string[]
+  signal?: AbortSignal
+}
+
+export interface RunResult {
+  status: number
+  /** Captured output when no stdout/stderr sink was configured. */
+  stdout: string
+  stderr: string
+  /** Set when the run was aborted (policy abort or signal). */
+  aborted?: string
+  /** Commands denied by policy or hooks during the run. */
+  denials: { argv: string[]; reason: string }[]
+}
+
+interface SourceRecord {
+  firstId: number
+  lastId: number
+  text: string
+  origin: string
+}
+
+export class Machine {
+  readonly options: MachineOptions
+  readonly policy: Policy
+  readonly behaviors: BehaviorRegistry
+  private readonly listeners: TraceListener[] = []
+  private readonly dataListeners: DataListener[] = []
+  private nextId = 1
+  private readonly sources: SourceRecord[] = []
+  private channelCounter = 0
+  private pidCounter = 0
+  private execCounter = 0
+  private runCounter = 0
+  private readonly contexts = new Map<number, CommandContext>()
+
+  constructor(options: MachineOptions = {}) {
+    this.options = options
+    const cwd = path.resolve(options.cwd ?? process.cwd())
+    this.policy = options.policy ?? defaultPolicy(cwd)
+    this.behaviors = options.behaviors ?? defaultBehaviors()
+    this.behaviors.scriptAnalyzer ??= (source, positional, inv, info) => this.analyzeNested(source, positional, inv, info)
+    if (options.traceData) {
+      this.dataListeners.push((channel, bytes, direction) => this.emit({ type: 'data', channel, bytes, direction }))
+    }
+    this.pidCounter = 10000 + (process.pid % 1000) * 10
+  }
+
+  /** Subscribe to trace events. Returns an unsubscribe function. */
+  on(listener: TraceListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      const i = this.listeners.indexOf(listener)
+      if (i >= 0) this.listeners.splice(i, 1)
+    }
+  }
+
+  /** Tap the bytes flowing through every channel (pipes, redirections, captures, stdio). */
+  tap(listener: DataListener): () => void {
+    this.dataListeners.push(listener)
+    return () => {
+      const i = this.dataListeners.indexOf(listener)
+      if (i >= 0) this.dataListeners.splice(i, 1)
+    }
+  }
+
+  private emit(e: TraceEvent): void {
+    for (const l of this.listeners) {
+      try {
+        l(e)
+      } catch {
+        // listeners must not break execution
+      }
+    }
+  }
+
+  /** Parse source, registering it so trace consumers can map node ids back to text. */
+  parse(source: string, origin = 'script', opts: { partial?: boolean } = {}): A.Script {
+    const firstId = this.nextId
+    const script = parse(source, { firstId, partial: opts.partial })
+    this.nextId = script.id + 1
+    this.sources.push({ firstId, lastId: script.id, text: source, origin })
+    return script
+  }
+
+  private sourceOf(id: number): SourceRecord | undefined {
+    for (let i = this.sources.length - 1; i >= 0; i--) {
+      const s = this.sources[i]
+      if (id >= s.firstId && id <= s.lastId) return s
+    }
+    return undefined
+  }
+
+  /** Source text of a node. */
+  textOf(node: { id: number; span: A.Span }): string {
+    const s = this.sourceOf(node.id)
+    return s ? s.text.slice(node.span.start, node.span.end) : ''
+  }
+
+  /** Static analysis: predicted commands, effects and policy findings, without running anything. */
+  analyze(source: string | A.Script, options: Partial<AnalyzeOptions> = {}): AnalysisReport {
+    const script = typeof source === 'string' ? this.parse(source, 'analysis') : source
+    const text = typeof source === 'string' ? source : this.sourceOf(source.id)?.text ?? ''
+    const cwd = path.resolve(this.options.cwd ?? process.cwd())
+    return analyzeScript(script, text, {
+      cwd: known(cwd),
+      env: this.initialEnv(),
+      policy: this.policy,
+      behaviors: this.behaviors,
+      ...options,
+    })
+  }
+
+  private analyzeNested(source: AValue, positional: AValue[], inv: Invocation, info: ScriptInfo = {}): BehaviorResult {
+    const text = source.alts.length === 1 && source.alts[0].every((s) => typeof s === 'string') ? (source.alts[0] as string[]).join('') : undefined
+    if (text === undefined) return { effects: [{ kind: 'unknown', detail: 'script text is not known statically' }], complete: false }
+    const file = info.file ? path.normalize(info.file) : undefined
+    if (file && inv.mayHaveChanged?.(file)) return { effects: [{ kind: 'unknown', detail: `script ${file} may be changed by the snippet before it runs` }], complete: false }
+    let script: A.Script
+    try {
+      script = parse(text, { firstId: 2_000_000_000 })
+    } catch (e) {
+      return { effects: [{ kind: 'unknown', detail: `script does not parse: ${(e as Error).message}` }], complete: false }
+    }
+    const env: Record<string, string> = {}
+    const report = analyzeScript(script, text, {
+      cwd: inv.cwd,
+      env,
+      envValues: (n) => inv.env(n),
+      policy: this.policy,
+      behaviors: this.behaviors,
+      positional,
+      nested: true,
+    })
+    // Every effect says which inner command it comes from. Conditional (`may`)
+    // effects are only possible effects of the outer command: never a definite
+    // violation, and checked individually when the script runs.
+    // External commands become `exec` effects, so denied command names are seen.
+    const effects: Effect[] = report.commands.flatMap((c) => {
+      const own: Effect[] = c.kind === 'external' || c.kind === 'not-found' ? [{ kind: 'exec', argv: c.argv }, ...c.effects] : c.effects
+      return own.map((e) => {
+        const nested = withVia(e, { text: c.text, line: c.line, ...(file ? { file } : {}) })
+        return c.reach === 'may' ? asPossible(nested) : nested
+      })
+    })
+    return { effects, complete: report.commands.every((c) => c.complete), readsStdin: 'maybe' }
+  }
+
+  private initialEnv(): Record<string, string> {
+    const env: Record<string, string> = {}
+    for (const [k, v] of Object.entries(this.options.env ?? process.env)) if (v !== undefined) env[k] = v
+    return env
+  }
+
+  /** Run a snippet. */
+  async run(source: string | A.Script, opts: RunOptions = {}): Promise<RunResult> {
+    // bash reads scripts line by line: lines before a syntax error still run
+    const script = typeof source === 'string' ? this.parse(source, 'script', { partial: true }) : source
+    const runId = ++this.runCounter
+    const controller = new AbortController()
+    const external = opts.signal
+    const onExternalAbort = (): void => controller.abort()
+    external?.addEventListener('abort', onExternalAbort, { once: true })
+    if (external?.aborted) controller.abort()
+
+    const cwd = path.resolve(this.options.cwd ?? process.cwd())
+    const state = new ShellState(cwd)
+    for (const [k, v] of Object.entries(this.initialEnv())) state.globals.set(k, newVar({ kind: 'string', value: v }, { exported: true }))
+    state.globals.set('PWD', newVar({ kind: 'string', value: cwd }, { exported: true }))
+    if (!state.globals.has('HOME')) state.globals.set('HOME', newVar({ kind: 'string', value: os.homedir() }, { exported: true }))
+    const shlvl = Number(state.getString('SHLVL') ?? '0') + 1
+    state.globals.set('SHLVL', newVar({ kind: 'string', value: String(shlvl) }, { exported: true }))
+    initShellVars(state)
+    state.positional = opts.args ?? []
+    state.arg0 = this.options.arg0 ?? 'mash'
+
+    const stdoutCapture: Uint8Array[] = []
+    const stderrCapture: Uint8Array[] = []
+    const denials: RunResult['denials'] = []
+    const fds = new FdTable()
+    const dl = this.dataListeners
+    fds.set(0, new HostStream(this.channel('host', 'stdin'), dl, { input: this.options.stdin ?? (async function* () {})() }))
+    fds.set(1, new HostStream(this.channel('host', 'stdout'), dl, { write: this.options.stdout ?? ((c) => void stdoutCapture.push(c)) }))
+    fds.set(2, new HostStream(this.channel('host', 'stderr'), dl, { write: this.options.stderr ?? ((c) => void stderrCapture.push(c)) }))
+
+    const shellPid = this.nextPidValue()
+    const jobs = new Map<number, Job>()
+    const allJobs: Job[] = []
+    const tracked: Promise<unknown>[] = []
+    const proc = new Proc(state, fds, shellPid, process.pid, 0, jobs, false)
+
+    const rt: Runtime = {
+      emit: (e) => this.emit(e),
+      listeners: dl,
+      channel: (kind, label, extra) => this.channel(kind, label, extra),
+      nextPid: () => this.nextPidValue(),
+      nextExecId: () => ++this.execCounter,
+      shellPid,
+      assess: async (intent) => {
+        const a = await this.assess(intent)
+        if (a.action === 'deny' || a.action === 'abort') denials.push({ argv: intent.argv, reason: a.reason })
+        return a
+      },
+      assessRedirects: async (effects, node, p) => {
+        const a = await this.assessEffectsOnly(effects, node)
+        if (a.action === 'deny' || a.action === 'abort') denials.push({ argv: [this.textOf(node)], reason: a.reason })
+        return a
+      },
+      afterCommand: async (execId, status) => {
+        const ctx = this.contexts.get(execId)
+        this.contexts.delete(execId)
+        if (ctx && this.options.hooks?.afterCommand) await this.options.hooks.afterCommand(ctx, status)
+      },
+      spawn: this.options.spawn ?? defaultSpawn,
+      signal: controller.signal,
+      text: (node) => this.textOf(node),
+      line: (node) => {
+        const s = this.sourceOf(node.id)
+        return s ? lineColumn(s.text, node.span.start).line : 0
+      },
+      parse: (text, origin, opts) => this.parse(text, origin, opts),
+      findJob: (pid) => allJobs.find((j) => j.pid === pid),
+      track: (p) => void tracked.push(p.catch(() => {})),
+      registerJob: (job) => void allJobs.push(job),
+      inlineScripts: this.options.inlineScripts ?? true,
+      emulate: this.options.emulate ?? true,
+      fdPassing: this.options.procSubst ?? defaultFdPassing(),
+    }
+
+    const interp = new Interpreter(rt)
+    this.emit({ type: 'run:start', runId, pid: shellPid })
+    let status: number
+    let aborted: string | undefined
+    try {
+      status = await interp.runTop(script, proc)
+    } catch (e) {
+      if (e instanceof AbortRun) {
+        status = e.status
+        aborted = e.message
+        controller.abort()
+        for (const j of allJobs) j.kill()
+        const errText = `mash: aborted: ${e.message}\n`
+        await fds.get(2)?.write(errText).catch(() => {})
+      } else {
+        throw e
+      }
+    }
+    const bg = this.options.background ?? 'wait'
+    if (bg === 'wait') await Promise.all(allJobs.map((j) => j.done.catch(() => 0)))
+    else if (bg === 'kill') {
+      for (const j of allJobs) if (j.status === null) j.kill()
+      await Promise.all(allJobs.map((j) => j.done.catch(() => 0)))
+    }
+    if (bg !== 'detach') await Promise.all(tracked)
+    fds.closeAll()
+    external?.removeEventListener('abort', onExternalAbort)
+    this.emit({ type: 'run:end', runId, status })
+    const dec = new TextDecoder()
+    const join = (chunks: Uint8Array[]): string => chunks.map((c) => dec.decode(c, { stream: true })).join('') + dec.decode()
+    return { status, stdout: join(stdoutCapture), stderr: join(stderrCapture), aborted, denials }
+  }
+
+  private nextPidValue(): number {
+    return ++this.pidCounter
+  }
+
+  private channel(kind: ChannelKind, label: string, extra: Partial<Channel> = {}): Channel {
+    const ch: Channel = { id: ++this.channelCounter, kind, label, ...extra }
+    if (kind !== 'host' && kind !== 'null') this.emit({ type: 'channel:open', channel: ch })
+    return ch
+  }
+
+  // -------------------------------------------------------------------------
+  // Assessment: behavior → effects → policy → hooks
+  // -------------------------------------------------------------------------
+
+  /** Effects of a builtin (most have none). */
+  private builtinEffects(argv: string[], cwd: string, env: Record<string, string>): BehaviorResult {
+    const name = argv[0]
+    const resolve = (p: string): AValue => known(path.resolve(cwd, p))
+    switch (name) {
+      case 'cd':
+      case 'pushd':
+        return { effects: argv[1] && argv[1] !== '-' ? [{ kind: 'chdir', path: resolve(argv[1]) }] : [] }
+      case 'source':
+      case '.':
+        return { effects: argv[1] ? [{ kind: 'read', path: resolve(argv[1]) }] : [] }
+      case 'exec':
+      case 'command':
+      case 'builtin': {
+        const rest = argv.slice(1).filter((a, i) => !(i === 0 && a.startsWith('-')))
+        if (rest.length === 0 || argv.slice(1).some((a) => a === '-v' || a === '-V')) return { effects: [] }
+        return this.behaviors.analyze(this.invocation(rest, cwd, env))
+      }
+      case 'kill':
+        return { effects: [{ kind: 'process', detail: `kill ${argv.slice(1).join(' ')}` }] }
+      default:
+        return { effects: [] }
+    }
+  }
+
+  private invocation(argv: string[], cwd: string, env: Record<string, string>, stdin: Invocation['stdin'] = 'unknown'): Invocation {
+    return {
+      name: basename(argv[0]),
+      argv: argv.map(known),
+      cwd: known(cwd),
+      env: (n) => (env[n] === undefined ? undefined : known(env[n])),
+      stdin,
+    }
+  }
+
+  private async assess(intent: ExecIntent): Promise<Assessment> {
+    const policy = this.policy
+    let result: BehaviorResult
+    if (intent.kind === 'external') {
+      result = this.behaviors.analyze(this.invocation(intent.argv, intent.cwd, intent.env, intent.stdinKind))
+    } else if (intent.kind === 'builtin') {
+      result = this.builtinEffects(intent.argv, intent.cwd, intent.env)
+    } else {
+      result = { effects: [] }
+    }
+    const effects: Effect[] = [...intent.redirectEffects, ...result.effects]
+    const findings: PolicyFinding[] = checkEffects(effects, policy, { runtime: true })
+    const nameFinding = intent.kind === 'external' || intent.kind === 'not-found' ? checkCommandName(intent.argv[0], policy) : null
+    if (nameFinding) findings.unshift(nameFinding)
+    findings.unshift(...checkExecEffects(result.effects, policy))
+    const denied = findings.filter((f) => f.verdict === 'deny')
+    const unknown = findings.filter((f) => f.verdict === 'unknown')
+    let decision: 'allow' | 'deny' = denied.length > 0 || (this.options.denyUnknown && unknown.length > 0) ? 'deny' : 'allow'
+    const ctx: CommandContext = {
+      execId: intent.execId,
+      nodeId: intent.node.id,
+      span: intent.node.span,
+      text: this.textOf(intent.node),
+      argv: intent.argv,
+      kind: intent.kind,
+      path: intent.path,
+      cwd: intent.cwd,
+      env: intent.env,
+      effects,
+      effectsComplete: result.complete !== false,
+      findings,
+      decision,
+      pid: intent.pid,
+    }
+    this.contexts.set(intent.execId, ctx)
+    let hook: HookDecision | void = undefined
+    if (this.options.hooks?.beforeCommand) hook = await this.options.hooks.beforeCommand(ctx)
+    const reasonOf = (): string => (denied.length > 0 ? denied : unknown).map((f) => f.reason + viaSuffix(f.effect)).join('; ') || 'denied by policy'
+    const status = this.options.deniedStatus ?? 126
+    if (hook) {
+      switch (hook.action) {
+        case 'allow':
+          decision = 'allow'
+          break
+        case 'deny':
+          this.emit({ type: 'command:denied', execId: intent.execId, nodeId: intent.node.id, argv: intent.argv, reason: hook.reason, findings })
+          return { action: 'deny', reason: hook.reason, status: hook.status ?? status }
+        case 'abort':
+          this.emit({ type: 'command:denied', execId: intent.execId, nodeId: intent.node.id, argv: intent.argv, reason: hook.reason, findings })
+          return { action: 'abort', reason: hook.reason, status: hook.status ?? status }
+        case 'simulate':
+          return { action: 'simulate', stdout: hook.stdout ?? '', stderr: hook.stderr ?? '', status: hook.status ?? 0 }
+      }
+    }
+    if (decision === 'deny') {
+      const reason = `denied by policy: ${reasonOf()}`
+      this.emit({ type: 'command:denied', execId: intent.execId, nodeId: intent.node.id, argv: intent.argv, reason, findings })
+      return this.options.abortOnDeny ? { action: 'abort', reason, status } : { action: 'deny', reason, status }
+    }
+    if (this.options.dryRun && intent.kind === 'external') {
+      return { action: 'simulate', stdout: '', stderr: '', status: 0 }
+    }
+    return { action: 'run', readsStdin: result.readsStdin ?? 'maybe' }
+  }
+
+  private async assessEffectsOnly(effects: Effect[], node: A.Node): Promise<Assessment> {
+    if (effects.length === 0) return { action: 'run', readsStdin: 'maybe' }
+    const findings = checkEffects(effects, this.policy, { runtime: true })
+    const denied = findings.filter((f) => f.verdict === 'deny')
+    if (denied.length > 0) {
+      const reason = `denied by policy: ${denied.map((f) => f.reason + viaSuffix(f.effect)).join('; ')}`
+      this.emit({ type: 'command:denied', execId: 0, nodeId: node.id, argv: [this.textOf(node)], reason, findings })
+      const status = this.options.deniedStatus ?? 126
+      return this.options.abortOnDeny ? { action: 'abort', reason, status } : { action: 'deny', reason, status }
+    }
+    return { action: 'run', readsStdin: 'maybe' }
+  }
+}
+
+export { Capture }