@gpzhang2001/sharpkit-sandbox 0.2.1

package/src/session.ts

@@ -0,0 +1,444 @@
+/**
+ * One docker-CLI sandbox session: exec/PTY command execution, file transfer
+ * via `docker cp`, lazy Caido endpoint, and strix-parity teardown. The
+ * subprocess seam arrives as a structural interface so the session is
+ * drivable from tests exactly like the S1 spike drove it. Teardown follows
+ * strix session_manager.cleanup order (staging → caido → container), each
+ * step best-effort with logging; host-side PTY trees are terminated first
+ * (spike finding D1.4: host terminate cannot reach daemon-owned container
+ * processes, so `docker rm -f` is the authoritative reaper).
+ * @module @gpzhang2001/sharpkit-sandbox/session
+ */
+
+import { mkdtemp, readFile, rm, writeFile, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import type {
+  SubprocessHandle,
+  SubprocessSpawnSpec,
+  SubprocessTerminalHandle,
+  SubprocessTerminalSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import { CaidoBootstrap, type CaidoEndpoint } from './caido.ts'
+import { SandboxProcessId, type SandboxSessionId } from './brand.ts'
+import {
+  buildExecArgv,
+  buildExecTtyArgv,
+  buildGetFileArgv,
+  buildPutFileArgv,
+  buildRmArgv,
+  buildRmForceArgv,
+  buildStopArgv,
+  type SandboxBindMount,
+} from './spec.ts'
+
+/** Structural view of `ctx.subprocess` the session drives (S1 spike shape). */
+export interface SubprocessLike {
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle
+  spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>
+}
+
+/** Logger subset (cordis logger satisfies this structurally). */
+export interface SandboxLogger {
+  debug(message: string): void
+  info(message: string): void
+  warn(message: string): void
+  error(message: string): void
+}
+
+/** Options for a non-interactive exec. */
+export interface SandboxExecOptions {
+  /** Working directory inside the container. */
+  readonly cwd?: string | undefined
+  /** Per-call timeout; a timed-out command is terminated and reported. */
+  readonly timeoutMs?: number | undefined
+  /** Cooperative cancellation: aborting terminates the tree (tool exec.signal). */
+  readonly signal?: AbortSignal | undefined
+}
+
+/** Result of a non-interactive exec. */
+export interface SandboxExecResult {
+  readonly exitCode: number | null
+  readonly signal: string | null
+  readonly stdout: string
+  readonly stderr: string
+  /** True only when the deadline fired (caller cancellation is `aborted`). */
+  readonly timedOut: boolean
+  /** True when the caller's AbortSignal fired (cooperative cancellation). */
+  readonly aborted: boolean
+}
+
+/** One live PTY-backed interactive process. */
+export interface SandboxTtyProcess {
+  readonly id: SandboxProcessId
+  readonly command: string
+  /** Feed characters into the process (Ctrl-C arrives as `\x03`, finding D1.1). */
+  write(chars: string): Promise<void>
+  /** Subscribe to decoded output chunks; returns an unsubscribe function. */
+  subscribe(listener: (chunk: string) => void): () => void
+  /** Resolves when the process exits. */
+  readonly done: Promise<SandboxExecResult>
+  /** Terminate the host-side tree (container residue is reaped by session stop). */
+  terminate(): Promise<void>
+}
+
+/** The session contract consumed by the suite's tool packages. */
+export interface PentestSandboxSession {
+  readonly sessionId: SandboxSessionId
+  readonly scanId: string
+  readonly containerId: string
+  /** Await Caido readiness (the guest-login retry loop is the probe). */
+  ready(): Promise<void>
+  /** Run one command in a fresh non-interactive login shell. */
+  exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult>
+  /** Start a cancellable no-timeout exec for background jobs. */
+  execJob(command: string, options?: { readonly cwd?: string | undefined }): SandboxExecProcess
+  /** Start one PTY-backed interactive process (REPL/ssh/msfconsole). */
+  execTty(command: string, options?: { readonly cwd?: string | undefined; readonly rows?: number | undefined; readonly cols?: number | undefined }): Promise<SandboxTtyProcess>
+  /** Write characters to a live PTY process. */
+  writeStdin(processId: SandboxProcessId, chars: string): Promise<void>
+  /** Copy a host file into the container. */
+  putFile(hostPath: string, containerPath: string): Promise<void>
+  /** Read a container file out as raw bytes (binary-safe via docker cp). */
+  getFile(containerPath: string): Promise<Uint8Array>
+  /** The host-side Caido endpoint (resolves readiness first). */
+  caidoEndpoint(): Promise<CaidoEndpoint>
+  /** Best-effort teardown: PTYs, staging dir, caido, container. */
+  stop(): Promise<void>
+}
+
+/** Collected output read helper: reader text or ''. */
+function readerText(handle: SubprocessHandle, stream: 'stdout' | 'stderr'): string {
+  return handle.collected[stream]?.readFrom(0).text ?? ''
+}
+
+/**
+ * Run one argv to completion with collected output and a hard timeout that
+ * terminates (and joins) the tree — the primitive every docker CLI call in
+ * the session goes through. A timeout and a caller abort terminate the host
+ * tree identically but are reported separately (`timedOut` vs `aborted`);
+ * per spike finding D1.4, host-side termination cannot reach daemon-owned
+ * container processes — a timed-out `docker exec` may leave its command
+ * running inside the container until the session stops and reaps it.
+ * @param subprocess - the subprocess seam.
+ * @param argv - full argv, argv[0] a program (never shell-interpreted).
+ * @param options - timeout and terminate grace.
+ * @returns the collected outcome.
+ */
+export async function runCollectArgv(
+  subprocess: SubprocessLike,
+  argv: readonly string[],
+  options: { readonly timeoutMs: number; readonly graceMs: number; readonly collectMaxBytes: number; readonly signal?: AbortSignal | undefined },
+): Promise<SandboxExecResult> {
+  const handle = subprocess.spawn({
+    argv,
+    cwd: process.cwd(),
+    stdio: {
+      stdin: 'ignore',
+      stdout: { maxBytes: options.collectMaxBytes },
+      stderr: { maxBytes: options.collectMaxBytes },
+    },
+    graceMs: options.graceMs,
+  })
+  let timedOut = false
+  let aborted = false
+  let timer: NodeJS.Timeout | undefined
+  let onAbort: (() => void) | undefined
+  const deadline = new Promise<'deadline'>(resolve => {
+    timer = setTimeout(() => {
+      timedOut = true
+      handle.terminate()
+      resolve('deadline')
+    }, options.timeoutMs)
+    const signal = options.signal
+    if (signal !== undefined) {
+      onAbort = () => {
+        aborted = true
+        handle.terminate()
+        resolve('deadline')
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+  })
+  const winner = await Promise.race([handle.done.then(outcome => ({ outcome })), deadline.then(() => 'deadline' as const)])
+  if (timer !== undefined) clearTimeout(timer)
+  if (onAbort !== undefined) options.signal?.removeEventListener('abort', onAbort)
+  const outcome = winner === 'deadline' ? await handle.done : winner.outcome
+  return {
+    exitCode: outcome.exitCode,
+    signal: outcome.signal,
+    stdout: readerText(handle, 'stdout'),
+    stderr: readerText(handle, 'stderr'),
+    timedOut,
+    aborted,
+  }
+}
+
+/** Internal record of one live PTY process. */
+interface TtyRecord {
+  readonly process: SandboxTtyProcess
+  readonly handle: SubprocessTerminalHandle
+  readonly listeners: Set<(chunk: string) => void>
+}
+
+/** A cancellable long-running non-interactive exec (jobs integration). */
+export interface SandboxExecProcess {
+  readonly processId: SandboxProcessId
+  /** Resolves with the full collected outcome after the tree settles. */
+  readonly done: Promise<SandboxExecResult>
+  /** Consuming delta of stdout since the previous call ('' when nothing new). */
+  readOutput(): string
+  /** Terminate the host-side tree; `done` then settles with the partial output. */
+  terminate(): void
+}
+
+/** Knobs the service hands each session (resolved Config values). */
+export interface SandboxSessionDeps {
+  readonly subprocess: SubprocessLike
+  readonly logger: SandboxLogger
+  readonly containerId: string
+  readonly scanId: string
+  readonly containerCaidoBaseUrl: string
+  readonly hostCaidoBaseUrl: string
+  readonly bootstrap: CaidoBootstrap
+  /** Extra-file staging directory to remove on stop (undefined when none). */
+  readonly stagingDir?: string | undefined
+  readonly graceMs: number
+  readonly defaultExecTimeoutMs: number
+  readonly collectMaxBytes: number
+}
+
+/**
+ * The docker-CLI-backed {@link PentestSandboxSession}. Constructed by the
+ * service after the container is created and started; never constructed
+ * directly by consumers.
+ */
+export class DockerCliSandboxSession implements PentestSandboxSession {
+  readonly sessionId: SandboxSessionId
+  readonly scanId: string
+  readonly containerId: string
+  private readonly deps: SandboxSessionDeps
+  private readonly ttyProcesses = new Map<SandboxProcessId, TtyRecord>()
+  private stopped = false
+
+  constructor(deps: SandboxSessionDeps) {
+    this.deps = deps
+    this.sessionId = crypto.randomUUID() as SandboxSessionId
+    this.scanId = deps.scanId
+    this.containerId = deps.containerId
+  }
+
+  async ready(): Promise<void> {
+    await this.deps.bootstrap.get()
+  }
+
+  async caidoEndpoint(): Promise<CaidoEndpoint> {
+    return this.deps.bootstrap.get()
+  }
+
+  async exec(command: string, options?: SandboxExecOptions): Promise<SandboxExecResult> {
+    if (this.stopped) throw new Error(`sandbox session for scan ${this.scanId} is stopped`)
+    const timeoutMs = options?.timeoutMs ?? this.deps.defaultExecTimeoutMs
+    return runCollectArgv(this.deps.subprocess, buildExecArgv({ containerId: this.containerId, command, cwd: options?.cwd }), {
+      timeoutMs,
+      graceMs: this.deps.graceMs,
+      collectMaxBytes: this.deps.collectMaxBytes,
+      signal: options?.signal,
+    })
+  }
+
+  /**
+   * Start a cancellable long-running exec with no timeout (jobs own the
+   * lifetime): the caller polls {@link SandboxExecProcess.readOutput} deltas
+   * and terminates on cancel.
+   */
+  execJob(command: string, options?: { readonly cwd?: string | undefined }): SandboxExecProcess {
+    if (this.stopped) throw new Error(`sandbox session for scan ${this.scanId} is stopped`)
+    const handle = this.deps.subprocess.spawn({
+      argv: buildExecArgv({ containerId: this.containerId, command, cwd: options?.cwd }),
+      cwd: process.cwd(),
+      stdio: {
+        stdin: 'ignore',
+        stdout: { maxBytes: this.deps.collectMaxBytes },
+        stderr: { maxBytes: this.deps.collectMaxBytes },
+      },
+      graceMs: this.deps.graceMs,
+    })
+    let offset = 0
+    const processId = SandboxProcessId(crypto.randomUUID())
+    const done = handle.done.then(outcome => {
+      const stdout = handle.collected.stdout?.readFrom(0).text ?? ''
+      const stderr = handle.collected.stderr?.readFrom(0).text ?? ''
+      return { exitCode: outcome.exitCode, signal: outcome.signal, stdout, stderr, timedOut: false, aborted: false }
+    })
+    return {
+      processId,
+      done,
+      readOutput: () => {
+        const read = handle.collected.stdout?.readFrom(offset)
+        if (read === undefined) return ''
+        offset = read.nextOffset
+        return read.text
+      },
+      terminate: () => {
+        handle.terminate()
+      },
+    }
+  }
+
+  async execTty(command: string, options?: { readonly cwd?: string | undefined; readonly rows?: number | undefined; readonly cols?: number | undefined }): Promise<SandboxTtyProcess> {
+    if (this.stopped) throw new Error(`sandbox session for scan ${this.scanId} is stopped`)
+    const handle = await this.deps.subprocess.spawnTerminal({
+      argv: buildExecTtyArgv({ containerId: this.containerId, command, cwd: options?.cwd }),
+      cwd: process.cwd(),
+      rows: options?.rows ?? 24,
+      cols: options?.cols ?? 80,
+      graceMs: this.deps.graceMs,
+    })
+    const id = SandboxProcessId(crypto.randomUUID())
+    const listeners = new Set<(chunk: string) => void>()
+    const decoder = new TextDecoder()
+    handle.output.on('data', (chunk: Uint8Array) => {
+      const text = decoder.decode(chunk, { stream: true })
+      for (const listener of listeners) listener(text)
+    })
+    const done = handle.done.then(outcome => ({
+      exitCode: outcome.exitCode,
+      signal: outcome.signal,
+      stdout: '',
+      stderr: '',
+      timedOut: false,
+      aborted: false,
+    }))
+    const record: TtyRecord = {
+      handle,
+      listeners,
+      process: {
+        id,
+        command,
+        write: chars => handle.write(chars),
+        subscribe: listener => {
+          listeners.add(listener)
+          return () => {
+            listeners.delete(listener)
+          }
+        },
+        done,
+        terminate: () => handle.terminate(),
+      },
+    }
+    this.ttyProcesses.set(id, record)
+    void done.then(
+      () => {
+        this.ttyProcesses.delete(id)
+      },
+      () => {
+        this.ttyProcesses.delete(id)
+      },
+    )
+    return record.process
+  }
+
+  async writeStdin(processId: SandboxProcessId, chars: string): Promise<void> {
+    const record = this.ttyProcesses.get(processId)
+    if (record === undefined) throw new Error(`write_stdin: no live interactive process ${processId} in scan ${this.scanId}`)
+    await record.handle.write(chars)
+  }
+
+  async putFile(hostPath: string, containerPath: string): Promise<void> {
+    const result = await runCollectArgv(this.deps.subprocess, buildPutFileArgv(hostPath, this.containerId, containerPath), {
+      timeoutMs: this.deps.defaultExecTimeoutMs,
+      graceMs: this.deps.graceMs,
+      collectMaxBytes: this.deps.collectMaxBytes,
+    })
+    if (result.exitCode !== 0) throw new Error(`putFile failed (exit ${result.exitCode}): ${result.stderr.slice(0, 500)}`)
+  }
+
+  async getFile(containerPath: string): Promise<Uint8Array> {
+    const name = basename(containerPath)
+    if (name === '' || name === '/' || name === '.') throw new Error(`getFile: container path must name a file: ${containerPath}`)
+    const dir = await mkdtemp(join(tmpdir(), 'sharpkit-getfile-'))
+    try {
+      const hostPath = join(dir, name)
+      const result = await runCollectArgv(this.deps.subprocess, buildGetFileArgv(this.containerId, containerPath, hostPath), {
+        timeoutMs: this.deps.defaultExecTimeoutMs,
+        graceMs: this.deps.graceMs,
+        collectMaxBytes: this.deps.collectMaxBytes,
+      })
+      if (result.exitCode !== 0) throw new Error(`getFile failed (exit ${result.exitCode}): ${result.stderr.slice(0, 500)}`)
+      return new Uint8Array(await readFile(hostPath))
+    } finally {
+      await rm(dir, { recursive: true, force: true }).catch(() => {})
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.stopped) return
+    this.stopped = true
+    const log = this.deps.logger
+    for (const record of this.ttyProcesses.values()) {
+      try {
+        await record.handle.terminate()
+      } catch (error) {
+        log.debug(`stop(${this.scanId}): tty terminate raised: ${String(error)}`)
+      }
+    }
+    this.ttyProcesses.clear()
+    if (this.deps.stagingDir !== undefined) {
+      await rm(this.deps.stagingDir, { recursive: true, force: true }).catch(() => {})
+    }
+    this.deps.bootstrap.close()
+    try {
+      const stopped = await runCollectArgv(this.deps.subprocess, buildStopArgv(this.containerId, this.deps.graceMs), {
+        timeoutMs: this.deps.defaultExecTimeoutMs,
+        graceMs: this.deps.graceMs,
+        collectMaxBytes: this.deps.collectMaxBytes,
+      })
+      if (stopped.exitCode !== 0) log.warn(`stop(${this.scanId}): docker stop exit ${stopped.exitCode}: ${stopped.stderr.slice(0, 200)}`)
+    } catch (error) {
+      log.debug(`stop(${this.scanId}): docker stop raised: ${String(error)}`)
+    }
+    try {
+      const removed = await runCollectArgv(this.deps.subprocess, buildRmArgv(this.containerId), {
+        timeoutMs: this.deps.defaultExecTimeoutMs,
+        graceMs: this.deps.graceMs,
+        collectMaxBytes: this.deps.collectMaxBytes,
+      })
+      if (removed.exitCode !== 0) {
+        await runCollectArgv(this.deps.subprocess, buildRmForceArgv(this.containerId), {
+          timeoutMs: this.deps.defaultExecTimeoutMs,
+          graceMs: this.deps.graceMs,
+          collectMaxBytes: this.deps.collectMaxBytes,
+        })
+      }
+    } catch (error) {
+      log.error(`stop(${this.scanId}): container removal raised; container may need manual reaping: ${String(error)}`)
+    }
+  }
+}
+
+/**
+ * Stage extra files for bind mounting (strix `build_extra_file_bind_mounts`):
+ * one numbered subdir per file, content written, mounted read-only at its
+ * workspace path.
+ * @param stagingDir - the session staging directory (already created).
+ * @param items - validated extra files: rel path + bytes.
+ * @param workspaceRoot - container workspace root (default `/workspace`).
+ * @returns the mounts, in placement order.
+ */
+export async function stageExtraFiles(
+  stagingDir: string,
+  items: readonly { readonly rel: string; readonly content: Uint8Array }[],
+  workspaceRoot: string,
+): Promise<SandboxBindMount[]> {
+  const mounts: SandboxBindMount[] = []
+  let index = 0
+  for (const item of items) {
+    const staged = join(stagingDir, String(index), basename(item.rel))
+    await mkdir(dirname(staged), { recursive: true })
+    await writeFile(staged, item.content)
+    mounts.push({ source: staged, target: `${workspaceRoot}/${item.rel}`, readOnly: true })
+    index++
+  }
+  return mounts
+}