@anionex/dsh-vision-toolkit 0.1.39 → 0.1.40

package/src/paths.ts

@@ -6,9 +6,10 @@
  * @module dsh-vision-toolkit/paths
  */
 
-import { randomUUID } from 'node:crypto'
-import { cp, link, lstat, mkdir, readdir, realpath, rename, rm, stat } from 'node:fs/promises'
-import { extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import type { Stats } from 'node:fs'
+import { cp, link, lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, stat } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
 import { homedir, tmpdir } from 'node:os'
 import { VisionToolkitError } from './errors.ts'
 
@@ -23,10 +24,22 @@ export interface PathPolicy {
   tempDir: string
   /** Real allowed roots: workspace, platform temp, and configured directories. */
   allowedDirs: string[]
+  /** Real plugin-managed root containing artifacts and transient files. */
+  storageRoot: string
   /** Real plugin-managed output directory inside the fence. */
   outputDir: string
 }
 
+/** Resolved plugin storage for one workspace. */
+export interface WorkspaceStorage {
+  /** Real workspace root. */
+  workspace: string
+  /** Real plugin-managed root for this workspace. */
+  root: string
+  /** Absolute user-visible spelling of the same managed root. */
+  visibleRoot: string
+}
+
 /** Whether `child` equals or lies under `parent` on the same path root. */
 export function isWithin(parent: string, child: string): boolean {
   const rel = relative(parent, child)
@@ -65,26 +78,231 @@ export function normalizePlatformTempPath(
   return win32.join(tempDirectory, raw.slice('/tmp/'.length))
 }
 
+/** Stable opaque per-user workspace id used below a shared storage root. */
+export function workspaceStorageId(
+  workspace: string,
+  userIdentity: string = typeof process.geteuid === 'function'
+    ? `uid:${process.geteuid()}`
+    : `home:${homedir()}`,
+): string {
+  return createHash('sha256')
+    .update(userIdentity)
+    .update('\0')
+    .update(workspace)
+    .digest('hex')
+    .slice(0, 20)
+}
+
+function currentPosixUid(): number {
+  if (typeof process.geteuid !== 'function') {
+    throw new VisionToolkitError(
+      'path',
+      'configured storage directory is not supported on this platform because ownership and permissions cannot be verified',
+    )
+  }
+  return process.geteuid()
+}
+
+export function assertSecureWorkspaceStorage(info: Stats, requested: string): void {
+  const currentUid = currentPosixUid()
+  if (info.uid !== currentUid || (info.mode & 0o777) !== 0o700) {
+    throw new VisionToolkitError('path', `workspace storage directory must be owned by the current user with mode 0700: ${requested}`)
+  }
+}
+
+/** Resolve a shared base and prove every POSIX ancestor is protected from replacement. */
+export async function assertSecureSharedStorageBase(requested: string): Promise<string> {
+  const currentUid = currentPosixUid()
+  const requestedPath = resolve(requested)
+  const requestedChain: string[] = []
+  let requestedCurrent = requestedPath
+  while (true) {
+    requestedChain.push(requestedCurrent)
+    const parent = dirname(requestedCurrent)
+    if (parent === requestedCurrent) break
+    requestedCurrent = parent
+  }
+  for (const component of requestedChain.reverse()) {
+    const info = await lstat(component)
+    if (info.isSymbolicLink()) {
+      if (info.uid !== 0) {
+        throw new VisionToolkitError('path', `configured storage directory contains an untrusted symbolic link: ${component}`)
+      }
+      continue
+    }
+    if (!info.isDirectory()) {
+      throw new VisionToolkitError('path', `configured storage path component is not a directory: ${component}`)
+    }
+    const writableByOthers = (info.mode & 0o022) !== 0
+    const sticky = (info.mode & 0o1000) !== 0
+    if (
+      (info.uid !== currentUid && info.uid !== 0)
+      || (writableByOthers && !sticky)
+    ) throw new VisionToolkitError('path', `configured storage directory has an untrusted path component: ${component}`)
+  }
+  const canonical = await realpath(requestedPath)
+  let current = canonical
+  while (true) {
+    const info = await lstat(current)
+    const writableByOthers = (info.mode & 0o022) !== 0
+    const sticky = (info.mode & 0o1000) !== 0
+    if (
+      info.isSymbolicLink()
+      || !info.isDirectory()
+      || (info.uid !== currentUid && info.uid !== 0)
+      || (writableByOthers && !sticky)
+    ) throw new VisionToolkitError('path', `configured storage directory has an untrusted path component: ${current}`)
+    const parent = dirname(current)
+    if (parent === current) return canonical
+    current = parent
+  }
+}
+
+function requestedSharedStorageBase(storageDirRaw: string): string {
+  currentPosixUid()
+  const configured = normalizePlatformTempPath(expandUserHome(storageDirRaw.trim()))
+  if (!isAbsolute(configured)) {
+    throw new VisionToolkitError('path', `configured storage directory must be an absolute path: ${storageDirRaw}`)
+  }
+  return resolve(configured)
+}
+
+async function ensureSharedStorageBase(storageDirRaw: string): Promise<{ requestedBase: string; base: string }> {
+  const requestedBase = requestedSharedStorageBase(storageDirRaw)
+  try {
+    await mkdir(requestedBase, { recursive: true, mode: 0o700 })
+  } catch (error) {
+    throw new VisionToolkitError('path', `configured storage directory is not writable: ${requestedBase}`, { cause: error })
+  }
+  try {
+    return { requestedBase, base: await assertSecureSharedStorageBase(requestedBase) }
+  } catch (error) {
+    throw new VisionToolkitError('path', `configured storage directory is not accessible: ${requestedBase}`, { cause: error })
+  }
+}
+
+/** Validate and write-probe a configured shared root before Settings activation. */
+export async function preflightSharedStorageBase(storageDirRaw: string): Promise<string> {
+  const { base } = await ensureSharedStorageBase(storageDirRaw)
+  let probe: string | undefined
+  let failure: unknown
+  try {
+    probe = await mkdtemp(join(base, '.dsh-vision-toolkit-preflight-'))
+    assertSecureWorkspaceStorage(await lstat(probe), probe)
+  } catch (error) {
+    failure = error
+  }
+  if (probe !== undefined) {
+    try {
+      await rm(probe, { recursive: true, force: true })
+    } catch (error) {
+      failure ??= error
+    }
+  }
+  if (failure !== undefined) {
+    throw new VisionToolkitError('path', `configured storage directory failed its write preflight: ${base}`, { cause: failure })
+  }
+  return base
+}
+
+async function managedDirectory(
+  parent: string,
+  requested: string,
+  label: string,
+  secureWorkspaceStorage = false,
+): Promise<string> {
+  try {
+    await mkdir(requested, { mode: 0o700 })
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) {
+      throw new VisionToolkitError('path', `${label} is not writable: ${requested}`, { cause: error })
+    }
+  }
+  let info
+  try {
+    info = await lstat(requested)
+  } catch (error) {
+    throw new VisionToolkitError('path', `${label} is not accessible: ${requested}`, { cause: error })
+  }
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new VisionToolkitError('path', `${label} must be a real directory: ${requested}`)
+  }
+  if (secureWorkspaceStorage) assertSecureWorkspaceStorage(info, requested)
+  const canonical = await realpath(requested)
+  if (!isWithin(parent, canonical)) {
+    throw new VisionToolkitError('path', `${label} escaped its configured root: ${requested}`)
+  }
+  return canonical
+}
+
+/**
+ * Resolve the plugin-managed root for one workspace. Blank configuration keeps
+ * the legacy workspace-local `.dsh-vision-toolkit` directory. A configured
+ * shared root receives one stable, automatically generated workspace child.
+ */
+export async function resolveWorkspaceStorage(
+  workspaceRaw: string,
+  storageDirRaw?: string,
+): Promise<WorkspaceStorage> {
+  const expandedWorkspace = expandUserHome(workspaceRaw)
+  const visibleWorkspace = resolve(expandedWorkspace)
+  let workspace: string
+  try {
+    workspace = await realpath(visibleWorkspace)
+  } catch (error) {
+    throw new VisionToolkitError('path', `workspace is not accessible: ${workspaceRaw}`, { cause: error })
+  }
+
+  if (storageDirRaw === undefined || storageDirRaw.trim().length === 0) {
+    const visibleRoot = join(visibleWorkspace, '.dsh-vision-toolkit')
+    const root = await managedDirectory(workspace, visibleRoot, 'plugin storage directory')
+    return { workspace, root, visibleRoot }
+  }
+
+  const { requestedBase, base } = await ensureSharedStorageBase(storageDirRaw)
+  const id = workspaceStorageId(workspace)
+  const visibleRoot = join(requestedBase, id)
+  const root = await managedDirectory(base, join(base, id), 'workspace storage directory', true)
+  return { workspace, root, visibleRoot }
+}
+
+async function resolveReadableWorkspaceStorageRoot(
+  workspace: string,
+  storageDirRaw: string,
+): Promise<string> {
+  const requestedBase = requestedSharedStorageBase(storageDirRaw)
+  const base = await assertSecureSharedStorageBase(requestedBase)
+  const requestedRoot = join(base, workspaceStorageId(workspace))
+  const info = await lstat(requestedRoot)
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new VisionToolkitError('path', `historical workspace storage must be a real directory: ${requestedRoot}`)
+  }
+  assertSecureWorkspaceStorage(info, requestedRoot)
+  const root = await realpath(requestedRoot)
+  if (!isWithin(base, root)) {
+    throw new VisionToolkitError('path', `historical workspace storage escaped its configured root: ${requestedRoot}`)
+  }
+  return root
+}
+
 /**
- * Build the per-invocation path policy: realpath the workspace, resolve and
- * realpath the platform temp directory and allowed directories, and create
- * the output directory inside the fence.
+ * Build the per-invocation path policy: resolve workspace storage, realpath the
+ * platform temp directory and allowed directories, and create the artifact
+ * directory inside the managed root.
  * @param workspaceRaw - session workspace (or process cwd fallback).
  * @param allowedDirs - configured extra allowed roots.
- * @param outputDirRaw - configured output directory (default `.dsh-vision-toolkit/artifacts`).
+ * @param storageDirRaw - optional shared storage root.
+ * @param readableStorageDirs - previously validated shared roots retained for persisted input paths.
  * @returns the resolved policy.
  */
 export async function createPathPolicy(
   workspaceRaw: string,
   allowedDirs: readonly string[],
-  outputDirRaw?: string,
+  storageDirRaw?: string,
+  readableStorageDirs: readonly string[] = [],
 ): Promise<PathPolicy> {
-  let workspace: string
-  try {
-    workspace = await realpath(expandUserHome(workspaceRaw))
-  } catch (error) {
-    throw new VisionToolkitError('path', `workspace is not accessible: ${workspaceRaw}`, { cause: error })
-  }
+  const storage = await resolveWorkspaceStorage(workspaceRaw, storageDirRaw)
+  const { workspace } = storage
   let tempDir: string
   const tempDirectoryRaw = platformTempDirectory()
   try {
@@ -92,7 +310,16 @@ export async function createPathPolicy(
   } catch (error) {
     throw new VisionToolkitError('path', `platform temporary directory is not accessible: ${tempDirectoryRaw}`, { cause: error })
   }
-  const roots = [workspace, tempDir]
+  const roots = [workspace, tempDir, storage.root]
+  for (const raw of readableStorageDirs) {
+    if (raw === storageDirRaw) continue
+    try {
+      roots.push(await resolveReadableWorkspaceStorageRoot(workspace, raw))
+    } catch {
+      // Historical roots are read-only compatibility fences. Missing or newly
+      // unsafe roots stay unauthorized without breaking the active runtime.
+    }
+  }
   for (const raw of allowedDirs) {
     const candidate = expandUserHome(raw)
     const target = isAbsolute(candidate) ? candidate : resolve(workspace, candidate)
@@ -102,20 +329,14 @@ export async function createPathPolicy(
       throw new VisionToolkitError('path', `allowedDirs entry is not accessible: ${raw}`, { cause: error })
     }
   }
-  const outputRaw = outputDirRaw === undefined || outputDirRaw.trim().length === 0
-    ? join(workspace, '.dsh-vision-toolkit', 'artifacts')
-    : resolve(workspace, expandUserHome(outputDirRaw))
-  if (!roots.some(root => isWithin(root, outputRaw))) {
-    throw new VisionToolkitError('path', 'output directory must stay inside the workspace or an allowedDirs entry')
-  }
-  let outputDir: string
-  try {
-    await mkdir(outputRaw, { recursive: true })
-    outputDir = await realpath(outputRaw)
-  } catch (error) {
-    throw new VisionToolkitError('path', `output directory is not writable: ${outputRaw}`, { cause: error })
+  const outputDir = await managedDirectory(storage.root, join(storage.root, 'artifacts'), 'artifact directory')
+  return {
+    workspace,
+    tempDir,
+    allowedDirs: [...new Set(roots)],
+    storageRoot: storage.root,
+    outputDir,
   }
-  return { workspace, tempDir, allowedDirs: [...new Set(roots)], outputDir }
 }
 
 /**

package/src/runtime-install.ts

@@ -22,9 +22,9 @@ import {
   utimes,
   writeFile,
 } from 'node:fs/promises'
-import { createWriteStream } from 'node:fs'
+import { createWriteStream, type Dirent } from 'node:fs'
 import { homedir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { Transform } from 'node:stream'
 import { pipeline } from 'node:stream/promises'
 import { fileURLToPath } from 'node:url'
@@ -90,6 +90,7 @@ const LOCK_STALE_MS = 15 * 60 * 1000
 const LOCK_HEARTBEAT_MS = 5_000
 const WINDOWS_FILE_RETRY_ATTEMPTS = 5
 const WINDOWS_FILE_RETRY_DELAY_MS = 250
+const LEGACY_RUNTIME_GC_STALE_MS = 24 * 60 * 60 * 1000
 
 /** Absolute root of the packaged upstream snapshot. */
 export function bundledUpstreamRoot(): string {
@@ -146,6 +147,166 @@ export async function ignoreCleanupFailure(ctx: Context, label: string, path: st
   }
 }
 
+type RuntimeGarbageKind = 'managed runtime staging' | 'managed runtime quarantine' | 'bundled Python staging'
+
+interface RuntimeGarbageCandidate {
+  kind: RuntimeGarbageKind
+  lockName?: string
+  lockToken?: string
+  minimumAgeMs?: number
+  createdAtMs?: number
+  observationMarker?: string
+}
+
+function runtimeGarbageLockToken(lockBase: string): string {
+  return sha256(lockBase).slice(0, 12)
+}
+
+function managedRuntimeGarbage(name: string): RuntimeGarbageCandidate | undefined {
+  if (name.startsWith('.prepare-')) {
+    const current = /^\.prepare-([a-f0-9]{12})-[^/]{6}$/.exec(name)
+    return { kind: 'managed runtime staging', ...(current === null ? {} : { lockToken: current[1] }) }
+  }
+  const replaced = name.indexOf('.replaced-')
+  if (replaced > 0) {
+    const stamped = /^(\d{13})-/.exec(name.slice(replaced + '.replaced-'.length))
+    return {
+      kind: 'managed runtime quarantine',
+      lockName: `${name.slice(0, replaced)}.lock`,
+      minimumAgeMs: LEGACY_RUNTIME_GC_STALE_MS,
+      ...(stamped === null
+        ? { observationMarker: '.dsh-vision-toolkit-gc-observed' }
+        : { createdAtMs: Number(stamped[1]) }),
+    }
+  }
+  return undefined
+}
+
+function bundledPythonGarbage(name: string): RuntimeGarbageCandidate | undefined {
+  if (!name.startsWith('.python-bootstrap-')) return undefined
+  const current = /^\.python-bootstrap-([a-f0-9]{12})-[^/]{6}$/.exec(name)
+  return { kind: 'bundled Python staging', ...(current === null ? {} : { lockToken: current[1] }) }
+}
+
+async function runtimeLockIsActive(lockPath: string, now: number): Promise<boolean> {
+  try {
+    const info = await stat(lockPath)
+    return now - info.mtimeMs <= LOCK_STALE_MS
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    return true
+  }
+}
+
+async function garbageCollectDirectory(
+  ctx: Context,
+  parent: string,
+  classify: (name: string) => RuntimeGarbageCandidate | undefined,
+  now: number,
+): Promise<void> {
+  let entries: Dirent[]
+  try {
+    entries = await readdir(parent, { withFileTypes: true })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+    ctx.logger.warn(
+      'dsh-vision-toolkit: runtime garbage collection scan failed for %s: %s',
+      parent,
+      error instanceof Error ? error.message : String(error),
+    )
+    return
+  }
+  let activeLockTokens: Set<string> | undefined
+  const getActiveLockTokens = async (): Promise<Set<string>> => {
+    if (activeLockTokens !== undefined) return activeLockTokens
+    activeLockTokens = new Set<string>()
+    for (const lock of entries) {
+      if (
+        lock.isDirectory()
+        && lock.name.endsWith('.lock')
+        && await runtimeLockIsActive(join(parent, lock.name), now)
+      ) {
+        activeLockTokens.add(runtimeGarbageLockToken(lock.name.slice(0, -'.lock'.length)))
+      }
+    }
+    return activeLockTokens
+  }
+  let legacyCollectionSafe: boolean | undefined
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const candidate = classify(entry.name)
+    if (candidate === undefined) continue
+    const path = join(parent, entry.name)
+    if (candidate.lockName !== undefined) {
+      if (await runtimeLockIsActive(join(parent, candidate.lockName), now)) continue
+    } else if (candidate.lockToken !== undefined) {
+      if ((await getActiveLockTokens()).has(candidate.lockToken)) continue
+    } else {
+      if (legacyCollectionSafe === undefined) {
+        legacyCollectionSafe = (await getActiveLockTokens()).size === 0
+      }
+      if (!legacyCollectionSafe) continue
+      try {
+        const info = await stat(path)
+        if (now - info.mtimeMs <= LEGACY_RUNTIME_GC_STALE_MS) continue
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
+        ctx.logger.warn(
+          'dsh-vision-toolkit: runtime garbage collection inspection failed for %s: %s',
+          path,
+          error instanceof Error ? error.message : String(error),
+        )
+        continue
+      }
+    }
+    if (candidate.minimumAgeMs !== undefined) {
+      let createdAt = candidate.createdAtMs
+      if (createdAt === undefined && candidate.observationMarker !== undefined) {
+        const marker = join(path, candidate.observationMarker)
+        try {
+          createdAt = (await stat(marker)).mtimeMs
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            await writeFile(marker, `${now}\n`, { flag: 'wx' }).catch(() => {})
+          }
+          continue
+        }
+      }
+      if (createdAt === undefined) {
+        try {
+          createdAt = (await stat(path)).mtimeMs
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
+          ctx.logger.warn(
+            'dsh-vision-toolkit: runtime garbage collection inspection failed for %s: %s',
+            path,
+            error instanceof Error ? error.message : String(error),
+          )
+          continue
+        }
+      }
+      if (now - createdAt <= candidate.minimumAgeMs) continue
+    }
+    await ignoreCleanupFailure(ctx, `stale ${candidate.kind}`, path)
+  }
+}
+
+/**
+ * Opportunistically remove abandoned runtime staging and quarantine trees.
+ * Current names encode their owning runtime lock, so live preparation is
+ * skipped. Quarantines retain a 24-hour recovery window; legacy names use the
+ * same grace period and are collected only when no runtime lock is active
+ * because they cannot be associated with a specific lock.
+ */
+export async function garbageCollectRuntimeCache(
+  ctx: Context,
+  stateRoot: string,
+  now: number = Date.now(),
+): Promise<void> {
+  await garbageCollectDirectory(ctx, join(stateRoot, 'python'), managedRuntimeGarbage, now)
+  await garbageCollectDirectory(ctx, join(stateRoot, 'python-bootstrap'), bundledPythonGarbage, now)
+}
+
 export function isolatedPythonEnvironment(home: string): NodeJS.ProcessEnv {
   return {
     HOME: home,
@@ -596,7 +757,7 @@ export async function acquireBundledPython(
     const parent = dirname(root)
     await mkdir(parent, { recursive: true })
     await withWindowsTransientRetry(() => rm(root, { recursive: true, force: true }))
-    const work = await mkdtemp(join(parent, '.python-bootstrap-'))
+    const work = await mkdtemp(join(parent, `.python-bootstrap-${runtimeGarbageLockToken(basename(root))}-`))
     try {
       const archive = join(work, 'python.tar.gz')
       const extractDir = join(work, 'extract')
@@ -675,6 +836,7 @@ export async function resolveBootstrapPython(
   try {
     const stateRoot = visionToolkitStateRoot()
     await mkdir(stateRoot, { recursive: true })
+    await garbageCollectRuntimeCache(ctx, stateRoot)
     const bundled = await acquireBundledPython(ctx, stateRoot, cwd, manifestOverride, requestImpl)
     return {
       command: bundled.command,
@@ -897,6 +1059,7 @@ async function prepareManaged(
 ): Promise<PreparedUpstreamRuntime> {
   const stateRoot = visionToolkitStateRoot()
   await mkdir(stateRoot, { recursive: true })
+  await garbageCollectRuntimeCache(ctx, stateRoot)
   const cleanHome = join(stateRoot, 'home')
   await mkdir(cleanHome, { recursive: true })
   const bootstrap = await resolveBootstrapPython(ctx, config.runtime.python, cleanHome)
@@ -966,7 +1129,7 @@ async function prepareManaged(
     return prepareManaged(ctx, config, manifest)
   }
 
-  const staging = await mkdtemp(join(parent, '.prepare-'))
+  const staging = await mkdtemp(join(parent, `.prepare-${runtimeGarbageLockToken(runtimeId)}-`))
   const installEnv: NodeJS.ProcessEnv = {
     ...isolatedPythonEnvironment(cleanHome),
     UV_CACHE_DIR: join(stateRoot, 'uv-cache'),
@@ -1056,7 +1219,7 @@ async function prepareManaged(
       manager,
     }
     await writeFile(join(staging, 'runtime.json'), `${JSON.stringify(marker, null, 2)}\n`)
-    const quarantine = `${finalRoot}.replaced-${randomUUID()}`
+    const quarantine = `${finalRoot}.replaced-${Date.now()}-${randomUUID()}`
     let quarantined = false
     try {
       await withWindowsTransientRetry(() => rename(finalRoot, quarantine))