@gpzhang2001/sharpkit-sandbox 0.2.1

package/src/index.ts

@@ -0,0 +1,366 @@
+/**
+ * Docker sandbox capability for the sharpkit pentest suite: the
+ * `ctx.pentestSandbox` service (decision D1: `ctx.subprocess` + docker CLI,
+ * argv built by the pure spec module). Port of strix runtime/session_manager
+ * `create_or_reuse` + `cleanup` semantics: sessions cached by scan id,
+ * container lifecycle over the CLI, extra files staged under the temp dir
+ * (a remote docker daemon resolves bind sources on its own filesystem), and
+ * a lazy Caido bootstrap that runs concurrently with scan start. Teardown is
+ * registered once via ctx.effect and stops every live session best-effort.
+ * @module @gpzhang2001/sharpkit-sandbox
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context, Service } from '@deepseek-ai/cordis'
+import type Schema from '@deepseek-ai/schemastery'
+import z from '@deepseek-ai/schemastery'
+import { bootstrapCaido, CaidoBootstrap } from './caido.ts'
+import {
+  buildBindMounts,
+  collidesWithRoots,
+  extraFileRelPath,
+  stagingDirName,
+  type FsProbe,
+  type SandboxSourceSpec,
+} from './mounts.ts'
+import {
+  buildCreateArgv,
+  buildContainerEnv,
+  buildImageInspectArgv,
+  buildNetworkIpArgv,
+  buildPortArgv,
+  buildPullArgv,
+  buildStartArgv,
+  parsePortOutput,
+  type SandboxCreateSpec,
+} from './spec.ts'
+import {
+  DockerCliSandboxSession,
+  runCollectArgv,
+  stageExtraFiles,
+  type PentestSandboxSession,
+} from './session.ts'
+
+export type {
+  PentestSandboxSession,
+  SandboxExecOptions,
+  SandboxExecResult,
+  SandboxTtyProcess,
+} from './session.ts'
+export type { CaidoBootstrap, CaidoEndpoint } from './caido.ts'
+export type { SandboxSourceSpec } from './mounts.ts'
+export { SandboxProcessId, SandboxSessionId } from './brand.ts'
+export type { SandboxProcessId as SandboxProcessIdType, SandboxSessionId as SandboxSessionIdType } from './brand.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    pentestSandbox: PentestSandboxService
+  }
+}
+
+/** One extra file materialized into the workspace before container start. */
+export interface SandboxExtraFile {
+  /** Absolute container path under the workspace root. */
+  readonly containerPath: string
+  /** File content; strings are encoded UTF-8. */
+  readonly content: string | Uint8Array
+}
+
+/** Options for {@link PentestSandboxService.createSession}. */
+export interface SandboxSessionOptions {
+  /** Cache key; repeated ids reuse the live session (strix create_or_reuse). */
+  readonly scanId: string
+  /** Source trees to bind-mount read-write into the workspace. */
+  readonly sources?: readonly SandboxSourceSpec[]
+  /** Extra files staged on the host and mounted read-only into the workspace. */
+  readonly extraFiles?: readonly SandboxExtraFile[]
+}
+
+/** Deployment-tunable configuration (cordis resolves defaults before apply). */
+export interface Config {
+  /** Sandbox image reference. */
+  readonly image?: string
+  /** Terminate grace for every docker CLI tree the session owns. */
+  readonly containerGraceMs?: number
+  /** Container workspace root (protocol constant with the image). */
+  readonly workspaceRoot?: string
+  /** Existing docker network to attach to (publishes no ports; strix sandbox-network mode). */
+  readonly network?: string
+  /** Resource limits (strix STRIX_SANDBOX_* env knobs, now config). */
+  readonly memLimit?: string
+  readonly shmSize?: string
+  readonly cpus?: number
+  readonly pidsLimit?: number
+  /** Log rotation; max-size 0/off/none/unlimited disables (strix default "50m"/3). */
+  readonly logMaxSize?: string
+  readonly logMaxFile?: number
+  /** Run labels forwarded to the container (strix STRIX_RUN_ID/RUN_TYPE). */
+  readonly runLabelId?: string
+  readonly runLabelType?: string
+  /** Caido guest-login retry budget (the readiness probe). */
+  readonly caidoLoginAttempts?: number
+  /** Per-attempt login exec timeout. */
+  readonly caidoLoginTimeoutMs?: number
+  /** Default timeout for exec and docker CLI helper calls. */
+  readonly defaultExecTimeoutMs?: number
+  /** Collect window for exec stdout/stderr (bytes; larger streams go lossy). */
+  readonly execCollectMaxBytes?: number
+}
+
+/** Resolved shape cordis hands the constructor after schema defaults. */
+type ResolvedConfig = Required<Omit<Config, 'network' | 'memLimit' | 'shmSize' | 'cpus' | 'pidsLimit' | 'runLabelId' | 'runLabelType'>>
+  & Pick<Config, 'network' | 'memLimit' | 'shmSize' | 'cpus' | 'pidsLimit' | 'runLabelId' | 'runLabelType'>
+
+/** Container-side Caido port (protocol constant with the image, not a tunable). */
+const CAIDO_PORT = 48080
+
+/** Keep-alive command (protocol with the image entrypoint, which execs it). */
+const KEEPALIVE_COMMAND = ['tail', '-f', '/dev/null'] as const
+
+/**
+ * The pentest sandbox service: creates, caches, and reuses docker-CLI
+ * sandbox sessions. Load as a plugin after a subprocess provider; it
+ * registers as `ctx.pentestSandbox` (one per context).
+ */
+export class PentestSandboxService extends Service {
+  static inject = ['subprocess']
+
+  static Config: Schema<Config> = z.object({
+    image: z.string().default('ghcr.io/gpzhang2001/sharpkit-sandbox:1.0.0-fork2'),
+    containerGraceMs: z.number().default(10_000),
+    workspaceRoot: z.string().default('/workspace'),
+    network: z.string(),
+    memLimit: z.string(),
+    shmSize: z.string(),
+    cpus: z.number(),
+    pidsLimit: z.number(),
+    logMaxSize: z.string().default('50m'),
+    logMaxFile: z.number().default(3),
+    runLabelId: z.string(),
+    runLabelType: z.string(),
+    caidoLoginAttempts: z.number().default(10),
+    caidoLoginTimeoutMs: z.number().default(15_000),
+    defaultExecTimeoutMs: z.number().default(120_000),
+    execCollectMaxBytes: z.number().default(1_048_576),
+  })
+
+  private readonly config: ResolvedConfig
+  private readonly sessions = new Map<string, PentestSandboxSession>()
+
+  /** node:fs-backed mount facts; a handful of sync calls on a few paths. */
+  private readonly probe: FsProbe = {
+    // pathlib.Path.resolve parity: expanduser + symlink-following canonicalization.
+    resolve: path => realpathSync(path.startsWith('~/') ? join(homedir(), path.slice(2)) : path),
+    exists: path => existsSync(path),
+    isDirectory: path => {
+      try {
+        return statSync(path).isDirectory()
+      } catch {
+        return false
+      }
+    },
+    isFile: path => {
+      try {
+        return statSync(path).isFile()
+      } catch {
+        return false
+      }
+    },
+    readTextFile: path => {
+      try {
+        return readFileSync(path, 'utf8')
+      } catch {
+        return null
+      }
+    },
+  }
+
+  constructor(ctx: Context, config: Config = {}) {
+    super(ctx, 'pentestSandbox')
+    this.config = config as ResolvedConfig
+    void ctx.effect(() => async () => {
+      for (const session of this.sessions.values()) {
+        await session.stop()
+      }
+      this.sessions.clear()
+    }, 'pentest-sandbox session teardown')
+  }
+
+  /**
+   * Create (or reuse) the sandbox session for a scan id — strix
+   * `create_or_reuse` parity, including lazy Caido bootstrap.
+   * @param options - scan identity, sources, extra files.
+   * @returns the live session.
+   */
+  async createSession(options: SandboxSessionOptions): Promise<PentestSandboxSession> {
+    const cached = this.sessions.get(options.scanId)
+    if (cached !== undefined) {
+      this.ctx.logger.debug(`pentest-sandbox: reusing session for scan ${options.scanId}`)
+      return cached
+    }
+    const config = this.config
+    const subprocess = this.ctx.subprocess
+    const cli = { timeoutMs: config.defaultExecTimeoutMs, graceMs: config.containerGraceMs, collectMaxBytes: config.execCollectMaxBytes }
+    let stagingDir: string | undefined
+    let containerId: string | undefined
+    try {
+      const mounts = buildBindMounts(options.sources ?? [], this.probe, config.workspaceRoot)
+      const extraMounts = await this.stageExtraFiles(options, config.workspaceRoot)
+      if (extraMounts.stagingDir !== undefined) stagingDir = extraMounts.stagingDir
+      const allMounts = [...mounts, ...extraMounts.mounts].sort(
+        (a, b) => a.target.split('/').length - b.target.split('/').length || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0),
+      )
+      const labels: Record<string, string> = {}
+      if (config.runLabelId !== undefined) labels['sharpkit-run-id'] = config.runLabelId
+      if (config.runLabelType !== undefined) labels['sharpkit-run-type'] = config.runLabelType
+      const spec: SandboxCreateSpec = {
+        image: config.image,
+        command: KEEPALIVE_COMMAND,
+        env: buildContainerEnv({
+          caidoPort: CAIDO_PORT,
+          platform: process.platform,
+          uid: typeof process.getuid === 'function' ? process.getuid() : undefined,
+          gid: typeof process.getgid === 'function' ? process.getgid() : undefined,
+        }),
+        bindMounts: allMounts,
+        caidoPort: CAIDO_PORT,
+        network: config.network,
+        caps: ['NET_ADMIN', 'NET_RAW'],
+        extraHosts: { 'host.docker.internal': 'host-gateway' },
+        resourceLimits: {
+          memLimit: config.memLimit,
+          shmSize: config.shmSize,
+          cpus: config.cpus,
+          pidsLimit: config.pidsLimit,
+        },
+        logMaxSize: config.logMaxSize,
+        logMaxFile: config.logMaxFile,
+        labels,
+      }
+      await this.ensureImage(spec.image, cli)
+      const created = await runCollectArgv(subprocess, buildCreateArgv(spec), cli)
+      if (created.exitCode !== 0) throw new Error(`docker create failed (exit ${created.exitCode}): ${created.stderr.slice(0, 500)}`)
+      containerId = created.stdout.trim().split('\n').at(-1)?.trim() ?? ''
+      if (containerId === '') throw new Error('docker create produced no container id')
+      const started = await runCollectArgv(subprocess, buildStartArgv(containerId), cli)
+      if (started.exitCode !== 0) throw new Error(`docker start failed (exit ${started.exitCode}): ${started.stderr.slice(0, 500)}`)
+      const hostBaseUrl = await this.resolveCaidoHostUrl(containerId, cli)
+      const id = containerId
+      const bootstrap = new CaidoBootstrap(signal =>
+        bootstrapCaido(
+          (command, timeoutMs) =>
+            runCollectArgv(subprocess, ['docker', 'exec', '-i', id, 'bash', '-lc', command], { ...cli, timeoutMs }).then(result => ({
+              ok: result.exitCode === 0,
+              exitCode: result.exitCode,
+              stdout: result.stdout,
+              stderr: result.stderr,
+            })),
+          fetch,
+          { containerBaseUrl: `http://127.0.0.1:${CAIDO_PORT}`, hostBaseUrl },
+          {
+            attempts: config.caidoLoginAttempts,
+            timeoutMs: config.caidoLoginTimeoutMs,
+            sleep: ms => new Promise(resolveSleep => setTimeout(resolveSleep, ms)),
+            signal,
+          },
+        ),
+      )
+      const session = new DockerCliSandboxSession({
+        subprocess,
+        logger: this.ctx.logger,
+        containerId,
+        scanId: options.scanId,
+        containerCaidoBaseUrl: `http://127.0.0.1:${CAIDO_PORT}`,
+        hostCaidoBaseUrl: hostBaseUrl,
+        bootstrap,
+        stagingDir,
+        graceMs: config.containerGraceMs,
+        defaultExecTimeoutMs: config.defaultExecTimeoutMs,
+        collectMaxBytes: config.execCollectMaxBytes,
+      })
+      this.sessions.set(options.scanId, session)
+      return session
+    } catch (error) {
+      // strix parity: drop staging, best-effort container removal, re-raise.
+      if (stagingDir !== undefined) await rm(stagingDir, { recursive: true, force: true }).catch(() => {})
+      if (containerId !== undefined) {
+        await runCollectArgv(subprocess, ['docker', 'rm', '-f', containerId], cli).catch(() => undefined)
+      }
+      throw error
+    }
+  }
+
+  /** Stop and forget one session (idempotent; strix `cleanup`). */
+  async destroySession(scanId: string): Promise<void> {
+    const session = this.sessions.get(scanId)
+    if (session === undefined) {
+      this.ctx.logger.debug(`pentest-sandbox: no session to clean for scan ${scanId}`)
+      return
+    }
+    this.sessions.delete(scanId)
+    await session.stop()
+  }
+
+  /** Validate + stage extra files (strix skip-and-warn semantics). */
+  private async stageExtraFiles(
+    options: SandboxSessionOptions,
+    workspaceRoot: string,
+  ): Promise<{ mounts: ReturnType<typeof buildBindMounts>; stagingDir?: string }> {
+    const extraFiles = options.extraFiles ?? []
+    if (extraFiles.length === 0) return { mounts: [] }
+    const sourceRoots = options.sources?.map(source => source.workspaceSubdir) ?? []
+    const placed: string[] = []
+    const items: { rel: string; content: Uint8Array }[] = []
+    for (const file of extraFiles) {
+      const rel = extraFileRelPath(file.containerPath, workspaceRoot)
+      if (rel === null) {
+        this.ctx.logger.warn(`pentest-sandbox: skipping invalid extra file path ${file.containerPath}`)
+        continue
+      }
+      if (collidesWithRoots(rel, [...sourceRoots, ...placed])) {
+        this.ctx.logger.warn(`pentest-sandbox: skipping colliding extra file ${file.containerPath}`)
+        continue
+      }
+      placed.push(rel)
+      items.push({ rel, content: typeof file.content === 'string' ? new TextEncoder().encode(file.content) : file.content })
+    }
+    if (items.length === 0) return { mounts: [] }
+    const stagingDir = await mkdtemp(`${tmpdir()}/pentest-extra-files-${stagingDirName(options.scanId)}-`)
+    return { mounts: await stageExtraFiles(stagingDir, items, workspaceRoot), stagingDir }
+  }
+
+  /** Pull the image when missing (strix image_exists → pull). */
+  private async ensureImage(image: string, cli: { timeoutMs: number; graceMs: number; collectMaxBytes: number }): Promise<void> {
+    const present = await runCollectArgv(this.ctx.subprocess, buildImageInspectArgv(image), { ...cli, timeoutMs: 60_000 })
+    if (present.exitCode === 0) return
+    this.ctx.logger.info(`pentest-sandbox: pulling image ${image}`)
+    const pulled = await runCollectArgv(this.ctx.subprocess, buildPullArgv(image), { ...cli, timeoutMs: 1_800_000 })
+    if (pulled.exitCode !== 0) throw new Error(`docker pull failed (exit ${pulled.exitCode}): ${pulled.stderr.slice(0, 500)}`)
+  }
+
+  /** Resolve the host-side Caido base URL for a started container. */
+  private async resolveCaidoHostUrl(
+    containerId: string,
+    cli: { timeoutMs: number; graceMs: number; collectMaxBytes: number },
+  ): Promise<string> {
+    const config = this.config
+    if (config.network !== undefined && config.network !== '') {
+      const inspected = await runCollectArgv(this.ctx.subprocess, buildNetworkIpArgv(containerId, config.network), cli)
+      if (inspected.exitCode !== 0) throw new Error(`docker inspect (network ip) failed (exit ${inspected.exitCode}): ${inspected.stderr.slice(0, 500)}`)
+      const ip = inspected.stdout.trim()
+      if (ip === '') throw new Error(`container has no address on network ${config.network}`)
+      const host = ip.includes(':') ? `[${ip}]` : ip
+      return `http://${host}:${CAIDO_PORT}`
+    }
+    const port = await runCollectArgv(this.ctx.subprocess, buildPortArgv(containerId, CAIDO_PORT), cli)
+    if (port.exitCode !== 0) throw new Error(`docker port failed (exit ${port.exitCode}): ${port.stderr.slice(0, 500)}`)
+    const endpoint = parsePortOutput(port.stdout)[0]
+    if (endpoint === undefined) throw new Error(`caido port ${CAIDO_PORT} is not published for container ${containerId}`)
+    return `http://${endpoint.host}:${endpoint.port}`
+  }
+}
+
+export default PentestSandboxService

package/src/mounts.ts

@@ -0,0 +1,197 @@
+/**
+ * Bind-mount assembly: workspace source mapping, protected-metadata mounts
+ * (`.git` / `.agents` / `.codex`, git-worktree gitdir pointers), extra-file
+ * staging path rules, and collision detection. Faithful port of strix
+ * session_manager.py `build_bind_mounts` (:54-66), `_metadata_mounts`
+ * (:230-245), `_gitdir_from_pointer` (:248-260), `_extra_file_rel_path`
+ * (:80-97), `_collides_with_source_root` (:111-124), and the staging-dir
+ * sanitizer (:172-180). Filesystem facts arrive through an injectable probe
+ * so every branch is unit-testable without touching a real tree.
+ * @module @gpzhang2001/sharpkit-sandbox/mounts
+ */
+
+import type { SandboxBindMount } from './spec.ts'
+
+/** One source tree mounted into the sandbox workspace. */
+export interface SandboxSourceSpec {
+  /** Directory name under the workspace root (`/workspace/<subdir>`). */
+  readonly workspaceSubdir: string
+  /** Host path of the tree to mount. */
+  readonly sourcePath: string
+  /** Mount `.git`/`.agents`/`.codex` (and worktree gitdir) read-only on top. */
+  readonly protectMetadata?: boolean
+}
+
+/** Injected filesystem facts; the real service passes node:fs-backed probes. */
+export interface FsProbe {
+  /** Resolve a path to its canonical absolute form (symlinks followed). */
+  resolve(path: string): string
+  exists(path: string): boolean
+  isDirectory(path: string): boolean
+  /** Whether the path exists as a regular file (a worktree `.git` pointer). */
+  isFile(path: string): boolean
+  /** Read a small text file, or null when unreadable (pointer parse is best-effort). */
+  readTextFile(path: string): string | null
+}
+
+/** Metadata names that get their own read-only overlay mount. */
+export const PROTECTED_METADATA_NAMES = ['.git', '.agents', '.codex'] as const
+
+/**
+ * Whether `child` is `parent` itself or underneath it, POSIX-style.
+ * @param parent - candidate ancestor path, already canonical.
+ * @param child - candidate descendant path, already canonical.
+ */
+export function isSubpath(parent: string, child: string): boolean {
+  return child === parent || child.startsWith(`${parent}/`)
+}
+
+/**
+ * Parse a git worktree `.git` pointer file for its `gitdir:` line.
+ * @param content - the raw pointer file text.
+ * @param base - directory of the pointer file, for relative gitdir values.
+ * @param resolve - canonicalizer for the candidate path.
+ * @returns the resolved gitdir, or null when absent/malformed.
+ */
+export function parseGitdirPointer(content: string, base: string, resolve: (path: string) => string): string | null {
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trimEnd()
+    const separator = line.indexOf(':')
+    if (separator === -1) continue
+    const prefix = line.slice(0, separator).trim()
+    if (prefix !== 'gitdir') continue
+    const value = line.slice(separator + 1).trim()
+    if (value === '') continue
+    return resolve(value.startsWith('/') ? value : `${base}/${value}`)
+  }
+  return null
+}
+
+/**
+ * Build the read-only metadata overlay mounts for one source tree (strix
+ * `_metadata_mounts`): each protected name that exists in the tree is mounted
+ * read-only at `<target>/<name>`; a file-shaped `.git` (worktree pointer)
+ * additionally gets its resolved gitdir mounted read-only when the gitdir
+ * stays inside the tree.
+ * @param tree - canonical host path of the source tree.
+ * @param target - container mount target of the tree (e.g. `/workspace/app`).
+ * @param probe - filesystem facts.
+ * @returns the overlay mounts (possibly empty).
+ */
+export function metadataMounts(tree: string, target: string, probe: FsProbe): SandboxBindMount[] {
+  const mounts: SandboxBindMount[] = []
+  for (const name of PROTECTED_METADATA_NAMES) {
+    const path = `${tree}/${name}`
+    if (!probe.exists(path)) continue
+    const isDir = probe.isDirectory(path)
+    if (!isDir && !probe.isFile(path)) continue
+    const resolved = probe.resolve(path)
+    if (!isSubpath(tree, resolved)) continue
+    mounts.push({ source: resolved, target: `${target}/${name}`, readOnly: true })
+    if (!isDir) {
+      const content = probe.readTextFile(path)
+      if (content === null) continue
+      const gitdir = parseGitdirPointer(content, path.substring(0, path.lastIndexOf('/')), probe.resolve)
+      if (gitdir === null || !probe.exists(gitdir) || !isSubpath(tree, gitdir)) continue
+      const relative = gitdir.slice(tree.length + 1)
+      mounts.push({ source: gitdir, target: `${target}/${relative}`, readOnly: true })
+    }
+  }
+  return mounts
+}
+
+/**
+ * Build every bind mount for the session's sources: workspace mounts plus
+ * metadata overlays, sorted shallowest-target-first so nested targets land on
+ * top (strix sort by `/` count).
+ * @param sources - the source specs; entries missing either path part are skipped.
+ * @param probe - filesystem facts.
+ * @param workspaceRoot - container workspace root (default `/workspace`).
+ * @returns the sorted mounts.
+ */
+export function buildBindMounts(
+  sources: readonly SandboxSourceSpec[],
+  probe: FsProbe,
+  workspaceRoot: string,
+): SandboxBindMount[] {
+  const mounts: SandboxBindMount[] = []
+  for (const source of sources) {
+    if (source.workspaceSubdir === '' || source.sourcePath === '') continue
+    const resolved = probe.resolve(source.sourcePath)
+    const target = `${workspaceRoot}/${source.workspaceSubdir}`
+    mounts.push({ source: resolved, target, readOnly: false })
+    if (source.protectMetadata === true) mounts.push(...metadataMounts(resolved, target, probe))
+  }
+  return mounts.sort((a, b) => targetDepth(a.target) - targetDepth(b.target) || (a.target < b.target ? -1 : a.target > b.target ? 1 : 0))
+}
+
+/** Path depth = number of `/` separators (strix ordering metric). */
+function targetDepth(target: string): number {
+  let depth = 0
+  for (const char of target) {
+    if (char === '/') depth++
+  }
+  return depth
+}
+
+/**
+ * Validate an extra file's container path (strix `_extra_file_rel_path`):
+ * must live under the workspace root, have no empty/`.`/`..` segments, and
+ * carry no control characters.
+ * @param containerPath - the requested absolute container path.
+ * @param workspaceRoot - container workspace root (default `/workspace`).
+ * @returns the workspace-relative path, or null when invalid.
+ */
+export function extraFileRelPath(containerPath: string, workspaceRoot: string): string | null {
+  const prefix = `${workspaceRoot}/`
+  if (!containerPath.startsWith(prefix)) return null
+  const rel = containerPath.slice(prefix.length).replace(/^\/+/, '')
+  if (rel === '') return null
+  const segments = rel.split('/')
+  for (const segment of segments) {
+    if (segment === '' || segment === '.' || segment === '..') return null
+    for (const char of segment) {
+      const code = char.codePointAt(0)
+      if (code === undefined || code < 0x20 || code === 0x7f) return null
+    }
+  }
+  return rel
+}
+
+/**
+ * Whether a candidate workspace-relative path collides with any source root
+ * or previously placed extra file (strix `_collides_with_source_root`,
+ * ancestor relationships included).
+ * @param rel - candidate workspace-relative path.
+ * @param roots - existing roots (subdirs and placed extra files), workspace-relative.
+ */
+export function collidesWithRoots(rel: string, roots: readonly string[]): boolean {
+  return roots.some(root => rel === root || rel.startsWith(`${root}/`) || root.startsWith(`${rel}/`))
+}
+
+/**
+ * Sanitize a scan id for a staging directory name (strix keeps `[alnum]-_.`,
+ * everything else becomes `-`).
+ * @param scanId - the raw scan id.
+ * @returns the sanitized name fragment (empty collapses to a single `-`).
+ */
+export function stagingDirName(scanId: string): string {
+  let safe = ''
+  for (const char of scanId) {
+    safe += /[A-Za-z0-9]/.test(char) || char === '-' || char === '_' || char === '.' ? char : '-'
+  }
+  return safe === '' ? '-' : safe
+}
+
+/**
+ * The staged host path for one extra file (strix: numbered subdir + basename,
+ * so same-basename files cannot clobber each other).
+ * @param stagingDir - the session's staging directory.
+ * @param index - the extra file's placement index.
+ * @param rel - the validated workspace-relative path.
+ * @returns the host file path to write the content to.
+ */
+export function stagedFilePath(stagingDir: string, index: number, rel: string): string {
+  const basename = rel.slice(rel.lastIndexOf('/') + 1)
+  return `${stagingDir}/${index}/${basename}`
+}